Module /fusion/collection

(. value key ...)

Traverses a "path" through a data structure, folding the value through each key in turn. When the value is void, it is returned immediately and any further keys are not applied. If a key is a procedure, it must accept one argument; the procedure is applied to the current value, and the result becomes the value for the next key. Otherwise, the key and value are passed to elt to get the next value.

(. [0, 1] 0)         =>  0
(. (sexp 0 1) 1)     =>  1
(. {f:2} "f")        =>  2
(. {f:3} (quote f))  =>  3

(. [0, 1, 2, 3] size)               =>  4
(. (sexp 0 1 2 3) head)             =>  0
(. (sexp 0 1 2 3) tail)             =>  (1 2 3)
(. (sexp 0 1 2 3) tail tail head)   =>  2

Since . is a procedure, field names must be quoted or else they will be evaluated as a variable reference:

(. {f:2} f)        => ERROR: Unbound variable reference
(let [(g "f")]
  (. {f:2} g))     => 2

(any pred collection)

Applies the one-argument predicate pred to the elements of collection; the first time pred returns a truthy value that truthy value is returned and no more elements are visited. If no call returns a truthy value, then the result is that of the final predicate call, or false if the collection is empty.

When collection is a sequence, the elements are visited in order, and the application of pred to the final element of the sequence is in tail position.

(do proc collection)

Applies the one-argument procedure proc to the elements of collection, ignoring any results. Returns void.

When collection is a sequence, the elements are visited in order.

See also: struct_do

(element collection key)

Returns an element within a collection. The collection must be a non-null, non-empty list, sexp, or struct. The key must have a type appropriate for the collection: an int for lists or sexps, a string or symbol for structs.

(element [0, 1] 0)         =>  0
(element (sexp 0 1) 1)     =>  1
(element {f:2} "f")        =>  2
(element {f:3} (quote f))  =>  3

Since element is a procedure, field names must be quoted or else they will be evaluated as a variable reference:

(element {f:2} f)        => ERROR: Unbound variable reference
(let [(g "f")]
  (element {f:2} g))     => 2

An exception is raised if the collection has an unsupported type, if the key isn't appropriate for the collection, or if the key doesn't identify an element within the collection.

(element [0, 1] 2)       =>  ERROR
(element [0, 1] "2")     =>  ERROR
(element {f:2} "g")      =>  ERROR

(elt collection key)

Returns an element within a collection, being lenient. The collection must be a list, sexp, struct, or void. The key must have a type appropriate for the collection: an int for lists or sexps, a string or symbol for structs.

(elt [0, 1] 0)         =>  0
(elt (sexp 0 1) 1)     =>  1
(elt {f:2} "f")        =>  2
(elt {f:3} (quote f))  =>  3

If the collection is empty, null, or void, the result is void. If the key isn't appropriate for the collection, or if the key doesn't identify an element within the collection, the result is void.

(elt null.list 0)    =>  void
(elt [0, 1] 2)       =>  void
(elt [0, 1] "2")     =>  void
(elt {f:2} "g")      =>  void

Since elt is a procedure, field names must be quoted or else they will be evaluated as a variable reference:

(elt {f:2} f)        => ERROR: Unbound variable reference
(let [(g "f")]
  (elt {f:2} g))     => 2

An exception is raised if the collection has an unsupported type.

(every pred collection)

Applies the one-argument predicate pred to the elements of collection; the first time pred returns an untruthy value that untruthy value is returned and no more elements are visited. If no call returns an untruthy value, then the result is that of the final predicate call, or true if the collection is empty. When collection is a sequence, the elements are visited in order, and the application of pred to the final element of the sequence is in tail position.

(find pred collection)

Applies the one-argument predicate pred to each element of collection; the first time pred returns a truthy value that element is returned. If no such element is found, the result is void.

When collection is a sequence, the elements are visited in order.

When collection is a struct, the "elements" of the collection are its values (as opposed to its key-value pairs): the predicate will be applied on each value, and the result is either one of those values or void.

(has_key collection key)

Determines whether a collection has a mapping for a given key. When has_key returns true, then (element collection key) will succeed.

Note that the keys of a sequence are the zero-based integer indices of the elements within the sequence, not the elements themselves.

(has_key {f:12} "f")           ==> true
(has_key [3,true,2014T] 0)     ==> true
(has_key [3,true,2014T] 3)     ==> false
(has_key [3,true,2014T] null)  ==> false

(is_collection value)

Determines whether value is a collection (struct, list, or sexp), returning true or false.

(is_empty collection)

Returns true if the size of the collection is zero, otherwise returns false.

(none pred collection)

Applies the one-argument predicate 'pred' to the elements of collection. Returns false if the predicate returns a truthy value for any element, true if none do, and true if the collection is empty.

(same_size collection1 collection2)

Returns whether two collections have the same size.

(size collection)

Returns the number of elements in the collection. The size of null.list (etc.) is zero. If collection is an improper sexp, an exception is thrown.

Warning: Computing the size of an sexp takes linear time, since it must traverse the linked list of pairs to count elements.