211 lines
12 KiB
Plaintext
211 lines
12 KiB
Plaintext
IN: sequences
|
|
USING: help kernel generic ;
|
|
|
|
HELP: subst
|
|
{ $values { "newseq" "a sequence" } { "oldseq" "a mutable sequence" } { "seq" "a sequence" } }
|
|
{ $description "Searches for every element of " { $snippet "seq" } " in " { $snippet "oldseq" } "; if a match is found, the element is replaced by the element of " { $snippet "oldseq" } " at the same index." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: move
|
|
{ $values { "m" "an index in " { $snippet "seq" } } { "n" "an index in " { $snippet "seq" } } { "seq" "a mutable sequence" } }
|
|
{ $description "Sets the element with index " { $snippet "m" } " to the element with index " { $snippet "n" } "." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: delete
|
|
{ $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes all elements equal to " { $snippet "elt" } " from " { $snippet "seq" } "." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: delete-nth
|
|
{ $values { "n" "a non-negative integer" } { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes the " { $snippet "n" } "th element from the sequence, shifting all other elements down and reducing its length by one." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: delete-slice
|
|
{ $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes a range of elements beginning at index " { $snippet "from" } " and ending before index " { $snippet "to" } "." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: replace-slice
|
|
{ $values { "new" "a sequence" } { "seq" "a mutable sequence" } { "m" "a non-negative integer" } { "n" "a non-negative integer" } }
|
|
{ $description "Replaces a range of elements beginning at index " { $snippet "from" } " and ending before index " { $snippet "to" } " with a new sequence." }
|
|
{ $notes "If the " { $snippet "to - from" } " is equal to the length of " { $snippet "new" } ", the sequence remains the same size, and does not have to support resizing. However, if " { $snippet "to - from" } " is not equal to the length of " { $snippet "new" } ", the " { $link set-length } " word is called on " { $snippet "seq" } ", so fixed-size sequences should not be passed in this case." }
|
|
{ $errors "Throws an error if " { $snippet "new" } " contains elements whose types are not permissible in " { $snippet "seq" } "." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: push-new
|
|
{ $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes all elements equal to " { $snippet "elt" } ", and adds " { $snippet "elt" } " at the end of the sequence." }
|
|
{ $examples
|
|
{ $example
|
|
"V{ \"beans\" \"salsa\" \"cheese\" } \"v\" set"
|
|
"\"nachos\" \"v\" get push-new"
|
|
"\"salsa\" \"v\" get push-new"
|
|
"\"v\" get ."
|
|
"V{ \"beans\" \"cheese\" \"nachos\" \"salsa\" }"
|
|
}
|
|
}
|
|
{ $side-effects "seq" } ;
|
|
|
|
{ push push-new add add* } related-words
|
|
|
|
HELP: add
|
|
{ $values { "seq" "a sequence" } { "elt" "an object" } { "newseq" "a sequence" } }
|
|
{ $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the end of " { $snippet "seq" } "." }
|
|
{ $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
|
|
{ $examples
|
|
{ $example "{ 1 2 3 } 4 add ." "{ 1 2 3 4 }" }
|
|
} ;
|
|
|
|
HELP: add*
|
|
{ $values { "seq" "a sequence" } { "elt" "an object" } { "newseq" "a sequence" } }
|
|
{ $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the beginning of " { $snippet "seq" } "." }
|
|
{ $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
|
|
{ $examples
|
|
{ $example "{ 1 2 3 } 0 add* ." "{ 0 1 2 3 }" }
|
|
} ;
|
|
|
|
HELP: diff
|
|
{ $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "newseq" "a sequence" } }
|
|
{ $description "Outputs a sequence consisting of elements present in " { $snippet "seq2" } " but not " { $snippet "seq1" } ", comparing elements for equality." } ;
|
|
|
|
HELP: concat
|
|
{ $values { "seq" "a sequence" } { "newseq" "a sequence" } }
|
|
{ $description "Concatenates a sequence of sequences together into one sequence. If " { $snippet "seq" } " is empty, outputs " { $snippet "{ }" } ", otherwise the resulting sequence is of the same class as the first element of " { $snippet "seq" } "." }
|
|
{ $errors "Throws an error if one of the sequences in " { $snippet "seq" } " contains elements not permitted in sequences of the same class as the first element of " { $snippet "seq" } "." } ;
|
|
|
|
HELP: peek
|
|
{ $values { "seq" "a sequence" } { "elt" "an object" } }
|
|
{ $description "Outputs the last element of a sequence." }
|
|
{ $errors "Throws an error if the sequence is empty." } ;
|
|
|
|
{ peek pop pop* } related-words
|
|
|
|
HELP: pop*
|
|
{ $values { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes the last element and shortens the sequence." }
|
|
{ $side-effects "seq" }
|
|
{ $errors "Throws an error if the sequence is empty." } ;
|
|
|
|
HELP: pop
|
|
{ $values { "seq" "a resizable mutable sequence" } { "elt" "an object" } }
|
|
{ $description "Outputs the last element after removing it and shortening the sequence." }
|
|
{ $side-effects "seq" }
|
|
{ $errors "Throws an error if the sequence is empty." } ;
|
|
|
|
HELP: all-equal?
|
|
{ $values { "seq" "a sequence" } { "?" "a boolean" } }
|
|
{ $description "Tests if all elements in the sequence are equal. Yields true with an empty sequence." } ;
|
|
|
|
HELP: all-eq?
|
|
{ $values { "seq" "a sequence" } { "?" "a boolean" } }
|
|
{ $description "Tests if all elements in the sequence are the same identical object. Yields true with an empty sequence." } ;
|
|
|
|
HELP: mismatch
|
|
{ $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "i" "an index" } }
|
|
{ $description "Compares pairs of elements up to the minimum of the sequences' lengths, outputting the first index where the two sequences have non-equal elements, or " { $link f } " if all tested elements were equal." } ;
|
|
|
|
HELP: flip
|
|
{ $values { "matrix" "a sequence of equal-length sequences" } { "newmatrix" "a sequence of equal-length sequences" } }
|
|
{ $description "Transposes the matrix; that is, rows become columns and columns become rows." }
|
|
{ $examples { $example "{ { 1 2 3 } { 4 5 6 } } flip ." "{ { 1 4 } { 2 5 } { 3 6 } }" } } ;
|
|
|
|
HELP: unpair
|
|
{ $values { "alist" "a sequence of pairs" } { "keys" "a new sequence" } { "values" "a new sequence" } }
|
|
{ $description "Given a sequence of two-element sequences, outputs a new sequence with the first element of each pair, and a new sequence with the second element of each pair." } ;
|
|
|
|
HELP: exchange
|
|
{ $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
|
|
{ $description "Exchanges the " { $snippet "m" } "th and " { $snippet "n" } "th elements of " { $snippet "seq" } "." } ;
|
|
|
|
HELP: reverse-here
|
|
{ $values { "seq" "a mutable sequence" } }
|
|
{ $description "Reverses a sequence in-place." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: last/first
|
|
{ $values { "seq" "a sequence" } { "pair" "a two-element array" } }
|
|
{ $description "Creates an array holding the first and last element of the sequence." } ;
|
|
|
|
HELP: padding
|
|
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
|
|
{ $description "Outputs a new string sequence of " { $snippet "elt" } " repeated, that when appended to " { $snippet "seq" } ", yields a sequence of length " { $snippet "n" } ". If the length of { " { $snippet "seq" } " is greater than " { $snippet "n" } ", this word outputs an empty sequence." } ;
|
|
|
|
HELP: pad-left
|
|
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
|
|
{ $description "Outputs a new sequence consisting of " { $snippet "seq" } " padded on the left with enough repetitions of " { $snippet "elt" } " to have the result be of length " { $snippet "n" } "." }
|
|
{ $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-left print ] each" "---ab\n-quux" } } ;
|
|
|
|
HELP: pad-right
|
|
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
|
|
{ $description "Outputs a new sequence consisting of " { $snippet "seq" } " padded on the right with enough repetitions of " { $snippet "elt" } " to have the result be of length " { $snippet "n" } "." }
|
|
{ $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-right print ] each" "ab---\nquux-" } } ;
|
|
|
|
HELP: sequence=
|
|
{ $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "?" "a boolean" } }
|
|
{ $description "Tests if the two sequences have the same length and elements. This is weaker than " { $link = } ", since it does not ensure that the sequences are instances of the same class." } ;
|
|
|
|
HELP: group
|
|
{ $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "groups" "a sequence of sequences" } }
|
|
{ $description "Splits the sequence into groups of " { $snippet "n" } " elements and collects the groups into a new array." }
|
|
{ $notes "If the sequence length is not a multiple of " { $snippet "n" } ", the final subsequence in the list will be shorter than " { $snippet "n" } " elements." } ;
|
|
|
|
HELP: depth
|
|
{ $values { "n" "a non-negative integer" } }
|
|
{ $description "Outputs the number of elements on the data stack." } ;
|
|
|
|
HELP: cond
|
|
{ $values { "assoc" "a sequence of quotation pairs" } }
|
|
{ $description
|
|
"Calls the second quotation in the first pair whose first quotation yields a true value."
|
|
$nl
|
|
"The following two phrases are equivalent:"
|
|
{ $code "{ { [ X ] [ Y ] } { [ Z ] [ T ] } } cond" }
|
|
{ $code "X [ Y ] [ Z [ T ] [ no-cond ] if ] if" }
|
|
}
|
|
{ $errors "Throws a " { $link no-cond } " error if none of the test quotations yield a true value." }
|
|
{ $examples
|
|
{ $code
|
|
"{"
|
|
" { [ dup 0 > ] [ \"positive\" ] }"
|
|
" { [ dup 0 < ] [ \"negative\" ] }"
|
|
" { [ dup zero? ] [ \"zero\" ] }"
|
|
"} cond"
|
|
}
|
|
} ;
|
|
|
|
HELP: no-cond
|
|
{ $description "Throws a " { $link no-cond } " error." }
|
|
{ $error-description "Thrown by " { $link cond } " if none of the test quotations yield a true value. Most uses of " { $link cond } " include a default case where the test quotation is " { $snippet "[ t ]" } "; such a " { $link cond } " form will never throw this error. If you wish to assert that certain conditions are true, and fail otherwise, you can use " { $link cond } " without a default case." } ;
|
|
|
|
HELP: case
|
|
{ $values { "obj" object } { "cases" "a sequence of object/quotation pairs, with an optional quotation at the end" } }
|
|
{ $description
|
|
"Compares " { $snippet "obj" } " against the first element of every pair. If some pair matches, removes " { $snippet "obj" } " from the stack and calls the second element of that pair, which must be a quotation."
|
|
$nl
|
|
"If there is no case matching " { $snippet "obj" } ", the default case is taken. If the last element of " { $snippet "cases" } " is a quotation, the quotation is called with " { $snippet "obj" } " on the stack. Otherwise, a " { $link no-cond } " error is rasied."
|
|
$nl
|
|
"The following two phrases are equivalent:"
|
|
{ $code "{ { X [ Y ] } { Y [ T ] } } case" }
|
|
{ $code "dup X = [ drop Y ] [ dup Z = [ drop T ] [ no-case ] if ] if" }
|
|
}
|
|
{ $examples
|
|
{ $code
|
|
"SYMBOL: yes SYMBOL: no SYMBOL: maybe"
|
|
"maybe {"
|
|
" { yes [ ] } ! Do nothing"
|
|
" { no [ \"No way!\" throw ] }"
|
|
" { maybe [ \"Make up your mind!\" print ] }"
|
|
" [ \"Invalid input; try again.\" print ]"
|
|
"} case"
|
|
}
|
|
} ;
|
|
|
|
HELP: no-case
|
|
{ $description "Throws a " { $link no-case } " error." }
|
|
{ $error-description "Thrown by " { $link case } " if the object at the top of the stack does not match any case, and no default case is given." } ;
|
|
|
|
HELP: unix?
|
|
{ $values { "?" "a boolean" } }
|
|
{ $description "Tests if Factor is running on a Unix-like system. While this is a rather vague notion, one can use it to make certain assumptions about system calls and file structure which are not valid on Windows." } ;
|