bundles/org.simantics.databoard/src-isv/spec/Type System.mediawiki

   1 =Type-system=
   2 DataBoard is a software library built upon a simple but well formulated and expressive type system. The design is a compromise of expression power, advanced functions, and performance. In total there are 13 types; 7 primitive types, and 6 structural.
   3
   4 ; Primitive Types
   5 {| border="1" cellpadding="3" cellspacing="0" align="center"
   6 |'''#'''
   7 |'''Datatype'''
   8 |'''Description'''
   9 |- style="background-color: #f9f9f9;"
  10 |0||Boolean||true and false
  11 |- style="background-color: #ffffff;"
  12 |1||Byte||signed 8-bit integers
  13 |- style="background-color: #f9f9f9;"
  14 |2||Integer||signed 32-bit integers
  15 |- style="background-color: #ffffff;"
  16 |3||Long||signed 64-bit integers
  17 |- style="background-color: #f9f9f9;"
  18 |4||Float||32-bit IEEE 754 floating point numbers
  19 |- style="background-color: #ffffff;"
  20 |5||Double||64-bit IEEE 754 floating point numbers
  21 |- style="background-color: #f9f9f9;"
  22 |6||String||Unicode strings of arbitrary length
  23 |}
  24
  25 ; Structural types
  26 {| border="1" cellpadding="3" cellspacing="0" align="center"
  27 |'''#'''||'''Datatype'''||'''Description'''
  28 |- style="background-color: #f9f9f9;"
  29 |7||Record||Contains constant set of fields
  30 |- style="background-color: #ffffff;"
  31 |8||Array||An ordered collection of values
  32 |- style="background-color: #f9f9f9;"
  33 |9||Map||An object that maps keys to values
  34 |- style="background-color: #ffffff;"
  35 |10||Optional||A container that either has or does not have a value
  36 |- style="background-color: #f9f9f9;"
  37 |11||Union||A choise between component types.
  38 |- style="background-color: #ffffff;"
  39 |12||Variant||An object that can contain a value of any type
  40 |}
  41
  42 ==Meta-Data==
  43 Annotations add meta data to a base type. They determine the set of valid values.
  44
  45 Different primitive types and datatype constructions support different annotations:
  46 {| border="1" cellpadding="3" cellspacing="0" align="center"
  47 |'''types/constructor'''
  48 |'''annotations supported'''
  49 |- style="background-color: #f9f9f9;"
  50 |Byte, Integer, Long, Float, Double
  51 |range, unit
  52 |-
  53 |String
  54 |pattern, mimeType, length
  55 |- style="background-color: #f9f9f9;"
  56 |Array
  57 |length
  58 |-
  59 |Record
  60 |referable
  61 |}
  62
  63 ==Record==
  64 A record type is a sequence of components. Each component has a type and a name. The name is a unrestricted Unicode string.
  65 The set of (well-formed/valid) values of the record type is a cartesian product of the (well-formed/valid) values of the component types. Recursion in Datatypes is based on referable records.
  66
  67 ==Union==
  68 A union type is defined with a sequence of components similarly as a record type.
  69 The set of (well-formed/valid) values of the union type is disjoint union of the (well-formed/valid) values of the component types.
  70
  71 ==Array==
  72 An array type is constructed with a base type. Its values are finite sequences of the base type.
  73
  74 ==Map==
  75 A map type is constructed with a base type of key and value. Its values are finite sequence of entries of key-value pairs. Keys may not refer even indirectly to the map itself.
  76
  77 ==Variants==
  78 Variant consists of type and a value.
  79
  80 ==Sub-typing==
  81 Datatypes do not support explicit subtyping (most of its uses can be replaced by using Union-constructor),
  82 but it can be defined implicitly: a datatype
  83 A is a ''subtype'' of B, if all valid values of A are also valid values of B. Primitive
  84 datatypes and type constructors are defined so that if A is a subtype of B then
  85 they have the same set of well-formed values.
  86
  87 ==Validation==
  88 ''Datatype'' is a mathematical object that is associated with two sets: ''well-formed''
  89 and ''valid'' values, where the former set contains the latter. A datatype
  90 is ''basic'' if its well-formed values are all valid. ''Primitive datatypes'' are basic data
  91 types that are completely defined by their set of valid values. There is only a
  92 finite set of primitive datatypes. ''Structured datatypes'' are constructed from other
  93 types.
  94
  95 The distinction between well-formed and valid values can be demonstrated
  96 with the following example: <code>"http://www.simantics.org/"</code> is a valid value of
  97 datatype URI. <code>"foo::bar"</code> is not a valid URI, but it is well-formed i.e. it can
  98 be represented in all contexts where URIs are used. The number 34 is not a
  99 well-formed URI. Similarly, if Probability is defined as a floating point number between 0 and 1,
 100 then 1.5 is well-formed but not a valid value of <code>Probability</code>.
 101
 102 ==Comparison==
 103 Two data values can be compared and put into order. There is a rule for each type. Structural values are compared in in-order.
 104 {| border="1" cellpadding="3" cellspacing="0" align="center"
 105 |'''Type'''
 106 |'''Compare-function'''
 107 |- style="background-color: #f9f9f9;"
 108 |RecordType
 109 |Field by field in order*
 110 |-
 111 |UnionType
 112 |by tag, if equals then by value. '''DataTypes''' have the following order: ArrayType, BooleanType, ByteType, IntegerType, LongType, FloatType, DoubleType, OptionalType, RecordType, StringType, UnionType, VariantType, MapType
 113 |- style="background-color: #f9f9f9;"
 114 |NumberType
 115 |compare values
 116 |-
 117 |ArrayType
 118 |compare lengths, then elements
 119 |- style="background-color: #f9f9f9;"
 120 |OptionalType
 121 |Compare ''HasValue'', then ''Value''
 122 |-
 123 |StringType
 124 |Case-sensitive String compare
 125 |- style="background-color: #f9f9f9;"
 126 |BooleanType
 127 |zero if values are the same; a positive value if the first value represents true and the second false; a negative value if the first is false and send true
 128 |-
 129 |VariantType
 130 |compare type, then value
 131 |- style="background-color: #f9f9f9;"
 132 |MapType
 133 |1. Compare Sizes, 2. Eliminate method : pair comparison of highest entries. Take highest key entries of both maps. Compare key, compare value. If equal go to the next entry, else use the compare value of (key then value).
 134 |}
 135
 136 ==Default Value==
 137 There is a default value specified for all datatypes.
 138
 139 {| border="1" cellpadding="3" cellspacing="0" align="center"
 140 |'''Type'''
 141 |'''Default Value'''
 142 |- style="background-color: #f9f9f9;"
 143 |RecordType
 144 |Each field according to type.
 145 |-
 146 |UnionType
 147 |Tag 0 with default value of the composite type.
 148 |- style="background-color: #f9f9f9;"
 149 |Byte, Integer, Long, Float, Double
 150 |0 or min limit if range exists.
 151 |-
 152 |MapType
 153 |no entries
 154 |- style="background-color: #f9f9f9;"
 155 |Array
 156 |Minimum number of entries where each entry has the default value of the composite type.
 157 |-
 158 |OptionalType
 159 |No value.
 160 |- style="background-color: #f9f9f9;"
 161 |String
 162 |"" or minimum value if pattern exists
 163 |-
 164 |Boolean
 165 |false
 166 |- style="background-color: #f9f9f9;"
 167 |Variant
 168 |{} : void
 169 |}
 170
 171 ==Hash Function==
 172 There is a hash function specified for each type of value. The result is a 32-bit integer.
 173
 174 {| border="1" cellpadding="3" cellspacing="0" align="center"
 175 |'''Type'''
 176 |'''Hash-function'''
 177 |- style="background-color: #f9f9f9;"
 178 |Boolean
 179 |true=1231, false=1237
 180 |-
 181 |Integer
 182 |value
 183 |- style="background-color: #f9f9f9;"
 184 |''Long''
 185 |lower 32-bits ^ higher 32-bits
 186 |-
 187 |Float
 188 |''IEEE 754 floating-point "single format" bit layout'' as is.
 189 |- style="background-color: #f9f9f9;"
 190 |''Double''
 191 |lower 32-bits ^ higher 32-bits of ''IEEE 754 floating-point "double format" bit layout.''
 192 |-
 193 |Optional
 194 |no value = 0, else <tt>hash(value)</tt>
 195 |- style="background-color: #f9f9f9;"
 196 |Array
 197 |<tt>int result = 1; for (int element : array) result = 31 * result + hash(element);</tt>
 198 |-
 199 |Record
 200 |<tt>int result = 3; for (field : record) result = 31 * result + hash(field)*;</tt>
 201 |- style="background-color: #f9f9f9;"
 202 |Variant
 203 |<tt>hash(type) + hash(value)</tt>
 204 |-
 205 |Union
 206 |<tt>tag + hash(value)</tt>
 207 |- style="background-color: #f9f9f9;"
 208 |Map
 209 |<tt>int result = 0; for (entry : map) result += hash(key) ^ hash(value);</tt>
 210 |-
 211 |Byte
 212 |value
 213 |}
 214
 215  *) In case of recursion, where the hash-function enters an referable data value a second/consecutive time,
 216     0 is considered as the hash value.
 217
 218
 219
 220