Janet 1.38.0-73334f3 Documentation
(Other Versions: 1.37.1 1.36.0 1.35.0 1.34.0 1.31.0 1.29.1 1.28.0 1.27.0 1.26.0 1.25.1 1.24.0 1.23.0 1.22.0 1.21.0 1.20.0 1.19.0 1.18.1 1.17.1 1.16.1 1.15.0 1.13.1 1.12.2 1.11.1 1.10.1 1.9.1 1.8.1 1.7.0 1.6.0 1.5.1 1.5.0 1.4.0 1.3.1 )

Arrays

Data Structures Buffers

Arrays are a fundamental 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, such as map, filter, and interpose.

Array length

The length of an array is the number of elements in the array. The last element of the array is therefore 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 of much use without being able to get and set values inside them. To get values from an array, use the in or get function. in will require an index within bounds and will throw an error otherwise. get takes an index and an optional default value. If the index is out of bounds it will return nil or the given default value. 

(def arr @[:a :b :c :d])
(in arr 1) # -> :b
(get arr 1) # -> :b
(get arr 100) # -> nil
(get arr 100 :default) # -> :default

Instead of in you can also use the array as a function with the index as an argument or call the index as a function with the array as the first argument. 

(arr 2) # -> :c
(0 arr) # -> :a

Note that a non-integer key will throw an error when using in.

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 it 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 favorites are below:

For documentation on these functions, use the doc macro in the REPL or consult the Array API.

Data Structures Buffers