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,
(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
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
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,
to the new value.
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.
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 Core Library API.