USING: help sequences sequences-internals ;

HELP: length "( seq -- n )"
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } }
{ $contract "Outputs the length of the sequence. All sequences support this operation."
$terpri
"This generic word is flushable, so user-defined methods must satisfy the flushable contract (see " { $link "declarations" } ")." } ;

HELP: set-length "( n seq -- )"
{ $values { "n" "a non-negative integer" } { "seq" "a resizable sequence" } }
{ $description "Resizes the sequence. Not all sequences are resizable." }
{ $errors "Throws an error if the new length is negative, or if the sequence is not resizable." }
{ $side-effects "seq" } ;

HELP: nth "( n seq -- elt )"
{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "elt" "the element at the " { $snippet "n" } "th index" } }
{ $contract "Outputs the " { $snippet "n" } "th element of the sequence. Elements are numbered from zero, so the last element has an index one less than the length of the sequence. All sequences support this operation."
$terpri
"This generic word is flushable, so user-defined methods must satisfy the flushable contract (see " { $link "declarations" } ")." }
{ $errors "Throws an error if the index is negative, or greater than or equal to the length of the sequence." } ;

HELP: set-nth "( elt n seq -- )"
{ $values { "elt" "an object" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
{ $contract "Sets the $n$th element of the sequence. Storing beyond the end of a resizable sequence such as a vector or string buffer grows the sequence." }
{ $errors "Throws an error if the index is negative, or if the sequence is not resizable and the index is greater than or equal to the length of the sequence."
$terpri
"Throws an error if the sequence cannot hold elements of the given type." }
{ $side-effects "seq" } ;

HELP: thaw "( seq -- resizable-seq )"
{ $values { "seq" "a sequence" } { "resizable-seq" "a resizable mutable sequence" } }
{ $contract "Outputs an empty, resizable mutable sequence that can hold the elements of " { $snippet "seq" } "."
$terpri
"This generic word is flushable, so user-defined methods must satisfy the flushable contract (see " { $link "declarations" } ")." }
{ $examples "The default implementation returns a new vector, but given a string, it returns a string buffer, since string buffers are more efficient in terms of memory usage." } ;

HELP: like "( seq prototype -- newseq )"
{ $values { "seq" "a sequence" } { "prototype" "a sequence" } { "newseq" "a sequence" } }
{ $contract "Outputs a sequence with the same elements as the input sequence, but " { $emphasis "like" } " the template sequence, in the sense that it either has the same class as the template sequence, or if the template sequence is a virtual sequence, the same class as the template sequence's underlying sequence. The default implementation does nothing."
$terpri
"This generic word is flushable, so user-defined methods must satisfy the flushable contract (see " { $link "declarations" } ")." } ;

HELP: empty? "( seq -- ? )"
{ $values { "seq" "a sequence" } { "?" "a boolean" } }
{ $description "Tests if the sequence has zero length." } ;

HELP: peek "( seq -- elt )"
{ $values { "seq" "a sequence" } { "elt" "an object" } }
{ $description "Outputs the last element of the sequence." }
{ $errors "Throws an error if the sequence is empty." } ;

HELP: head "( n seq -- headseq )"
{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "headseq" "a new sequence" } }
{ $description "Outputs a new sequence consisting of the first " { $snippet "n" } " elements of the input sequence." }
{ $errors "Throws an error if the index is out of bounds." } ;

HELP: tail "( n seq -- tailseq )"
{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "tailseq" "a new sequence" } }
{ $description "Outputs a new sequence consisting of the input sequence with the first n items removed." }
{ $errors "Throws an error if the index is out of bounds." } ;

HELP: resize "( n seq -- newseq )"
{ $values { "n" "a non-negative integer" } { "seq" "a sequence" } { "newseq" "a new sequence" } }
{ $description "Creates a new sequence of the same type as " { $snippet "seq" } " with " { $snippet "n" } " elements, and copies the contents of " { $snippet "seq" } " into the new sequence. If " { $snippet "n" } " exceeds the length of " { $snippet "seq" } ", the remaining elements are filled with a default value; " { $link f } " for arrays and 0 for strings." }
{ $notes "This generic word is only implemented for strings and arrays." } ;

HELP: first "( seq -- first )"
{ $values { "seq" "a sequence" } { "first" "the first element of the sequence" } }
{ $description "Outputs the first element of the sequence." }
{ $errors "Throws an error if the sequence is empty." } ;

HELP: second "( seq -- second )"
{ $values { "seq" "a sequence" } { "second" "the second element of the sequence" } }
{ $description "Outputs the second element of the sequence." }
{ $errors "Throws an error if the sequence contains less than two elements." } ;

HELP: third "( seq -- third )"
{ $values { "seq" "a sequence" } { "third" "the third element of the sequence" } }
{ $description "Outputs the third element of the sequence." }
{ $errors "Throws an error if the sequence contains less than three elements." } ;

HELP: fourth "( seq -- fourth )"
{ $values { "seq" "a sequence" } { "fourth" "the fourth element of the sequence" } }
{ $description "Outputs the fourth element of the sequence." }
{ $errors "Throws an error if the sequence contains less than four elements." } ;

HELP: push "( elt seq -- )"
{ $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
{ $description "Adds an element at the end of the sequence. The sequence length is adjusted accordingly." }
{ $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
{ $side-effects "seq" }
{ $see-also pop push-new } ;

HELP: ?push "( elt seq/f -- seq )"
{ $values { "elt" "an object" } { "seq/f" "a resizable mutable sequence, or " { $link f } } { "seq" "a resizable mutable sequence" } }
{ $description "If the given sequence is " { $link f } ", creates and outputs a new one-element vector holding " { $snippet "elt" } ". Otherwise, pushes " { $snippet "elt" } " onto the given sequence." }
{ $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
{ $side-effects "seq" } ;

HELP: bounds-check? "( n seq -- ? )"
{ $values { "n" "an integer" } { "seq" "a sequence" } { "?" "a boolean" } }
{ $description "Tests if the index is within the bounds of the sequence." } ;

HELP: ?nth "( n seq/f -- elt )"
{ $values { "n" "an integer" } { "seq" "a sequence" } { "elt" "an object" } }
{ $description "A forgiving version of " { $link nth } ". If the index is out of bounds, or if the sequence is " { $link f } ", simply outputs " { $link f } "." } ;

HELP: nth-unsafe "( n seq -- elt )"
{ $values { "n" "an integer" } { "seq" "a sequence" } { "elt" "an object" } }
{ $contract "Unsafe variant of " { $link nth } " that does not perform bounds checks." } ;

HELP: set-nth-unsafe "( elt n seq -- )"
{ $values { "elt" "an object" } { "n" "an integer" } { "seq" "a sequence" } }
{ $contract "Unsafe variant of " { $link set-nth } " that does not perform bounds checks." } ;

HELP: exchange "( m n seq -- )"
{ $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
{ $description "Unsafe variant of " { $link exchange } " that does not perform bounds checks." } ;