factor/core/collections/sequences-epilogue.facts

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: 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" }
{ $see-also push } ;

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. 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" } "." }
{ $see-also join } ;

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." }
{ $see-also pop* pop } ;

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." }
{ $see-also peek pop } ;

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." }
{ $see-also peek pop* } ;

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 -1 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 { "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
{ $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: nreverse
{ $values { "seq" "a mutable sequence" } }
{ $description "Reverses a sequence in-place." }
{ $side-effects "seq" } ;

HELP: assoc
{ $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." } ;

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."
    $terpri
    "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 } { "assoc" "a sequence of object/quotation pairs" } }
{ $description
    "Calls the second quotation in the first pair whose first element is equal to " { $snippet "obj" } ", dropping the object from the stack first."
    $terpri
    "The following two phrases are equivalent:"
    { $code "{ { X [ Y ] } { Y [ T ] } } cond" }
    { $code "dup X = [ drop Y ] [ dup Z = [ drop T ] [ no-case ] if ] if" }
}
{ $errors "Throws a " { $link no-case } " error if none of the test quotations yield a true value." }
{ $examples
    { $code
        "SYMBOL: yes  SYMBOL: no  SYMBOL: maybe"
        "maybe {"
        "    { yes [ ] } ! Do nothing"
        "    { no [ \"No way!\" throw ] }"
        "    { maybe [ \"Make up your mind!\" 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 is not equal to any key in the association list." } ;

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." } ;