Janet 1.17.1-e1c4fc2 Documentation
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
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,
(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 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]
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 will require an index within bounds and will throw an error
get requires 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
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
(arr 2) # -> :c (0 arr) # -> :a
Note that a non-integer key will throw an error when using
To set values in an array, use either the
put function or 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)
(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 the last element in stack but does not remove it. Returns
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.