Janet 1.4.0-655d4b3 Documentation
(Other Versions: 1.4.0 1.3.1)

Arrays

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.

Array Length

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 the (length x) function.

Creating Arrays

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 values inside.

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]

Getting values

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.

Setting values

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)

Appends a value to the end of the array and returns the array.

(array/pop stack)

Removes the last value from stack and returns it. If the array is empty, returns nil.

(array/peek stack)

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 array/ namespace 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.