bundles/org.simantics.databoard/src-isv/spec/Standard Library.mediawiki

   1 =Standard Library=
   2 There is a standard library of named datatypes. The following types are built-in in Simantics systems.
   3
   4 == Datatype==
   5 The datatype description of types themselves. This type is used when serializing types in binary file and network connections.
   6
   7  type DataType =
   8       | BooleanType  { metadata : Map(String, String) }
   9       | ByteType     { metadata : Map(String, String), unit : Optional(String), range : Optional(Range) }
  10       | IntegerType  { metadata : Map(String, String), unit : Optional(String), range : Optional(Range) }
  11       | LongType     { metadata : Map(String, String), unit : Optional(String), range : Optional(Range) }
  12       | FloatType    { metadata : Map(String, String), unit : Optional(String), range : Optional(Range) }
  13       | DoubleType   { metadata : Map(String, String), unit : Optional(String), range : Optional(Range) }
  14       | StringType   { metadata : Map(String, String), pattern : Optional(String), mimeType : Optional(String), length : Optional(String) }
  15       | RecordType   referable { metadata : Map(String, String), referable : Boolean, components : Component[] }
  16       | ArrayType    { metadata : Map(String, String), componentType : DataType, length : Optional(Range) }
  17       | MapType      { metadata : Map(String, String), keyType : DataType, valueType : DataType }
  18       | OptionalType { metadata : Map(String, String), componentType : DataType }
  19       | UnionType    { metadata : Map(String, String), components : Component[] }
  20       | VariantType  { metadata : Map(String, String) }
  21
  22
  23  type Range = { lower : Limit, upper : Limit }
  24  type Limit = Nolimit | Inclusive { value : Double } | Exclusive { value : Double } | InclusiveLong { value : Long } | ExclusiveLong { value : Long }
  25  type Component = { name : String, type : DataType }
  26  type DataTypeDefinition = { name : String, type : DataType }
  27
  28 ==Utility types==
  29 [http://java.sun.com/j2se/1.5.0/docs/api/java/util/UUID.html UUID] represents an universally unique identifier (UUID), a 128-bit value.
  30
  31   type UUID = { mostSigBits : Long, leastSigBits : Long }
  32
  33 Localized text is a map of user readable text for multiple languages.
  34 The key is [http://www.loc.gov/standards/iso639-2/englangn.html ISO-639] language code, and value is the text for that language.
  35 Default language is ''en'', it is highly encouraged to always provide english text in addition to all others.
  36   type LocalizedText = Map(String, String)
  37
  38 Void type is represented as empty record.
  39   type Void = {}
  40
  41 URI type is a textual reference.
  42   type URI = String
  43
  44 ==Time Types==
  45 These great time types are borrowed from JSR-310.
  46
  47 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/Instant.html Instant] is an instantaneous point on the time-line.
  48 It represents nano seconds since epoch (1970-01-01T00:00:00Z) ignoring leap seconds.
  49 In order to represent the data a 96 bit number is required. To achieve this the data is stored as seconds, measured using a long, and nanoseconds, measured using an int. The nanosecond part will always be between 0 and 999,999,999 representing the nanosecond part of the second.
  50
  51   type Instant = {
  52       seconds : Long,
  53       nanoSeconds : Integer(range=[0..999999999])
  54   }
  55
  56 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/Duration.html Duration] is the time between two instants on the time-line.
  57 In order to represent the data a 96 bit number is required. To achieve this the data is stored as seconds, measured using a long, and nanoseconds, measured using an int.
  58 The nanosecond part will always be between 0 and 999,999,999 representing the nanosecond part of the second.
  59 For example, the negative duration of PT-0.1S is represented as -1 second and 900,000,000 nanoseconds.
  60
  61   type Duration = {
  62       seconds : Long,
  63       nanoSeconds : Integer(range=[0..999999999])
  64   }
  65
  66 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/LocalDate.html LocalDate] is a date without a time zone in the ISO-8601 calendar system, such as '2007-12-03'.
  67
  68   type LocalDate = {
  69       year : Integer,
  70       monthOfYear : Integer(range=[1..12]),
  71       dayOfMonth : Integer(range=[1..31])
  72   }
  73
  74 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/LocalTime.html LocalTime] is a time without time zone in the ISO-8601 calendar system, such as '10:15:30'.
  75 This type stores all time fields, to a precision of nanoseconds. It does not store or represent a date or time zone. Thus, for example, the value "13:45.30.123456789" can be stored in a LocalTime.
  76
  77   type LocalTime = {
  78       hourOfDay : Integer(range=[0..23]),
  79       minuteOfHour : Integer(range=[0..59]),
  80       secondOfMinute : Integer(range=[0..59]),
  81       nanoOfSecond : Integer(range=[0..999999999])
  82   }
  83
  84 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/LocalDateTime.html LocalDateTime] is a date-time without a time zone in the ISO-8601 calendar system, such as '2007-12-03T10:15:30'.
  85 This type stores all date and time fields, to a precision of nanoseconds. It does not store or represent a time zone. Thus, for example, the value "2nd October 2007 at 13:45.30.123456789" can be stored in an LocalDateTime.
  86
  87   type LocalDateTime = {
  88       year : Integer,
  89       monthOfYear : Integer(range=[1..12]),
  90       dayOfMonth : Integer(range=[1..31]),
  91       hourOfDay : Integer(range=[0..23]),
  92       minuteOfHour : Integer(range=[0..59]),
  93       secondOfMinute : Integer(range=[0..59]),
  94       nanoOfSecond : Integer(range=[0..999999999])
  95   }
  96
  97 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/ZonedDateTime.html ZonedDateTime] is a date-time with a time zone in the ISO-8601 calendar system, such as '2007-12-03T10:15:30+01:00 Europe/Paris'. This type stores all date and time fields, to a precision of nanoseconds, as well as a time zone and zone offset. Thus, for example, the value "2nd October 2007 at 13:45.30.123456789 +02:00 in the Europe/Paris time zone" can be stored in a ZonedDateTime. The purpose of storing the time zone is to distinguish the ambiguous case where the local time-line overlaps, typically as a result of the end of daylight time.
  98   type ZonedDateTime = {
  99      date : LocalDate,
 100      time : LocalTime,
 101      zone : TimeZone
 102   }
 103
 104 [https://jsr-310.dev.java.net/nonav/doc-2010-02-09/javax/time/calendar/TimeZone.html TimeZones] are geographical regions where the same rules for time apply. The rules are defined by governments and change frequently.
 105
 106 Each group defines a naming scheme for the regions of the time zone. The format of the region is specific to the group. For example, the 'TZDB' group typically use the format {area}/{city}, such as 'Europe/London'.
 107
 108 Each group typically produces multiple versions of their data. The format of the version is specific to the group. For example, the 'TZDB' group use the format {year}{letter}, such as '2009b'.
 109
 110 In combination, a unique ID is created expressing the time-zone, formed from {groupID}:{regionID}#{versionID}.
 111
 112 The version can be set to an empty string. This represents the "floating version". The floating version will always choose the latest applicable set of rules. Applications will probably choose to use the floating version, as it guarantees usage of the latest rules.
 113
 114 In addition to the group/region/version combinations, TimeZone can represent a fixed offset. This has an empty group and version ID. It is not possible to have an invalid instance of a fixed time zone.
 115
 116 The purpose of capturing all this information is to handle issues when manipulating and persisting time zones. For example, consider what happens if the government of a country changed the start or end of daylight savings time. If you created and stored a date using one version of the rules, and then load it up when a new version of the rules are in force, what should happen? The date might now be invalid, for example due to a gap in the local time-line. By storing the version of the time zone rules data together with the date, it is possible to tell that the rules have changed and to process accordingly.
 117
 118 TimeZone merely represents the identifier of the zone.
 119
 120   type TimeZone = { zoneId : String }
 121
 122