Collections

Fate supports two types of collections: [LIST], which are basic, unordered lists; and [SET], which are ordered lists, but only useable with [COMPARABLE] elements.

ADDING A MEMBER

(list:add_element! [C0 = X COMPUTATION*] ... [CN = X COMPUTATION*] [X LIST REFERENCE])
(set:add_element! [C0 = X COMPUTATION*] ... [CN = X COMPUTATION*] [X SET REFERENCE])

Adds C0 … CN to the [X LIST] or [X SET] collection reference. If the collection is a [LIST], the new members are added at the end of the list, in order (meaning that the list then ends with CN). Note that [COMPUTATION*] does not support use of the variable shorthand if this is a collection of strings or text.

ADDING A MEMBER AT INDEX

(list:add_element_at! [INT] [X COMPUTATION*] [X LIST REFERENCE])

Adds [COMPUTATION*] to [X LIST REFERENCE] at index [INT]. If [INT] is less than 0, the element is added at the start of the list, and if [INT] is greater or equal to the size of the list, the element is added at the end of the list. Note that [COMPUTATION*] does not support use of the variable shorthand if this is a collection of string or text.

ADDING MEMBERS

(list:add_all_elements! [X COLLECTION] [X LIST REFERENCE])
(set:add_all_elements! [X COLLECTION] [X SET REFERENCE])

Adds all the elements of [COLLECTION] to the [X LIST] or [X SET] collection reference. In the case of [X LIST], the new members are added at the end of the list.

EMPTYING COLLECTIONS

(list:clear! [LIST REFERENCE])
(set:clear! [SET REFERENCE])

Removes all members of the [LIST] or [SET] collection reference.

REMOVING MEMBER

(list:remove! [X COMPUTATION*] [X LIST REFERENCE])
(set:remove! [X COMPUTATION*] [X SET REFERENCE])

Removes the first member of the [X LIST] or [X SET] collection reference equal to [COMPUTATION]. Note that [COMPUTATION*] does not support use of the variable shorthand if this is a collection of string or text.

REMOVING MEMBERS

(list:remove_all! [X COMPUTATION*] [X LIST REFERENCE])
(set:remove_all! [X COMPUTATION*] [X SET REFERENCE])

Removes all values equal to [COMPUTATION] from the [X LIST] or [X SET] collection reference. Note that [COMPUTATION*] does not support use of the variable shorthand if this is a collection of string or text.

REMOVING AT INDEX

(list:remove_at! [INT] [LIST REFERENCE])
(set:remove_at! [INT] [SET REFERENCE])

Removes from the collection reference the element at index [INT].

REVERSING LISTS

(list:reverse! [LIST REFERENCE])

Reverses the order of the members of [LIST REFERENCE].

FILTER ELEMENTS

(list:filter! [LAMBDA BOOL (X)] [X LIST REFERENCE])
(set:filter! [LAMBDA BOOL (X)] [X SET REFERENCE])
Modifies the collection reference so that only the elements for which [LAMBDA BOOL (X)] returns true remain.

FILTER ELEMENTS (INDEXED)

(list:indexed_filter! [LAMBDA BOOL (INT X)] [X LIST REFERENCE])
(set:indexed_filter! [LAMBDA BOOL (INT X)] [X SET REFERENCE])
Modifies the collection reference so that only the elements for which [LAMBDA BOOL (INT X)] returns true remain, with the [INT] value being the index of the element in the collection.

SUBLIST

(list:sublist! [start_at = INT] [end_before = INT] [LIST REFERENCE])
(set:sublist! [start_at = INT] [end_before = INT] [SET REFERENCE])

Only keep in the collection reference the elements with indexes equal or greater than [start_at] and strictly lower than [end_before].

SORT

(list:sort! [LAMBDA INT (X X)] [X LIST REFERENCE])

Reorders the elements of the list reference according to the [LAMBDA] function. The resulting order is ascending. To compare two elements, the lambda function should return:

  • a negative number if the first argument is lower than the second.
  • zero if the first argument is equal to the second.
  • a non-null positive number otherwise.

SHUFFLE

(list:shuffle! [LIST REFERENCE]+)

Randomly changes the order of the elements in [LIST REFERENCE]. As a shorthand, multiple calls to the list:shuffle! instruction can be merged by passing more lists as arguments.

PUSH ELEMENT

(list:push_right! [X COMPUTATION] [X LIST REFERENCE])
(list:push_left! [X COMPUTATION] [X LIST REFERENCE])

Adds an element [X] at the start (list:push_left) or the end (list:push_right) of a list reference.

POP ELEMENT

(list:pop_right! [X LIST REFERENCE] [X REFERENCE])
(list:pop_left! [X LIST REFERENCE] [X REFERENCE])
(set:pop_right! [X SET REFERENCE] [X REFERENCE])
(set:pop_left! [X SET REFERENCE] [X REFERENCE])

Removes and retrieves the element at the start (pop_left) or the end (pop_right) of a list. The removed element is stored in [X REFERENCE].

PARTITION

(list:partition! [LAMBDA BOOL (X)] [if_true = X LIST REFERENCE] [if_false = X LIST REFERENCE])
(set:partition! [LAMBDA BOOL (X)] [if_true = X SET REFERENCE] [if_false = X SET REFERENCE])

Partitions a collection reference [if_true], leaving in the collection all elements for which the lambda function returns (true) and moving to the collection reference [if_false] all elements for which the lambda function returns (false).

PARTITION (INDEXED)

(list:partition! [LAMBDA BOOL (INT X)] [if_true = X LIST REFERENCE] [if_false = X LIST REFERENCE])
(set:partition! [LAMBDA BOOL (INT X)] [if_true = X SET REFERENCE] [if_false = X SET REFERENCE])

Partitions a collection reference [if_true], leaving in the collection all elements for which the lambda function returns (true) and moving to the collection reference [if_false] all elements for which the lambda function returns (false). The first argument given to the lambda function corresponds to the index of the element in the collection (prior to the partitioning).