USING: arrays help sequences sequences-internals vectors
strings kernel ;

HELP: <vector>
{ $values { "n" "a positive integer specifying initial capacity" } { "vector" "a new vector" } }
{ $description "Creates a new vector that can hold " { $snippet "n" } " elements before resizing." }
{ $see-also <array> <string> <sbuf> } ;

HELP: length
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } }
{ $contract "Outputs the length of the sequence. All sequences support this operation." } ;

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

HELP: nth
{ $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." }
{ $errors "Throws a " { $link bounds-error } " if the index is negative, or greater than or equal to the length of the sequence." } ;

HELP: set-nth
{ $values { "elt" "an object" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
{ $contract "Sets the " { $snippet "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
{ $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" } "." }
{ $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
{ $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."
$terpri
"The default implementation does nothing." }
{ $notes "The output sequence might share storage with the input sequence, for example:"
{ $example
    "{ 1 2 3 } \"array\" set"
    "\"array\" get V{ } like \"vector\" set"
    "t 0 \"array\" get set-nth"
    "\"vector\" get ."
    "V{ t 2 3 }"
}
"If this behavior is undesirable, you can use one of the following words instead, which always output a fresh sequence:"
{ $list
    { $link >array }
    { $link >quotation }
    { $link >string }
    { $link >sbuf }
    { $link >vector }
} } ;

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

HELP: delete-all
{ $values { "seq" "a resizable sequence" } }
{ $description "Resizes the sequence to zero length, removing all elements. Not all sequences are resizable." }
{ $errors "Throws a " { $link bounds-error } " if the new length is negative, or if the sequence is not resizable." }
{ $side-effects "seq" } ;

HELP: resize
{ $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
{ $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
{ $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
{ $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
{ $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
{ $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
{ $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?
{ $values { "n" "an integer" } { "seq" "a sequence" } { "?" "a boolean" } }
{ $description "Tests if the index is within the bounds of the sequence." } ;

HELP: ?nth
{ $values { "n" "an integer" } { "seq" "a sequence" } { "elt/f" "an object or " { $link f } } }
{ $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
{ $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
{ $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-unsafe
{ $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." } ;

HELP: first2-unsafe
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } }
{ $contract "Unsafe variant of " { $link first2 } " that does not perform bounds checks." } ;

HELP: first3-unsafe
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } }
{ $contract "Unsafe variant of " { $link first3 } " that does not perform bounds checks." } ;

HELP: first4-unsafe
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } { "fourth" "the fourth element" } }
{ $contract "Unsafe variant of " { $link first4 } " that does not perform bounds checks." } ;