Sequences
Sequences hold a sequence of data, as the name implies. Clarity provides three different kinds of sequences: buffers, strings, and lists.
Buffers
Buffers are unstructured data of a fixed maximum length. They always start with
the prefix 0x followed by a
hexadecimal string. Each byte is
thus represented by two so-called
hexits.
0x68656c6c6f21
The buffer above spells out "hello!". (Copy and paste it to this page to verify.)
Strings
A string is a sequence of characters. These can be defined as
ASCII strings or
UTF-8 strings. ASCII strings may only
contain basic Latin characters whilst UTF-8 strings can contain fun stuff like
emoji. Both strings are enclosed in double-quotes (") but UTF-8 strings are
also prefixed by a u. Just like buffers, strings always have a fixed maximum
length in Clarity.
ASCII:
"This is an ASCII string"
UTF-8:
u"And this is an UTF-8 string \u{1f601}"
You can use strings to pass names and messages.
Lists
Lists are sequences of fixed length that contain another type. Since types cannot mix, a list can only contain items of the same type. Take this list of signed integers for example:
(list 4 8 15 16 23 42)
As you can see, a list is constructed using the list function. Here is a list
of ASCII strings:
(list "Hello" "World" "!")
And just for completeness, here is a list that is invalid due to mixed types:
(list u5 10 "hello") ;; This list is invalid.
Lists are very useful and make it a lot easier to perform actions in bulk. (For
example, sending some tokens to a list of people.) You can iterate over a list
using the map or fold functions.
map applies an input function to each element and returns a new list with the
updated values. The not function inverts a boolean (true becomes false and
false becomes true). We can thus invert a list of booleans like this:
(map not (list true true false false))
fold applies an input function to each element of the list and the output
value of the previous application. It also takes an initial value to use for the
second input for the first element. The returned result is the last value
returned by the final application. This function is also commonly called
reduce, because it reduces a list to a single value. We can use fold to sum
numbers in a list by applying the + (addition) function with an initial value
of u0:
(fold + (list u1 u2 u3) u0)
The snippet above can be expanded to the following:
(+ u3 (+ u2 (+ u1 u0)))
Working with sequences
Length
Sequences always have a specific length, which we can retrieve using the len
function.
A buffer (remember that each byte is represented as two hexits):
(len 0x68656c6c6f21)
A string:
(len "How long is this string?")
And a list:
(len (list 4 8 15 16 23 42))
Retrieving elements
They also allow you to extract elements at a particular index. The following takes the fourth element from the list. (Counting starts at 0.)
(element-at (list 4 8 15 16 23 42) u3)
You can also do the reverse and find the index of a particular item in a
sequence. We can search the list to see if it contains the value 23.
(index-of (list 4 8 15 16 23 42) 23)
And we get (some u4), indicating there is a value of 23 at index four. The
attentive might now be wondering, what is this "some"? Read on and all will be
revealed in the next section.