Janet 1.1.0-dev Documentation
Arrays are a central datatype in Janet. Arrays are values that contain a sequence of other values, indexed from 0. Arrays are also mutable, meaning that values can be added or removed in place. Many functions in the Janet core library will also create arrays.
The length of an array is the number of elements in the array. The last element
of the array is therefor at index length - 1. To get the length of an array, use
(length x) function.
There are many ways to create arrays in Janet, but the easiest is the array literal.
(def my-array @[1 2 3 "four"]) (def my-array2 @(1 2 3 "four"))
An array literal begins with an at symbol,
@, followed by
square brackets or parentheses with 0 or more
To create an empty array that you will fill later, use the `(array/new capacity)` function. This creates an array with a reserved capacity for a number of elements. This means that appending elements to the array will not re-allocate the memory in the array. Using an empty array literal would not pre-allocate any space, so the resulting operation would be less efficient.
(def arr (array/new 4)) arr # -> @ (put arr 0 :one) (put arr 1 :two) (put arr 2 :three) (put arr 3 :four) arr # -> @[:one :two :three :four]
Arrays are not much use without being able to get and set values inside them. To get values from an array, use the `get` function or call the array as a function with the index as an argument. You can also call the index as a function with the array as the first argument.
(def arr @[:a :b :c :d]) (get arr 1) # -> :b (arr 2) # -> :c (0 arr) # -> :a (arr 100) # -> nil
Note that indexing outside of the array bounds will return nil. A non-integer key, however, will throw an error.
To set values in an array, use either the `put` function or the `set` special. The put function is a function that allows putting values in any associative data structure. This means that can associate keys with values for arrays, tables, and buffers. If an index is given that is past the end of the array, the array is first padded with nils so that it is large enough to accommodate the new element.
(def arr @) (put arr 0 :hello) # -> @[:hello] (put arr 2 :hello) # -> @[:hello nil :hello] (set (arr 0) :hi) # -> :hi arr # -> @[:hi nil :hello]
The syntax for the set special is slightly different, as it is meant to mirror the syntax for getting an element out of a data structure. Another difference is that while `put` returns the data structure, `set` evaluates to the new value.
Using an Array as a Stack
Arrays can also be used for implementing efficient stacks. The Janet core library provides three functions that can be used to treat an array as a stack.
(array/push stack value)
(array/push stack value)
Appends a value to the end of the array and returns the array.
Removes the last value from stack and returns it. If the array is empty, returns nil.
Returns the last element in stack but does not remove it. Returns nil if the stack is empty.
More array functions
There are several more functions in the
and many more functions that create or manipulate arrays in the core
library. A short list of the author's favorite are below:
For documentation on these functions, use the
doc macro in the REPL or
consult the Array API.