"A sequence is a linearly-ordered finite collection of elements."
$terpri
"Sequence utility words can operate on any object whose class implements the sequence protocol."
{ $subsection "sequence-protocol" }
"There are a number of implementations of sequences in the core library, and you can write new implementations yourself."
{ $subsection "sequence-implementations" }
"Much of the power of sequences lies in the polymorphic utility words that allow computations to be expressed as bulk operations without loops, recursion or micro-management of elements."
"The " { $link f } " object also supports the sequence protocol. It responds with a length of zero, and instead of throwing an out of bounds error, outputs " { $link f } " when an element is accessed. This can simplify code that would like a dummy sequence behaving as if it has arbitrary length." ;
ARTICLE: "sequences-integers" "Integer sequences and counted loops"
"Integers support the sequence protocol in a trivial fashion; a non-negative integer presents its non-negative predecessors as elements. For example, the integer 3, when viewed as a sequence, contains the elements 0, 1, and 2. This is very useful for performing counted loops."
$terpri
"For example, the " { $link each } " combinator, given an integer, simply calls a quotation that number of times, pushing a counter on each iteration that ranges from 0 up to that integer:"
{ $example "3 [ . ] each" "0\n1\n2" }
"A common idiom is to iterate over a sequence, while also maintaining a loop counter. This can be done using " { $link 2each } ":"
"Some utilities for accessing various common indices:"
{ $subsection first }
{ $subsection second }
{ $subsection third }
{ $subsection fourth }
{ $subsection first2 }
{ $subsection first3 }
{ $subsection first4 }
"A forgiving wrapper for " { $link nth } ":"
{ $subsection ?nth }
{ $subsection bounds-check? } ;
ARTICLE: "sequences-iteration" "Iteration and collection"
"Iteration combinators:"
{ $subsection each }
{ $subsection reduce }
{ $subsection interleave }
{ $subsection 2each }
{ $subsection 2reduce }
"Collection combinators:"
{ $subsection map }
{ $subsection 2map }
"A combinator that modifies elements in-place:"
{ $subsection inject } ;
ARTICLE: "sequences-tests" "Testing sequences"
{ $subsection empty? }
{ $subsection member? }
{ $subsection memq? }
{ $subsection head? }
{ $subsection tail? }
{ $subsection subseq? }
{ $subsection contains? }
{ $subsection all? }
{ $subsection monotonic? }
{ $subsection all-eq? }
{ $subsection all-equal? } ;
ARTICLE: "sequences-slicing" "Slicing and splitting"
"The first set of words are concerned with taking subsequences of a sequence. Each of the below words comes in dual pairs; the first of the pair outputs a new copied sequence, the second outputs a virtual sequence sharing structure with the underlying sequence."
"An " { $emphasis "association list" } " is a sequence of pairs. Association lists come up from time to time; for example, the " { $link cond } " combinator takes an association list of quotations as input. You can perform lookups and take association lists apart:"
{ $subsection assoc }
{ $subsection rassoc }
{ $subsection unpair }
"An association list is slower to search than a hashtable. The main advantage of an association list is that the elements are ordered; also sometimes it is more convenient to construct an association list with sequence words than to construct a hashtable with hastable words. Most of the time, hashtables are more appropriate. See " { $link "hashtables" } "." ;
"An array is a fixed-size mutable sequence whose elements are stored in a contiguous range of memory. The literal syntax is covered in " { $link "syntax-arrays" } ". Sometimes you need a growable array -- this is called a vector, and vectors are documented in " { $link "vectors" } "."
"Array words are in the " { $vocab-link "arrays" } " vocabulary. Unsafe implementation words are in the " { $vocab-link "kernel-internals" } " vocabulary."
"A string buffer is a resizable mutable sequence of characters. String buffers can be used to construct new strings by accumilating substrings and characters, however usually they are only used indirectly, since the sequence construction words are more convenient to use in most cases (see " { $link "namespaces-make" } ")."
"Sorting and binary search combinators all take comparator quotations with stack effect " { $snippet "( elt1 elt2 -- n )" } " that order the two given elements and output a value whose sign denotes the result:"
"The unsafe sequence protocol bypasses bounds checks for increased performance:"
{ $subsection nth-unsafe }
{ $subsection set-nth-unsafe }
"These words assume the sequence index given is within bounds; if it is not, memory corruption can occur. Please think twice before using them; first, make sure the code in question is actually a bottleneck; next, try improving the algorithm first. If all else fails, then use these words and test your code very carefully."
$terpri
"There is a very important invariant these word must preserve: if at some point in time, the length of a sequence was " { $snippet "n" } ", then any future lookups of elements with indices below " { $snippet "n" } " must not crash the runtime, even if the sequence length is now less than " { $snippet "n" } ". For example, vectors preserve this invariant by never shrinking the underlying storage, only growing it as necessary."
$terpri
"The justification for this is that the runtime should not crash if a resizable sequence is resized during the execution of an iteration combinator."
$terpri
"Indeed, iteration combinators are the primary use-case for these words; if the iteration index is already guarded by a loop test which ensures it is within bounds, then additional bounds checks are redundant. For example, see the implementation of " { $link each } "." ;
"Growable sequences are implementing by having a wrapper object hold a reference to an underlying sequence, together with a fill pointer indicating how many elements of the underlying sequence are occupied. When the fill pointer exceeds the underlying sequence capacity, the underlying sequence grows."
$terpri
"There is a growable sequence protocol:"
{ $subsection underlying }
{ $subsection set-underlying }
{ $subsection set-fill }
"Any instance of a class implementing the above generics can make use of several utility words:"
{ $subsection capacity }
{ $subsection ensure }
{ $subsection grow-length }
{ $subsection clone-growable }
"This protocol and the above words are unsafe; they do not perform bounds checks for performance reasons, and thus a mistake can lead to memory corruption due to an underlying sequence being shorter than the fill pointer."
$terpri
"Vectors and string buffers are implemented using the growable sequence facility (and they perform full bounds-checks and thus are safe)." ;
