138 lines
7.7 KiB
Plaintext
138 lines
7.7 KiB
Plaintext
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." } ;
|