212 lines
12 KiB
Plaintext
212 lines
12 KiB
Plaintext
IN: sequences
|
|
USING: help kernel ;
|
|
|
|
HELP: first2 "( seq -- first second )"
|
|
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } }
|
|
{ $description "Pushes the first two elements of a sequence." }
|
|
{ $errors "Throws an error if the sequence has less than two elements." } ;
|
|
|
|
HELP: first3 "( seq -- first second third )"
|
|
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } }
|
|
{ $description "Pushes the first three elements of a sequence." }
|
|
{ $errors "Throws an error if the sequence has less than three elements." } ;
|
|
|
|
HELP: first4 "( seq -- first second third fourth )"
|
|
{ $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } { "fourth" "the fourth element" } }
|
|
{ $description "Pushes the first four elements of a sequence." }
|
|
{ $errors "Throws an error if the sequence has less than four elements." } ;
|
|
|
|
HELP: index "( obj seq -- n )"
|
|
{ $values { "obj" "an object" } { "seq" "a sequence" } }
|
|
{ $description "Outputs the index of the first element in the sequence equal to " { $snippet "obj" } ". If no element is found, outputs -1." }
|
|
{ $see-also index* member? } ;
|
|
|
|
HELP: index* "( obj i seq -- n )"
|
|
{ $values { "obj" "an object" } { "i" "a start index" } { "seq" "a sequence" } }
|
|
{ $description "Outputs the index of the first element in the sequence equal to " { $snippet "obj" } ", starting the search from the " { $snippet "i" } "th element. If no element is found, outputs -1." }
|
|
{ $see-also index member? } ;
|
|
|
|
HELP: member? "( obj seq -- ? )"
|
|
{ $values { "obj" "an object" } { "seq" "a sequence" } }
|
|
{ $description "Tests if the sequence contains an element equal to the object." }
|
|
{ $see-also index index* memq? } ;
|
|
|
|
HELP: memq? "( obj seq -- ? )"
|
|
{ $values { "obj" "an object" } { "seq" "a sequence" } }
|
|
{ $description "Tests if the sequence contains the object." }
|
|
{ $examples
|
|
"This word uses identity comparison, so the following will most likely print " { $link f } ":"
|
|
{ $example "\"hello\" { \"hello\" } memq? ." "f" }
|
|
}
|
|
{ $see-also index index* member? } ;
|
|
|
|
HELP: remove "( elt seq -- newseq )"
|
|
{ $values { "elt" "an object" } { "seq" "a sequence" } { "newseq" "a new sequence" } }
|
|
{ $description "Outputs a new sequence containing all elements of the input sequence except those equal to the given element." } ;
|
|
|
|
HELP: subst "( newseq oldseq seq -- )"
|
|
{ $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 "( m n seq -- )"
|
|
{ $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 "( elt seq -- )"
|
|
{ $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Removes all elements equal to " { $snippet "elt" } " from " { $snippet "seq" } "." }
|
|
{ $side-effects "seq" } ;
|
|
|
|
HELP: push-new "( elt seq -- )"
|
|
{ $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\" \"salsa\" \"nachos\" }"
|
|
}
|
|
}
|
|
{ $side-effects "seq" }
|
|
{ $see-also push } ;
|
|
|
|
HELP: nappend "( dest src -- )"
|
|
{ $values { "n" "an index in " { $snippet "dest" } } { "dest" "a resizable mutable sequence" } { "src" "a sequence" } }
|
|
{ $description "Appends " { $snippet "src" } " to the end of " { $snippet "dest" } "." }
|
|
{ $side-effects "dest" }
|
|
{ $errors "Throws an error if " { $snippet "src" } " contains elements not permitted in " { $snippet "dest" } "." } ;
|
|
|
|
HELP: >resizable "( seq -- newseq )"
|
|
{ $values { "seq" "a sequence" } { "newseq" "a mutable resizable sequence" } }
|
|
{ $description "Outputs a new, mutable resizable sequence having the same elements as " { $snippet "seq" } "." } ;
|
|
|
|
HELP: immutable "( seq quot -- newseq )"
|
|
{ $values { "seq" "a sequence" } { "quot" "a quotation with stack effect " { $snippet "( seq -- )" } } { "newseq" "a sequence" } }
|
|
{ $description "A utility combinator transforming a word which modifies its input sequence into a word which returns a new output sequence. "
|
|
$terpri
|
|
"A mutable, resizable copy of " { $snippet "seq" } " is made, then the quotation is called to modify this copy and consume it. Finally, the copy is converted into a sequence of the same type as the original." }
|
|
{ $examples
|
|
"Take a look at " { $link append } ", which is built off the mutating word " { $link nappend } ", or " { $link add } " which is built from " { $link push } "."
|
|
} ;
|
|
|
|
HELP: add "( seq elt -- newseq )"
|
|
{ $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* "( seq elt -- newseq )"
|
|
{ $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 "( seq1 seq2 -- newseq )"
|
|
{ $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: append3 "( seq1 seq2 seq3 -- newseq )"
|
|
{ $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "seq3" "a sequence" } { "newseq" "a sequence" } }
|
|
{ $description "Outputs a new sequence consisting of the elements of " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn." }
|
|
{ $errors "Throws an error if " { $snippet "seq2" } " or " { $snippet "seq3" } " contain elements not permitted in sequences of the same class as " { $snippet "seq1" } "." } ;
|
|
|
|
HELP: peek "( seq -- elt )"
|
|
{ $values { "seq" "a sequence" } { "elt" "an object" } }
|
|
{ $description "Outputs the last element of a sequence." }
|
|
{ $errors "Throws an error if the sequence is empty." }
|
|
{ $see-also pop* pop } ;
|
|
|
|
HELP: pop* "( seq -- )"
|
|
{ $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." }
|
|
{ $see-also peek pop } ;
|
|
|
|
HELP: pop "( seq -- )"
|
|
{ $values { "seq" "a resizable mutable sequence" } }
|
|
{ $description "Outputs the last element after removing it and shortening the sequence." }
|
|
{ $side-effects "seq" }
|
|
{ $errors "Throws an error if the sequence is empty." }
|
|
{ $see-also peek pop* } ;
|
|
|
|
HELP: all-equal? "( seq -- ? )"
|
|
{ $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? "( seq -- ? )"
|
|
{ $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 "( seq1 seq2 -- i )"
|
|
{ $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 -1 if all tested elements were equal." } ;
|
|
|
|
HELP: flip "( matrix -- newmatrix )"
|
|
{ $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 "( assoc -- keys values )"
|
|
{ $values { "assoc" "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 "( m n seq -- )"
|
|
{ $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: assoc "( key assoc -- value )"
|
|
{ $values { "key" "an object" } { "assoc" "a sequence of pairs" } { "value" "the associated value, or " { $link f } } }
|
|
{ $description "Searches for a pair whose first element is equal to the key and outputs the second element of the pair. Keys are compared for equality using " { $link = } ". Outputs " { $link f } " if no matching key is found." }
|
|
{ $see-also rassoc } ;
|
|
|
|
HELP: rassoc "( value assoc -- key )"
|
|
{ $values { "value" "an object" } { "assoc" "a sequence of pairs" } { "key" "the associated key, or " { $link f } } }
|
|
{ $description "Searches for a pair whose second element is equal to the value and outputs the first element of the pair. Values are compared for equality using " { $link = } ". Outputs " { $link f } " if no matching value is found." }
|
|
{ $see-also rassoc } ;
|
|
|
|
HELP: last/first "( seq -- pair )"
|
|
{ $values { "seq" "a sequence" } { "pair" "a two-element array" } }
|
|
{ $description "Creates an array holding the first and last element of the sequence." } ;
|
|
|
|
HELP: sequence= "( seq1 seq2 -- ? )"
|
|
{ $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: depth "( -- n )"
|
|
{ $values { "n" "a non-negative integer" } }
|
|
{ $description "Outputs the number of elements on the data stack." } ;
|
|
|
|
HELP: cond "( assoc -- )"
|
|
{ $values { "assoc" "a sequence of quotation pairs" } }
|
|
{ $description
|
|
"Calls the first quotation in each pair in turn, until a quotation outputs a true value, in which case the second quotation in the corresponding pair is called."
|
|
$terpri
|
|
"The following two phrases are equivalent:"
|
|
{ $code "{ { [ X ] [ Y ] } { [ Z ] [ T ] } } cond" }
|
|
{ $code "X [ Y ] [ Z [ T ] [ no-cond ] if ] if" }
|
|
"Note that the base case is " { $link no-cond } " which throws an error."
|
|
}
|
|
{ $errors "Throws an error if the first quotation in every pair yields " { $link f } "." }
|
|
{ $examples
|
|
{ $example
|
|
"{"
|
|
" { [ dup 0 > ] [ \"positive\" ] }"
|
|
" { [ dup 0 < ] [ \"negative\" ] }"
|
|
" { [ dup zero? ] [ \"zero\" ] }"
|
|
"} cond"
|
|
}
|
|
} ;
|
|
|
|
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." } ;
|