git.m6w6.name Git - awesomized/ext-ion/blob - docs/tutorial/: Tutorial/:3. Standard Datatypes.md

   1 # Standard Datatypes
   2
   3 ION supports many of PHP's data types:
   4
   5 ## Nulls
   6
   7 Additonally to the plain and simple `NULL`, ION can attach a type to `NULL` values.
   8
   9 ```php
  10 <?php
  11
  12 $writer = new ion\Writer\Stream\Writer(STDOUT);
  13 $writer->writeNull();
  14 $writer->writeTypedNull(ion\Type::Int);
  15 $writer->writeTypedNull(ion\Type::String);
  16 $writer->flush();
  17
  18 /*
  19         null
  20         null.int
  21         null.string
  22 */
  23
  24 ?>
  25 ```
  26
  27 ## Booleans
  28
  29 The bool type does not need a lot of explanation:
  30
  31 ```php
  32 <?php
  33
  34 $writer->writeBool(true);
  35 $writer->writeBool(false);
  36 $writer->flush();
  37
  38 /*
  39         true
  40         false
  41 */
  42
  43 ?>
  44 ```
  45
  46 ## Integers
  47
  48 The int type comprises signed integers of arbitrary size.
  49
  50 ```php
  51 <?php
  52
  53 $writer->writeInt(123);
  54 $writer->writeInt("12345678901234567890");
  55 $writer->flush();
  56
  57 /*
  58         123
  59         12345678901234567890
  60 */
  61
  62 ?>
  63 ```
  64
  65 In ION-Text, underscores are allowed to separate digits:
  66
  67 ```php
  68 <?php
  69
  70 $reader = new ion\Reader\Buffer\Reader("-123_456_789");
  71 $reader->next();
  72 var_dump($reader->getType());
  73 var_dump($reader->readInt());
  74
  75 /*
  76         enum(ion\Type::Int)
  77         int(-123456789)
  78 */
  79
  80 ?>
  81 ```
  82
  83 Hexadecimal as well as binary notation are supported, too:
  84
  85 ```php
  86 <?php
  87
  88 $reader = new ion\Reader\Buffer\Reader("0xdead_beef");
  89 $reader->next();
  90 var_dump($reader->readInt());
  91
  92 /*
  93         int(3735928559)
  94 */
  95
  96 $reader = new ion\Reader\Buffer\Reader("0b10000100_11001001");
  97 $reader->next();
  98 var_dump($reader->readInt());
  99
 100 /*
 101         int(33993)
 102 */
 103
 104 ?>
 105 ```
 106
 107 ## Reals
 108
 109 Ion supports both binary and lossless decimal encodings of real numbers as, respectively, types `float` and `decimal`. In the text format, `float` values are denoted much like the decimal formats in C or Java; `decimal` values use `d` instead of `e` to start the exponent.
 110
 111 Reals without an exponent are treated as decimal. As with JSON, extra leading zeros are not allowed. Digits may be separated with an underscore.
 112
 113 ### Floats
 114
 115 ```php
 116 <?php
 117
 118 var_dump(ion\serialize(0.123));
 119
 120 /*
 121         string(25) "0.12299999999999999822e+0"
 122 */
 123
 124 var_dump(ion\unserialize("[0.123e, 123e-3]"));
 125
 126 /*
 127   array(2) {
 128     [0]=>
 129     float(0.123)
 130     [1]=>
 131     float(0.123)
 132   }
 133 */
 134
 135 ?>
 136 ```
 137
 138 ### Decimals
 139
 140 ```php
 141 <?php
 142
 143 var_dump(ion\serialize(new ion\Decimal("0.123")));
 144
 145 /*
 146         string(5) "0.123"
 147 */
 148
 149 var_dump(ion\unserialize("[0.123d0, 123d-3]"));
 150
 151 /*
 152   array(2) {
 153     [0]=>
 154     object(ion\Decimal)#8 (2) {
 155       ["number"]=>
 156       string(5) "0.123"
 157       // ...
 158     }
 159     [1]=>
 160     object(ion\Decimal)#11 (2) {
 161       ["number"]=>
 162       string(5) "0.123"
 163       // ...
 164     }
 165   }
 166 */
 167
 168 ?>
 169 ```
 170
 171 ## Strings
 172
 173 Ion strings are Unicode character sequences of arbitrary length.
 174
 175 In the text format, strings are delimited by double-quotes and follow common backslash-escape conventions (see [official spec](https://amzn.github.io/ion-docs/docs/spec.html#escapess)). The binary format always uses UTF-8 encoding.
 176
 177 ```php
 178 <?=
 179
 180 ion\serialize([
 181   "abc", "new
 182 line"
 183 ]);
 184
 185 /*
 186         ["abc", "new\nline"]
 187 */
 188
 189 ?>
 190 ```
 191
 192 ### Long Strings
 193
 194 The text format supports an alternate syntax for “long strings”, including those that break across lines. Sequences bounded by three single-quotes (''') can cross multiple lines and still count as a valid, single string. In addition, any number of adjacent triple-quoted strings are concatenated into a single value.
 195
 196 The concatenation happens within the Ion text parser and is neither detectable via the data model nor applicable to the binary format. Note that comments are always treated as whitespace, so concatenation still occurs when a comment falls between two long strings.
 197
 198 ```php
 199 <?php
 200
 201 var_dump(ion\unserialize("
 202 '''
 203   here are
 204   several new
 205   lines
 206 '''
 207 "));
 208
 209 /*
 210 string(35) "
 211   here are
 212   several new
 213   lines
 214 "
 215 */
 216
 217 ?>
 218 ```
 219
 220 ## Containers
 221
 222 Ion defines three container types: structures, lists, and S-expressions. These types are defined recursively and may contain values of any Ion type.
 223
 224 ### Lists
 225
 226 Lists are ordered collections of values. The contents of the list are heterogeneous (that is, each element can have a different type). In the text format, lists are bounded by square brackets and elements are separated by commas.
 227
 228 ```php
 229 <?=
 230
 231 ion\serialize([1, "yes", null]);
 232
 233 /*
 234   [1,"yes",null]
 235 */
 236
 237 ?>
 238 ```
 239
 240 ### Structures
 241
 242 Structures are *unordered* collections of name/value pairs. The names are symbol tokens, and the values are unrestricted. Each name/value pair is called a field.
 243
 244 In the text format, structures are wrapped by curly braces, with a colon between each name and value, and a comma between the fields. For the purposes of JSON compatibility, it’s also legal to use strings for field names, but they are converted to symbol tokens by the parser.
 245
 246 ```php
 247 <?=
 248
 249 ion\serialize([
 250   "outlaw",
 251   "key" => "value",
 252   "obj" => (object)["key" => "value"]
 253 ]);
 254
 255 /*
 256         {'0':"outlaw",key:"value",obj:o::{key:"value"}}
 257 */
 258
 259 ?>
 260 ```
 261
 262 ```php
 263 <?php
 264
 265 var_dump(ion\unserialize(
 266   '{\'0\':"outlaw",key:"value",obj:o::{key:"value"}}'
 267 ));
 268
 269 /*
 270   array(3) {
 271     [0]=>
 272     string(6) "outlaw"
 273     ["key"]=>
 274     string(5) "value"
 275     ["obj"]=>
 276     object(stdClass)#10 (1) {
 277       ["key"]=>
 278       string(5) "value"
 279     }
 280   }
 281 */
 282
 283 ?>
 284 ```
 285
 286 ---
 287
 288 ## Next up
 289
 290 * [Special Datatypes](ion/:%20Tutorial/:4.%20Special%20Datatypes)