Tuples

Structs Destructuring

Tuples are immutable, sequential types that are similar to arrays. They are represented in source code with either parentheses or brackets surrounding their items. Note that Janet differs from traditional Lisps here, which commonly use the term "lists" to describe forms wrapped in parentheses. Like all data structures, tuple contents can be retrieved with the get function and their length retrieved with the length function.

The two most common ways to create a tuple are using the literal form with bracket characters [] or calling the tuple function directly.

# Four ways to create the same tuple:

(def mytup1 [1 2 3 4])       # using bracket literals
(def mytup2 (tuple 1 2 3 4)) # using the (tuple) function

# the quote prevents form evaluation and returns the tuple directly
(def mytup3 '(1 2 3 4))

# quasiquote works similarly to quote, but allows for some
# forms to be evaluated inside via the , character
(def mytup4 ~(1 2 3 ,(+ 2 2)))

# these all result in the same tuple:
(assert (= mytup1 mytup2 mytup3 mytup4)) # true

As table keys

Tuples can be used as table keys because two tuples with the same contents are considered equal:

(def points @{[0 0] "A"
              [1 3] "B"
              [7 5] "C"})

(get points [0 0])       # "A"
(get points (tuple 0 0)) # "A"
(get points [1 3])       # "B"
(get points [8 5])       # nil (ie: not found)

Sorting tuples

Tuples can also be used to sort items. When sorting tuples via the < or > comparators, the first elements are compared first. If those elements are equal, we move on to the second element, then the third, and so on. We could use this property of tuples to sort all kind of data, or sort one array by the contents of another array.

(def inventory [
 ["ermie" 1]
 ["banana" 18]
 ["cat" 5]
 ["dog" 3]
 ["flamingo" 23]
 ["apple" 2]])

(def sorted-inventory (sorted inventory))

(each [item n] sorted-inventory (print item ": " n))
# apple: 2
# banana: 18
# cat: 5
# dog: 3
# ermie: 1
# flamingo: 23

Bracketed tuples

Under the hood, there are two kinds of tuples: bracketed and non-bracketed. We have seen above that bracket tuples are used to create a tuple with [] characters (ie: a tuple literal). The way a tuple literal is interpreted by the compiler is one of the few ways in which bracketed tuples and non-bracketed tuples differ:

Bracket tuples are interpreted as a tuple constructor rather than a function call by the compiler.
When printed via pp, bracket tuples are printed with square brackets instead of parentheses.
When passed as an argument to tuple/type, bracket tuples will return :brackets instead of :parens.

In all other ways, bracketed tuples behave identically to normal tuples. It is not recommended to use bracketed tuples for anything outside of macros and tuple constructors (ie: tuple literals).

More functions

Most functions in the core library that work on arrays also work on tuples, or have an analogous function for tuples. See the Tuple API for a list of functions that operate on tuples.