core/collections/sequences-epilogue.facts

   1 IN: sequences
   2 USING: help kernel ;
   3
   4 HELP: first2
   5 { $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } }
   6 { $description "Pushes the first two elements of a sequence." }
   7 { $errors "Throws an error if the sequence has less than two elements." } ;
   8
   9 HELP: first3
  10 { $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } }
  11 { $description "Pushes the first three elements of a sequence." }
  12 { $errors "Throws an error if the sequence has less than three elements." } ;
  13
  14 HELP: first4
  15 { $values { "seq" "a sequence" } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } { "fourth" "the fourth element" } }
  16 { $description "Pushes the first four elements of a sequence." }
  17 { $errors "Throws an error if the sequence has less than four elements." } ;
  18
  19 HELP: index
  20 { $values { "obj" "an object" } { "seq" "a sequence" } }
  21 { $description "Outputs the index of the first element in the sequence equal to " { $snippet "obj" } ". If no element is found, outputs -1." }
  22 { $see-also index* member? } ;
  23
  24 HELP: index*
  25 { $values { "obj" "an object" } { "i" "a start index" } { "seq" "a sequence" } }
  26 { $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." }
  27 { $see-also index member? } ;
  28
  29 HELP: last-index
  30 { $values { "obj" "an object" } { "seq" "a sequence" } }
  31 { $description "Outputs the index of the last element in the sequence equal to " { $snippet "obj" } "; the sequence is traversed back to front. If no element is found, outputs -1." }
  32 { $see-also index* member? } ;
  33
  34 HELP: last-index*
  35 { $values { "obj" "an object" } { "i" "a start index" } { "seq" "a sequence" } }
  36 { $description "Outputs the index of the last element in the sequence equal to " { $snippet "obj" } ", traversing the sequence backwards starting from the " { $snippet "i" } "th element and finishing at the first. If no element is found, outputs -1." }
  37 { $see-also index member? } ;
  38
  39 HELP: member?
  40 { $values { "obj" "an object" } { "seq" "a sequence" } }
  41 { $description "Tests if the sequence contains an element equal to the object." }
  42 { $see-also index index* memq? } ;
  43
  44 HELP: memq?
  45 { $values { "obj" "an object" } { "seq" "a sequence" } }
  46 { $description "Tests if the sequence contains the object." }
  47 { $examples
  48     "This word uses identity comparison, so the following will most likely print " { $link f } ":"
  49     { $example "\"hello\" { \"hello\" } memq? ." "f" }
  50 }
  51 { $see-also index index* member? } ;
  52
  53 HELP: remove
  54 { $values { "elt" "an object" } { "seq" "a sequence" } { "newseq" "a new sequence" } }
  55 { $description "Outputs a new sequence containing all elements of the input sequence except those equal to the given element." } ;
  56
  57 HELP: subst
  58 { $values { "newseq" "a sequence" } { "oldseq" "a mutable sequence" } { "seq" "a sequence" } }
  59 { $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." }
  60 { $side-effects "seq" } ;
  61
  62 HELP: move
  63 { $values { "m" "an index in " { $snippet "seq" } } { "n" "an index in " { $snippet "seq" } } { "seq" "a mutable sequence" } }
  64 { $description "Sets the element with index " { $snippet "m" } " to the element with index " { $snippet "n" } "." }
  65 { $side-effects "seq" } ;
  66
  67 HELP: delete
  68 { $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
  69 { $description "Removes all elements equal to " { $snippet "elt" } " from " { $snippet "seq" } "." }
  70 { $side-effects "seq" } ;
  71
  72 HELP: push-new
  73 { $values { "elt" "an object" } { "seq" "a resizable mutable sequence" } }
  74 { $description "Removes all elements equal to " { $snippet "elt" } ", and adds " { $snippet "elt" } " at the end of the sequence." }
  75 { $examples
  76     { $example
  77         "V{ \"beans\" \"salsa\" \"cheese\" } \"v\" set"
  78         "\"nachos\" \"v\" get push-new"
  79         "\"salsa\" \"v\" get push-new"
  80         "\"v\" get ."
  81         "V{ \"beans\" \"cheese\" \"nachos\" \"salsa\" }"
  82     }
  83 }
  84 { $side-effects "seq" }
  85 { $see-also push } ;
  86
  87 HELP: prune
  88 { $values { "seq" "a sequence" } { "newseq" "a sequence" } }
  89 { $description "Outputs a new sequence with each distinct element of " { $snippet "seq" } " appearing only once. Elements are compared for equality using " { $link = } " and elements are ordered according to their position in " { $snippet "seq" } "." } ;
  90
  91 HELP: nappend
  92 { $values { "dest" "a resizable mutable sequence" } { "src" "a sequence" } }
  93 { $description "Appends " { $snippet "src" } " to the end of " { $snippet "dest" } "." }
  94 { $side-effects "dest" }
  95 { $errors "Throws an error if " { $snippet "src" } " contains elements not permitted in " { $snippet "dest" } "." } ;
  96
  97 HELP: add
  98 { $values { "seq" "a sequence" } { "elt" "an object" } { "newseq" "a sequence" } }
  99 { $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the end of " { $snippet "seq" } "." }
 100 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 101 { $examples
 102     { $example "{ 1 2 3 } 4 add ." "{ 1 2 3 4 }" }
 103 } ;
 104
 105 HELP: add*
 106 { $values { "seq" "a sequence" } { "elt" "an object" } { "newseq" "a sequence" } }
 107 { $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the beginning of " { $snippet "seq" } "." }
 108 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 109 { $examples
 110     { $example "{ 1 2 3 } 0 add* ." "{ 0 1 2 3 }" }
 111 } ;
 112
 113 HELP: diff
 114 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "newseq" "a sequence" } }
 115 { $description "Outputs a sequence consisting of elements present in " { $snippet "seq2" } " but not " { $snippet "seq1" } ", comparing elements for equality." } ;
 116
 117 HELP: append
 118 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "newseq" "a sequence" } }
 119 { $description "Outputs a new sequence of the same type as " { $snippet "seq1" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." }
 120 { $errors "Throws an error if " { $snippet "seq2" } " contains elements not permitted in sequences of the same class as " { $snippet "seq1" } "." } ;
 121
 122 HELP: 3append
 123 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "seq3" "a sequence" } { "newseq" "a sequence" } }
 124 { $description "Outputs a new sequence consisting of the elements of " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn." }
 125 { $errors "Throws an error if " { $snippet "seq2" } " or " { $snippet "seq3" } " contain elements not permitted in sequences of the same class as " { $snippet "seq1" } "." } ;
 126
 127 HELP: concat
 128 { $values { "seq" "a sequence" } { "newseq" "a sequence" } }
 129 { $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" } "." }
 130 { $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" } "." }
 131 { $see-also join } ;
 132
 133 HELP: peek
 134 { $values { "seq" "a sequence" } { "elt" "an object" } }
 135 { $description "Outputs the last element of a sequence." }
 136 { $errors "Throws an error if the sequence is empty." }
 137 { $see-also pop* pop } ;
 138
 139 HELP: pop*
 140 { $values { "seq" "a resizable mutable sequence" } }
 141 { $description "Removes the last element and shortens the sequence." }
 142 { $side-effects "seq" }
 143 { $errors "Throws an error if the sequence is empty." }
 144 { $see-also peek pop } ;
 145
 146 HELP: pop
 147 { $values { "seq" "a resizable mutable sequence" } { "elt" "an object" } }
 148 { $description "Outputs the last element after removing it and shortening the sequence." }
 149 { $side-effects "seq" }
 150 { $errors "Throws an error if the sequence is empty." }
 151 { $see-also peek pop* } ;
 152
 153 HELP: all-equal?
 154 { $values { "seq" "a sequence" } { "?" "a boolean" } }
 155 { $description "Tests if all elements in the sequence are equal. Yields true with an empty sequence." } ;
 156
 157 HELP: all-eq?
 158 { $values { "seq" "a sequence" } { "?" "a boolean" } }
 159 { $description "Tests if all elements in the sequence are the same identical object. Yields true with an empty sequence." } ;
 160
 161 HELP: mismatch
 162 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "i" "an index" } }
 163 { $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." } ;
 164
 165 HELP: flip
 166 { $values { "matrix" "a sequence of equal-length sequences" } { "newmatrix" "a sequence of equal-length sequences" } }
 167 { $description "Transposes the matrix; that is, rows become columns and columns become rows." }
 168 { $examples { $example "{ { 1 2 3 } { 4 5 6 } } flip ." "{ { 1 4 } { 2 5 } { 3 6 } }" } } ;
 169
 170 HELP: unpair
 171 { $values { "assoc" "a sequence of pairs" } { "keys" "a new sequence" } { "values" "a new sequence" } }
 172 { $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." } ;
 173
 174 HELP: exchange
 175 { $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
 176 { $description "Exchanges the " { $snippet "m" } "th and " { $snippet "n" } "th elements of " { $snippet "seq" } "." } ;
 177
 178 HELP: assoc
 179 { $values { "key" "an object" } { "assoc" "a sequence of pairs" } { "value" "the associated value, or " { $link f } } }
 180 { $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." }
 181 { $see-also rassoc } ;
 182
 183 HELP: rassoc
 184 { $values { "value" "an object" } { "assoc" "a sequence of pairs" } { "key" "the associated key, or " { $link f } } }
 185 { $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." }
 186 { $see-also rassoc } ;
 187
 188 HELP: last/first
 189 { $values { "seq" "a sequence" } { "pair" "a two-element array" } }
 190 { $description "Creates an array holding the first and last element of the sequence." } ;
 191
 192 HELP: padding
 193 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
 194 { $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." } ;
 195
 196 HELP: pad-left
 197 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
 198 { $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" } "." }
 199 { $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-left print ] each" "---ab\n-quux" } } ;
 200
 201 HELP: pad-right
 202 { $values { "seq" "a sequence" } { "n" "a non-negative integer" } { "elt" "an object"} { "padded" "a new sequence" } }
 203 { $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" } "." }
 204 { $examples { $example "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-right print ] each" "ab---\nquux-" } } ;
 205
 206 HELP: sequence=
 207 { $values { "seq1" "a sequence" } { "seq2" "a sequence" } { "?" "a boolean" } }
 208 { $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." } ;
 209
 210 HELP: depth
 211 { $values { "n" "a non-negative integer" } }
 212 { $description "Outputs the number of elements on the data stack." } ;
 213
 214 HELP: cond
 215 { $values { "assoc" "a sequence of quotation pairs" } }
 216 { $description
 217     "Calls the second quotation in the first pair whose first quotation yields a true value."
 218     $terpri
 219     "The following two phrases are equivalent:"
 220     { $code "{ { [ X ] [ Y ] } { [ Z ] [ T ] } } cond" }
 221     { $code "X [ Y ] [ Z [ T ] [ no-cond ] if ] if" }
 222 }
 223 { $errors "Throws a " { $link no-cond } " error if none of the test quotations yield a true value." }
 224 { $examples
 225     { $code
 226         "{"
 227         "    { [ dup 0 > ] [ \"positive\" ] }"
 228         "    { [ dup 0 < ] [ \"negative\" ] }"
 229         "    { [ dup zero? ] [ \"zero\" ] }"
 230         "} cond"
 231     }
 232 } ;
 233
 234 HELP: no-cond
 235 { $description "Throws a " { $link no-cond } " error." }
 236 { $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." } ;
 237
 238 HELP: unix?
 239 { $values { "?" "a boolean" } }
 240 { $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." } ;