#### Janet 1.10.1-9cfc3d9 Documentation

(Other Versions:
1.9.1
1.8.1
1.7.0
1.6.0
1.5.1
1.5.0
1.4.0
1.3.1
)

# Data Structures

Once you have a handle on functions and the primitive value types, you may be wondering how to work with collections of things. Janet has a small number of core data structure types that are very versatile. Tables, structs, arrays, tuples, strings, and buffers, are the 6 main built-in data structure types. These data structures can be arranged in a useful table describing their relationship to each other.

Interface | Mutable | Immutable |
---|---|---|

Indexed | Array | Tuple |

Dictionary | Table | Struct |

Bytes | Buffer | String (Symbol, Keyword) |

Indexed types are linear lists of elements than can be accessed in constant time with an integer index. Indexed types are backed by a single chunk of memory for fast access, and are indexed from 0 as in C. Dictionary types associate keys with values. The difference between dictionaries and indexed types is that dictionaries are not limited to integer keys. They are backed by a hash table and also offer constant time lookup (and insertion for the mutable case). Finally, the 'bytes' abstraction is any type that contains a sequence of bytes. A 'bytes' value or byteseq associates integer keys (the indices) with integer values between 0 and 255 (the byte values). In this way, they behave much like arrays and tuples. However, one cannot put non-integer values into a byteseq.

The table below summarizes the big-O complexity of various operations and other information on the built-in data structures. All primitive operations on data structures will run in constant time regardless of the number of items in the data structure.

Data Structure | Access | Insert/Append | Delete | Space Complexity | Mutable |
---|---|---|---|---|---|

Array * | O(1) | O(1) | O(1) | O(n) | Yes |

Tuple | O(1) | - | - | O(n) | No |

Table | O(1) | O(1) | O(1) | O(n) | Yes |

Struct | O(1) | - | - | O(n) | No |

Buffer | O(1) | O(1) | O(1) | O(n) | Yes |

String/Keyword/Symbol | - | - | - | O(n) | No |

*: Append and delete for an array correspond to `array/push`

and
`array/pop`

. Removing or inserting elements at random indices will run in
`O(n)`

time where `n`

is the number of elements in the array.

```
(def mytuple (tuple 1 2 3))
(def myarray @(1 2 3))
(def myarray (array 1 2 3))
(def mystruct {
:key "value"
:key2 "another"
1 2
4 3})
(def another-struct
(struct :a 1 :b 2))
(def my-table @{
:a :b
:c :d
:A :qwerty})
(def another-table
(table 1 2 3 4))
(def my-buffer @"thisismutable")
(def my-buffer2 @``This is also mutable``)
```

To read the values in a data structure, use the `get`

function. The first
parameter is the data structure itself, and the second parameter is the key. An
optional third paramter can be used to specify a default if the value is not
found.

```
(get @{:a 1} :a) # -> 1
(get {:a 1} :a) # -> 1
(get @[:a :b :c] 2) # -> :c
(get (tuple "a" "b" "c") 1) # -> "b"
(get @"hello, world" 1) # -> 101
(get "hello, world" 0) # -> 104
(get {:a :b} :a) # -> :b
(get {:a :b} :c :d) # -> :d
```

Similar to the `get`

function and added in v1.5.0, the `in`

function
also get values contained in a data structure but will throw errors on bad keys
to arrays, tuple, and string-likes. You should prefer `in`

going forward as
it can be used to better detect errors. For tables and structs, `in`

behaves identically to `get`

.

```
(in @[:a :b :c] 2) # -> :c
(in @[:a :b :c] 3) # -> raises error
```

To update a mutable data structure, use the `put`

function. It takes 3
arguments, the data structure, the key, and the value, and returns the data
structure. The allowed types keys and values depend on the data structure passed
in.

```
(put @[] 100 :a)
(put @{} :key "value")
(put @"" 100 92)
```

Note that for arrays and buffers, putting an index that is outside the length of
the data structure will extend the data structure and fill it with `nil`

s
in the case of the array, or `0`

s in the case of the buffer.

The last generic function for all data structures is the `length`

function.
This returns the number of values in a data structure (the number of keys in a
dictionary type).