core/sequences/sequences-docs.factor

   1 USING: arrays help.markup help.syntax math
   2 sequences.private vectors strings kernel math.order layouts
   3 quotations generic.single ;
   4 IN: sequences
   5
   6 HELP: sequence
   7 { $class-description "A mixin class whose instances are sequences. Custom implementations of the sequence protocol should be declared as instances of this mixin for all sequence functionality to work correctly:"
   8     { $code "INSTANCE: my-sequence sequence" }
   9 } ;
  10
  11 HELP: length
  12 { $values { "seq" sequence } { "n" "a non-negative integer" } }
  13 { $contract "Outputs the length of the sequence. All sequences support this operation." } ;
  14
  15 HELP: set-length
  16 { $values { "n" "a non-negative integer" } { "seq" "a resizable sequence" } }
  17 { $contract "Resizes a sequence. The initial contents of the new area is undefined." }
  18 { $errors "Throws a " { $link no-method  } " error if the sequence is not resizable, and a " { $link bounds-error } " if the new length is negative." }
  19 { $side-effects "seq" } ;
  20
  21 HELP: lengthen
  22 { $values { "n" "a non-negative integer" } { "seq" "a resizable sequence" } }
  23 { $contract "Ensures the sequence has a length of at least " { $snippet "n" } " elements. This word differs from " { $link set-length } " in two respects:"
  24     { $list
  25         { "This word does not shrink the sequence if " { $snippet "n" } " is less than its length." }
  26         { "The word doubles the underlying storage of " { $snippet "seq" } ", whereas " { $link set-length } " is permitted to set it to equal " { $snippet "n" } ". This ensures that repeated calls to this word with constant increments of " { $snippet "n" } " do not result in a quadratic amount of copying, so that for example " { $link push-all } " can run efficiently when used in a loop." }
  27     }
  28 } ;
  29
  30 HELP: nth
  31 { $values { "n" "a non-negative integer" } { "seq" sequence } { "elt" "the element at the " { $snippet "n" } "th index" } }
  32 { $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." }
  33 { $errors "Throws a " { $link bounds-error } " if the index is negative, or greater than or equal to the length of the sequence." } ;
  34
  35 HELP: set-nth
  36 { $values { "elt" object } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
  37 { $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." }
  38 { $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."
  39 $nl
  40 "Throws an error if the sequence cannot hold elements of the given type." }
  41 { $side-effects "seq" } ;
  42
  43 HELP: nths
  44 { $values
  45      { "indices" sequence } { "seq" sequence }
  46      { "seq'" sequence } }
  47 { $description "Outputs a sequence of elements from the input sequence indexed by the indices." }
  48 { $examples
  49     { $example "USING: prettyprint sequences ;"
  50                "{ 0 2 } { \"a\" \"b\" \"c\" } nths ."
  51                "{ \"a\" \"c\" }"
  52     }
  53 } ;
  54
  55 HELP: immutable
  56 { $values { "seq" sequence } }
  57 { $description "Throws an " { $link immutable } " error." }
  58 { $error-description "Thrown if an attempt is made to modify an immutable sequence." } ;
  59
  60 HELP: new-sequence
  61 { $values { "len" "a non-negative integer" } { "seq" sequence } { "newseq" "a mutable sequence" } }
  62 { $contract "Outputs a mutable sequence of length " { $snippet "n" } " which can hold the elements of " { $snippet "seq" } ". The initial contents of the sequence are undefined." } ;
  63
  64 HELP: new-resizable
  65 { $values { "len" "a non-negative integer" } { "seq" sequence } { "newseq" "a resizable mutable sequence" } }
  66 { $contract "Outputs a resizable mutable sequence with an initial capacity of " { $snippet "n" } " elements and zero length, which can hold the elements of " { $snippet "seq" } "." }
  67 { $examples
  68     { $example "USING: prettyprint sequences ;" "300 V{ } new-resizable ." "V{ }" }
  69     { $example "USING: prettyprint sequences ;" "300 SBUF\" \" new-resizable ." "SBUF\" \"" }
  70 } ;
  71
  72 HELP: like
  73 { $values { "seq" sequence } { "exemplar" sequence } { "newseq" "a new sequence" } }
  74 { $contract "Outputs a sequence with the same elements as " { $snippet "seq" } ", 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."
  75 $nl
  76 "The default implementation does nothing." }
  77 { $notes "Unlike " { $link clone-like } ", the output sequence might share storage with the input sequence." } ;
  78
  79 HELP: empty?
  80 { $values { "seq" sequence } { "?" "a boolean" } }
  81 { $description "Tests if the sequence has zero length." } ;
  82
  83 HELP: if-empty
  84 { $values { "seq" sequence } { "quot1" quotation } { "quot2" quotation } }
  85 { $description "Makes an implicit check if the sequence is empty. An empty sequence is dropped and " { $snippet "quot1" } " is called. Otherwise, if the sequence has any elements, " { $snippet "quot2" } " is called on it." }
  86 { $example
  87     "USING: kernel prettyprint sequences ;"
  88     "{ 1 2 3 } [ \"empty sequence\" ] [ sum ] if-empty ."
  89     "6"
  90 } ;
  91
  92 HELP: when-empty
  93 { $values
  94      { "seq" sequence } { "quot" "the first quotation of an " { $link if-empty } } }
  95 { $description "Makes an implicit check if the sequence is empty. An empty sequence is dropped and the " { $snippet "quot" } " is called." }
  96 { $examples "This word is equivalent to " { $link if-empty } " with an empty second quotation:"
  97     { $example
  98     "USING: sequences prettyprint ;"
  99     "{ } [ { 4 5 6 } ] [ ] if-empty ."
 100     "{ 4 5 6 }"
 101     }
 102     { $example
 103     "USING: sequences prettyprint ;"
 104     "{ } [ { 4 5 6 } ] when-empty ."
 105     "{ 4 5 6 }"
 106     }
 107 } ;
 108
 109 HELP: unless-empty
 110 { $values
 111      { "seq" sequence } { "quot" "the second quotation of an " { $link if-empty } } }
 112 { $description "Makes an implicit check if the sequence is empty. An empty sequence is dropped. Otherwise, the " { $snippet "quot" } " is called on the sequence." }
 113 { $examples "This word is equivalent to " { $link if-empty } " with an empty first quotation:"
 114     { $example
 115     "USING: sequences prettyprint ;"
 116     "{ 4 5 6 } [ ] [ sum ] if-empty ."
 117     "15"
 118     }
 119     { $example
 120     "USING: sequences prettyprint ;"
 121     "{ 4 5 6 } [ sum ] unless-empty ."
 122     "15"
 123     }
 124 } ;
 125
 126 HELP: delete-all
 127 { $values { "seq" "a resizable sequence" } }
 128 { $description "Resizes the sequence to zero length, removing all elements. Not all sequences are resizable." }
 129 { $errors "Throws a " { $link bounds-error } " if the new length is negative, or if the sequence is not resizable." }
 130 { $side-effects "seq" } ;
 131
 132 HELP: resize
 133 { $values { "n" "a non-negative integer" } { "seq" sequence } { "newseq" "a new sequence" } }
 134 { $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." }
 135 { $notes "This generic word is only implemented for strings and arrays." } ;
 136
 137 HELP: first
 138 { $values { "seq" sequence } { "first" "the first element of the sequence" } }
 139 { $description "Outputs the first element of the sequence." }
 140 { $errors "Throws an error if the sequence is empty." } ;
 141
 142 HELP: second
 143 { $values { "seq" sequence } { "second" "the second element of the sequence" } }
 144 { $description "Outputs the second element of the sequence." }
 145 { $errors "Throws an error if the sequence contains less than two elements." } ;
 146
 147 HELP: third
 148 { $values { "seq" sequence } { "third" "the third element of the sequence" } }
 149 { $description "Outputs the third element of the sequence." }
 150 { $errors "Throws an error if the sequence contains less than three elements." } ;
 151
 152 HELP: fourth
 153 { $values { "seq" sequence } { "fourth" "the fourth element of the sequence" } }
 154 { $description "Outputs the fourth element of the sequence." }
 155 { $errors "Throws an error if the sequence contains less than four elements." } ;
 156
 157 HELP: push
 158 { $values { "elt" object } { "seq" "a resizable mutable sequence" } }
 159 { $description "Adds an element at the end of the sequence. The sequence length is adjusted accordingly." }
 160 { $errors "Throws an error if " { $snippet "seq" } " is not resizable, or if the type of " { $snippet "elt" } " is not permitted in " { $snippet "seq" } "." }
 161 { $side-effects "seq" } ;
 162
 163 HELP: bounds-check?
 164 { $values { "n" "an integer" } { "seq" sequence } { "?" "a boolean" } }
 165 { $description "Tests if the index is within the bounds of the sequence." } ;
 166
 167 HELP: bounds-error
 168 { $values { "n" "a positive integer" } { "seq" sequence } }
 169 { $description "Throws a " { $link bounds-error } "." }
 170 { $error-description "Thrown by " { $link nth } ", " { $link set-nth } " and " { $link set-length } " if the given index lies beyond the bounds of the sequence." } ;
 171
 172 HELP: bounds-check
 173 { $values { "n" "a positive integer" } { "seq" sequence } }
 174 { $description "Throws an error if " { $snippet "n" } " is negative or if it is greater than or equal to the length of " { $snippet "seq" } ". Otherwise the two inputs remain on the stack." } ;
 175
 176 HELP: ?nth
 177 { $values { "n" "an integer" } { "seq" sequence } { "elt/f" "an object or " { $link f } } }
 178 { $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 } "." } ;
 179
 180 HELP: nth-unsafe
 181 { $values { "n" "an integer" } { "seq" sequence } { "elt" object } }
 182 { $contract "Unsafe variant of " { $link nth } " that does not perform bounds checks." } ;
 183
 184 HELP: set-nth-unsafe
 185 { $values { "elt" object } { "n" "an integer" } { "seq" sequence } }
 186 { $contract "Unsafe variant of " { $link set-nth } " that does not perform bounds checks." } ;
 187
 188 HELP: exchange-unsafe
 189 { $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
 190 { $description "Unsafe variant of " { $link exchange } " that does not perform bounds checks." } ;
 191
 192 HELP: first-unsafe
 193 { $values { "seq" sequence } { "first" "the first element" } }
 194 { $contract "Unsafe variant of " { $link first } " that does not perform bounds checks." } ;
 195
 196 HELP: first2-unsafe
 197 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } }
 198 { $contract "Unsafe variant of " { $link first2 } " that does not perform bounds checks." } ;
 199
 200 HELP: first3-unsafe
 201 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } }
 202 { $contract "Unsafe variant of " { $link first3 } " that does not perform bounds checks." } ;
 203
 204 HELP: first4-unsafe
 205 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } { "fourth" "the fourth element" } }
 206 { $contract "Unsafe variant of " { $link first4 } " that does not perform bounds checks." } ;
 207
 208 HELP: 1sequence
 209 { $values { "obj" object } { "exemplar" sequence } { "seq" sequence } }
 210 { $description "Creates a one-element sequence of the same type as " { $snippet "exemplar" } "." } ;
 211
 212 HELP: 2sequence
 213 { $values { "obj1" object } { "obj2" object } { "exemplar" sequence } { "seq" sequence } }
 214 { $description "Creates a two-element sequence of the same type as " { $snippet "exemplar" } "." } ;
 215
 216 HELP: 3sequence
 217 { $values { "obj1" object } { "obj2" object } { "obj3" object } { "exemplar" sequence } { "seq" sequence } }
 218 { $description "Creates a three-element sequence of the same type as " { $snippet "exemplar" } "." } ;
 219
 220 HELP: 4sequence
 221 { $values { "obj1" object } { "obj2" object } { "obj3" object } { "obj4" object } { "exemplar" sequence } { "seq" sequence } }
 222 { $description "Creates a four-element sequence of the same type as " { $snippet "exemplar" } "." } ;
 223
 224 HELP: first2
 225 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } }
 226 { $description "Pushes the first two elements of a sequence." }
 227 { $errors "Throws an error if the sequence has less than two elements." } ;
 228
 229 HELP: first3
 230 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } }
 231 { $description "Pushes the first three elements of a sequence." }
 232 { $errors "Throws an error if the sequence has less than three elements." } ;
 233
 234 HELP: first4
 235 { $values { "seq" sequence } { "first" "the first element" } { "second" "the second element" } { "third" "the third element" } { "fourth" "the fourth element" } }
 236 { $description "Pushes the first four elements of a sequence." }
 237 { $errors "Throws an error if the sequence has less than four elements." } ;
 238
 239 HELP: array-capacity
 240 { $values { "array" "an array" } { "n" "a non-negative fixnum" } }
 241 { $class-description "A predicate class whose instances are valid array sizes for the current architecture. The minimum value is zero and the maximum value is " { $link max-array-capacity } "." }
 242 { $description "Low-level array length accessor." }
 243 { $warning "This word is in the " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types, so improper use can corrupt memory." } ;
 244
 245 HELP: array-nth
 246 { $values { "n" "a non-negative fixnum" } { "array" "an array" }  { "elt" object } }
 247 { $description "Low-level array element accessor." }
 248 { $warning "This word is in the " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link nth } " instead." } ;
 249
 250 HELP: set-array-nth
 251 { $values { "elt" object } { "n" "a non-negative fixnum" } { "array" "an array" }  }
 252 { $description "Low-level array element mutator." }
 253 { $warning "This word is in the " { $vocab-link "sequences.private" } " vocabulary because it is unsafe. It does not check types or array bounds, and improper use can corrupt memory. User code must use " { $link set-nth } " instead." } ;
 254
 255 HELP: collect
 256 { $values { "n" "a non-negative integer" } { "quot" { $quotation "( n -- value )" } } { "into" "a sequence of length at least " { $snippet "n" } } }
 257 { $description "A primitive mapping operation that applies a quotation to all integers from 0 up to but not including " { $snippet "n" } ", and collects the results in a new array. User code should use " { $link map } " instead." } ;
 258
 259 HELP: each
 260 { $values { "seq" sequence } { "quot" { $quotation "( elt -- )" } } }
 261 { $description "Applies the quotation to each element of the sequence in order." } ;
 262
 263 HELP: reduce
 264 { $values { "seq" sequence } { "identity" object } { "quot" { $quotation "( prev elt -- next )" } } { "result" "the final result" } }
 265 { $description "Combines successive elements of the sequence using a binary operation, and outputs the final result. On the first iteration, the two inputs to the quotation are " { $snippet "identity" } ", and the first element of the sequence. On successive iterations, the first input is the result of the previous iteration, and the second input is the corresponding element of the sequence." }
 266 { $examples
 267     { $example "USING: math prettyprint sequences ;" "{ 1 5 3 } 0 [ + ] reduce ." "9" }
 268 } ;
 269
 270 HELP: reduce-index
 271 { $values
 272      { "seq" sequence } { "identity" object } { "quot" quotation } }
 273 { $description "Combines successive elements of the sequence and their indices binary operations, and outputs the final result. On the first iteration, the three inputs to the quotation are " { $snippet "identity" } ", the first element of the sequence, and its index, 0. On successive iterations, the first input is the result of the previous iteration, the second input is the corresponding element of the sequence, and the third is its index." }
 274 { $examples { $example "USING: sequences prettyprint math ;"
 275     "{ 10 50 90 } 0 [ + + ] reduce-index ."
 276     "153"
 277 } } ;
 278
 279 HELP: accumulate-as
 280 { $values { "seq" sequence } { "identity" object } { "quot" { $quotation "( prev elt -- next )" } } { "exemplar" sequence } { "final" "the final result" } { "newseq" "a new sequence" } }
 281 { $description "Combines successive elements of the sequence using a binary operation, and outputs a sequence of the same type as " { $snippet "exemplar" } " containing intermediate results, together with the final result."
 282 $nl
 283 "The first element of the new sequence is " { $snippet "identity" } ". Then, on the first iteration, the two inputs to the quotation are " { $snippet "identity" } ", and the first element of the old sequence. On successive iterations, the first input is the result of the previous iteration, and the second input is the corresponding element of the old sequence."
 284 $nl
 285 "When given the empty sequence, outputs an empty sequence together with the " { $snippet "identity" } "." } ;
 286
 287 HELP: accumulate
 288 { $values { "seq" sequence } { "identity" object } { "quot" { $quotation "( prev elt -- next )" } } { "final" "the final result" } { "newseq" "a new array" } }
 289 { $description "Combines successive elements of the sequence using a binary operation, and outputs an array of intermediate results, together with the final result."
 290 $nl
 291 "The first element of the new sequence is " { $snippet "identity" } ". Then, on the first iteration, the two inputs to the quotation are " { $snippet "identity" } ", and the first element of the old sequence. On successive iterations, the first input is the result of the previous iteration, and the second input is the corresponding element of the old sequence."
 292 $nl
 293 "When given the empty sequence, outputs an empty sequence together with the " { $snippet "identity" } "." }
 294 { $examples
 295     { $example "USING: math prettyprint sequences ;" "{ 2 2 2 2 2 } 0 [ + ] accumulate . ." "{ 0 2 4 6 8 }\n10" }
 296 } ;
 297
 298 HELP: map
 299 { $values { "seq" sequence } { "quot" { $quotation "( old -- new )" } } { "newseq" "a new sequence" } }
 300 { $description "Applies the quotation to each element of the sequence in order. The new elements are collected into a sequence of the same class as the input sequence." } ;
 301
 302 HELP: map-as
 303 { $values { "seq" sequence } { "quot" { $quotation "( old -- new )" } } { "exemplar" sequence } { "newseq" "a new sequence" } }
 304 { $description "Applies the quotation to each element of the sequence in order. The new elements are collected into a sequence of the same class as " { $snippet "exemplar" } "." }
 305 { $examples
 306     "The following example converts a string into an array of one-element strings:"
 307     { $example "USING: prettyprint strings sequences ;" "\"Hello\" [ 1string ] { } map-as ." "{ \"H\" \"e\" \"l\" \"l\" \"o\" }" }
 308     "Note that " { $link map } " could not be used here, because it would create another string to hold results, and one-element strings cannot themselves be elements of strings."
 309 } ;
 310
 311 HELP: each-index
 312 { $values
 313      { "seq" sequence } { "quot" quotation } }
 314 { $description "Calls the quotation with the element of the sequence and its index on the stack, with the index on the top of the stack." }
 315 { $examples { $example "USING: sequences prettyprint math ;"
 316 "{ 10 20 30 } [ + . ] each-index"
 317 "10\n21\n32"
 318 } } ;
 319
 320 HELP: map-index
 321 { $values
 322   { "seq" sequence } { "quot" quotation } { "newseq" sequence } }
 323 { $description "Calls the quotation with the element of the sequence and its index on the stack, with the index on the top of the stack. Collects the outputs of the quotation and outputs them in a sequence of the same type as the input sequence." }
 324 { $examples { $example "USING: sequences prettyprint math ;"
 325 "{ 10 20 30 } [ + ] map-index ."
 326 "{ 10 21 32 }"
 327 } } ;
 328
 329 HELP: change-nth
 330 { $values { "i" "a non-negative integer" } { "seq" "a mutable sequence" } { "quot" { $quotation "( elt -- newelt )" } } }
 331 { $description "Applies the quotation to the " { $snippet "i" } "th element of the sequence, storing the result back into the sequence." }
 332 { $errors "Throws an error if the sequence is immutable, if the index is out of bounds, or the sequence cannot hold elements of the type output by " { $snippet "quot" } "." }
 333 { $side-effects "seq" } ;
 334
 335 HELP: map!
 336 { $values { "seq" "a mutable sequence" } { "quot" { $quotation "( old -- new )" } } { "seq" "a mutable sequence" } }
 337 { $description "Applies the quotation to each element yielding a new element, storing the new elements back in the original sequence. Returns the original sequence." }
 338 { $errors "Throws an error if the sequence is immutable, or the sequence cannot hold elements of the type output by " { $snippet "quot" } "." }
 339 { $side-effects "seq" } ;
 340
 341 HELP: min-length
 342 { $values { "seq1" sequence } { "seq2" sequence } { "n" "a non-negative integer" } }
 343 { $description "Outputs the minimum of the lengths of the two sequences." } ;
 344
 345 HELP: max-length
 346 { $values { "seq1" sequence } { "seq2" sequence } { "n" "a non-negative integer" } }
 347 { $description "Outputs the maximum of the lengths of the two sequences." } ;
 348
 349 HELP: 2each
 350 { $values { "seq1" sequence } { "seq2" sequence } { "quot" { $quotation "( elt1 elt2 -- )" } } }
 351 { $description "Applies the quotation to pairs of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } "." } ;
 352
 353 HELP: 3each
 354 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" { $quotation "( elt1 elt2 elt3 -- )" } } }
 355 { $description "Applies the quotation to triples of elements from " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } "." } ;
 356
 357 HELP: 2reduce
 358 { $values { "seq1" sequence }
 359           { "seq2" sequence }
 360           { "identity" object }
 361           { "quot" { $quotation "( prev elt1 elt2 -- next )" } }
 362           { "result" "the final result" } }
 363 { $description "Combines successive pairs of elements from the two sequences using a ternary operation. The first input value at each iteration except the first one is the result of the previous iteration. The first input value at the first iteration is " { $snippet "identity" } "." } ;
 364
 365 HELP: 2map
 366 { $values { "seq1" sequence } { "seq2" sequence } { "quot" { $quotation "( elt1 elt2 -- new )" } } { "newseq" "a new sequence" } }
 367 { $description "Applies the quotation to each pair of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } "." } ;
 368
 369 HELP: 3map
 370 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" { $quotation "( elt1 elt2 elt3 -- new )" } } { "newseq" "a new sequence" } }
 371 { $description "Applies the quotation to each triple of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } "." } ;
 372
 373 HELP: 2map-as
 374 { $values { "seq1" sequence } { "seq2" sequence } { "quot" { $quotation "( elt1 elt2 -- new )" } } { "exemplar" sequence } { "newseq" "a new sequence" } }
 375 { $description "Applies the quotation to each pair of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "exemplar" } "." } ;
 376
 377 HELP: 3map-as
 378 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" { $quotation "( elt1 elt2 elt3 -- new )" } } { "exemplar" sequence } { "newseq" "a new sequence" } }
 379 { $description "Applies the quotation to each triple of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "exemplar" } "." } ;
 380
 381 HELP: 2all?
 382 { $values { "seq1" sequence } { "seq2" sequence } { "quot" { $quotation "( elt1 elt2 -- ? )" } } { "?" "a boolean" } }
 383 { $description "Tests the predicate pairwise against elements of " { $snippet "seq1" } " and " { $snippet "seq2" } "." } ;
 384
 385 HELP: find
 386 { $values { "seq" sequence }
 387           { "quot" { $quotation "( elt -- ? )" } }
 388           { "i" "the index of the first match, or " { $link f } }
 389           { "elt" "the first matching element, or " { $link f } } }
 390 { $description "A simpler variant of " { $link find-from } " where the starting index is 0." } ;
 391
 392 HELP: find-from
 393 { $values { "n" "a starting index" }
 394           { "seq" sequence }
 395           { "quot" { $quotation "( elt -- ? )" } }
 396           { "i" "the index of the first match, or " { $link f } }
 397           { "elt" "the first matching element, or " { $link f } } }
 398 { $description "Applies the quotation to each element of the sequence in turn, until it outputs a true value or the end of the sequence is reached. If the quotation yields a true value for some sequence element, the word outputs the element index and the element itself. Otherwise, the word outputs an index of f and " { $link f } " as the element." } ;
 399
 400 HELP: find-last
 401 { $values { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } }
 402 { $description "A simpler variant of " { $link find-last-from } " where the starting index is one less than the length of the sequence." } ;
 403
 404 HELP: find-last-from
 405 { $values { "n" "a starting index" } { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "i" "the index of the first match, or f" } { "elt" "the first matching element, or " { $link f } } }
 406 { $description "Applies the quotation to each element of the sequence in reverse order, until it outputs a true value or the start of the sequence is reached. If the quotation yields a true value for some sequence element, the word outputs the element index and the element itself. Otherwise, the word outputs an index of f and " { $link f } " as the element." } ;
 407
 408 HELP: map-find
 409 { $values { "seq" sequence } { "quot" { $quotation "( elt -- result/f )" } } { "result" "the first non-false result of the quotation" } { "elt" "the first matching element, or " { $link f } } }
 410 { $description "Applies the quotation to each element of the sequence, until the quotation outputs a true value. If the quotation ever yields a result which is not " { $link f } ", then the value is output, along with the element of the sequence which yielded this." } ;
 411
 412 HELP: any?
 413 { $values { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "?" "a boolean" } }
 414 { $description "Tests if the sequence contains an element satisfying the predicate, by applying the predicate to each element in turn until a true value is found. If the sequence is empty or if the end of the sequence is reached, outputs " { $link f } "." } ;
 415
 416 HELP: all?
 417 { $values { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "?" "a boolean" } }
 418 { $description "Tests if all elements in the sequence satisfy the predicate by checking each element in turn. Given an empty sequence, vacuously outputs " { $link t } "." } ;
 419
 420 HELP: push-if
 421 { $values { "elt" object } { "quot" { $quotation "( elt -- ? )" } } { "accum" "a resizable mutable sequence" } }
 422 { $description "Adds the element at the end of the sequence if the quotation yields a true value." }
 423 { $notes "This word is a factor of " { $link filter } "." } ;
 424
 425 HELP: filter
 426 { $values { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "subseq" "a new sequence" } }
 427 { $description "Applies the quotation to each element in turn, and outputs a new sequence containing the elements of the original sequence for which the quotation output a true value." } ;
 428
 429 HELP: filter-as
 430 { $values { "seq" sequence } { "quot" { $quotation "( elt -- ? )" } } { "exemplar" sequence } { "subseq" "a new sequence" } }
 431 { $description "Applies the quotation to each element in turn, and outputs a new sequence of the same type as " { $snippet "exemplar" } " containing the elements of the original sequence for which the quotation output a true value." } ;
 432
 433 HELP: filter!
 434 { $values { "seq" "a resizable mutable sequence" } { "quot" { $quotation "( elt -- ? )" } } { "seq" "a resizable mutable sequence" } }
 435 { $description "Applies the quotation to each element in turn, and removes elements for which the quotation outputs a false value." }
 436 { $side-effects "seq" } ;
 437
 438 HELP: interleave
 439 { $values { "seq" sequence } { "between" "a quotation" } { "quot" { $quotation "( elt -- )" } } }
 440 { $description "Applies " { $snippet "quot" } " to each element in turn, also invoking " { $snippet "between" } " in-between each pair of elements." }
 441 { $example "USING: io sequences ;" "{ \"a\" \"b\" \"c\" } [ \"X\" write ] [ write ] interleave" "aXbXc" } ;
 442
 443 HELP: index
 444 { $values { "obj" object } { "seq" sequence } { "n" "an index" } }
 445 { $description "Outputs the index of the first element in the sequence equal to " { $snippet "obj" } ". If no element is found, outputs " { $link f } "." } ;
 446
 447 HELP: index-from
 448 { $values { "obj" object } { "i" "a start index" } { "seq" sequence } { "n" "an index" } }
 449 { $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 " { $link f } "." } ;
 450
 451 HELP: last-index
 452 { $values { "obj" object } { "seq" sequence } { "n" "an index" } }
 453 { $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 " { $link f } "." } ;
 454
 455 HELP: last-index-from
 456 { $values { "obj" object } { "i" "a start index" } { "seq" sequence } { "n" "an index" } }
 457 { $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 " { $link f } "." } ;
 458
 459 HELP: member?
 460 { $values { "elt" object } { "seq" sequence } { "?" "a boolean" } }
 461 { $description "Tests if the sequence contains an element equal to the object." }
 462 { $notes "This word uses equality comparison (" { $link = } ")." } ;
 463
 464 HELP: member-eq?
 465 { $values { "elt" object } { "seq" sequence } { "?" "a boolean" } }
 466 { $description "Tests if the sequence contains the object." }
 467 { $notes "This word uses identity comparison (" { $link eq? } ")." } ;
 468
 469 HELP: remove
 470 { $values { "elt" object } { "seq" sequence } { "newseq" "a new sequence" } }
 471 { $description "Outputs a new sequence containing all elements of the input sequence except for given element." }
 472 { $notes "This word uses equality comparison (" { $link = } ")." } ;
 473
 474 HELP: remove-eq
 475 { $values { "elt" object } { "seq" sequence } { "newseq" "a new sequence" } }
 476 { $description "Outputs a new sequence containing all elements of the input sequence except those equal to the given element." }
 477 { $notes "This word uses identity comparison (" { $link eq? } ")." } ;
 478
 479 HELP: remove-nth
 480 { $values
 481      { "n" integer } { "seq" sequence }
 482      { "seq'" sequence } }
 483 { $description "Creates a new sequence without the element at index " { $snippet "n" } "." }
 484 { $examples "Notice that the original sequence is left intact:" { $example "USING: sequences prettyprint kernel ;"
 485     "{ 1 2 3 } 1 over remove-nth . ."
 486     "{ 1 3 }\n{ 1 2 3 }"
 487 } } ;
 488
 489 HELP: move
 490 { $values { "to" "an index in " { $snippet "seq" } } { "from" "an index in " { $snippet "seq" } } { "seq" "a mutable sequence" } }
 491 { $description "Sets the element with index " { $snippet "m" } " to the element with index " { $snippet "n" } "." }
 492 { $side-effects "seq" } ;
 493
 494 HELP: remove!
 495 { $values { "elt" object } { "seq" "a resizable mutable sequence" } { "elt" object } }
 496 { $description "Removes all elements equal to " { $snippet "elt" } " from " { $snippet "seq" } " and returns " { $snippet "seq" } "." }
 497 { $notes "This word uses equality comparison (" { $link = } ")." }
 498 { $side-effects "seq" } ;
 499
 500 HELP: remove-eq!
 501 { $values { "elt" object } { "seq" "a resizable mutable sequence" } { "seq" "a resizable mutable sequence" } }
 502 { $description "Outputs a new sequence containing all elements of the input sequence except the given element." }
 503 { $notes "This word uses identity comparison (" { $link eq? } ")." }
 504 { $side-effects "seq" } ;
 505
 506 HELP: remove-nth!
 507 { $values { "n" "a non-negative integer" } { "seq" "a resizable mutable sequence" } { "seq" "a resizable mutable sequence" } }
 508 { $description "Removes the " { $snippet "n" } "th element from the sequence, shifting all other elements down and reducing its length by one." }
 509 { $side-effects "seq" } ;
 510
 511 HELP: delete-slice
 512 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" "a resizable mutable sequence" } }
 513 { $description "Removes a range of elements beginning at index " { $snippet "from" } " and ending before index " { $snippet "to" } "." }
 514 { $side-effects "seq" } ;
 515
 516 HELP: replace-slice
 517 { $values { "new" sequence } { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } { "seq'" sequence } }
 518 { $description "Replaces a range of elements beginning at index " { $snippet "from" } " and ending before index " { $snippet "to" } " with a new sequence." }
 519 { $errors "Throws an error if " { $snippet "new" } " contains elements whose types are not permissible in " { $snippet "seq" } "." } ;
 520
 521 { push prefix suffix } related-words
 522
 523 HELP: suffix
 524 { $values { "seq" sequence } { "elt" object } { "newseq" sequence } }
 525 { $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the end of " { $snippet "seq" } "." }
 526 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 527 { $examples
 528     { $example "USING: prettyprint sequences ;" "{ 1 2 3 } 4 suffix ." "{ 1 2 3 4 }" }
 529 } ;
 530
 531 HELP: suffix!
 532 { $values { "seq" sequence } { "elt" object } { "seq" sequence } }
 533 { $description "Modifiers a sequence in-place by adding " { $snippet "elt" } " to the end of " { $snippet "seq" } ". Outputs " { $snippet "seq" } "." }
 534 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq" } "." }
 535 { $examples
 536     { $example "USING: prettyprint sequences ;" "V{ 1 2 3 } 4 suffix! ." "V{ 1 2 3 4 }" }
 537 } ;
 538
 539 HELP: append!
 540 { $values { "seq1" sequence } { "seq2" sequence } { "seq1" sequence } }
 541 { $description "Modifiers " { $snippet "seq1" } " in-place by adding the elements from " { $snippet "seq2" } " to the end and outputs " { $snippet "seq1" } "." }
 542 { $examples
 543     { $example "USING: prettyprint sequences ;" "V{ 1 2 3 } { 4 5 6 } append! ." "V{ 1 2 3 4 5 6 }" }
 544 } ;
 545
 546 HELP: prefix
 547 { $values { "seq" sequence } { "elt" object } { "newseq" sequence } }
 548 { $description "Outputs a new sequence obtained by adding " { $snippet "elt" } " at the beginning of " { $snippet "seq" } "." }
 549 { $errors "Throws an error if the type of " { $snippet "elt" } " is not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 550 { $examples
 551 { $example "USING: prettyprint sequences ;" "{ 1 2 3 } 0 prefix ." "{ 0 1 2 3 }" }
 552 } ;
 553
 554 HELP: sum-lengths
 555 { $values { "seq" "a sequence of sequences" } { "n" integer } }
 556 { $description "Outputs the sum of the lengths of all sequences in " { $snippet "seq" } "." } ;
 557
 558 HELP: concat
 559 { $values { "seq" sequence } { "newseq" sequence } }
 560 { $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" } "." }
 561 { $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" } "." } ;
 562
 563 HELP: concat-as
 564 { $values { "seq" sequence } { "exemplar" sequence } { "newseq" sequence } }
 565 { $description "Concatenates a sequence of sequences together into one sequence with the same type as " { $snippet "exemplar" } "." }
 566 { $errors "Throws an error if one of the sequences in " { $snippet "seq" } " contains elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." } ;
 567
 568 HELP: join
 569 { $values { "seq" sequence } { "glue" sequence } { "newseq" sequence } }
 570 { $description "Concatenates a sequence of sequences together into one sequence, placing a copy of " { $snippet "glue" } " between each pair of sequences. The resulting sequence is of the same class as " { $snippet "glue" } "." }
 571 { $notes "If the " { $snippet "glue" } " sequence is empty, this word calls " { $link concat-as } "." }
 572 { $errors "Throws an error if one of the sequences in " { $snippet "seq" } " contains elements not permitted in sequences of the same class as " { $snippet "glue" } "." } ;
 573
 574 { join concat concat-as } related-words
 575
 576 HELP: last
 577 { $values { "seq" sequence } { "elt" object } }
 578 { $description "Outputs the last element of a sequence." }
 579 { $errors "Throws an error if the sequence is empty." } ;
 580
 581 { pop pop* } related-words
 582
 583 HELP: pop*
 584 { $values { "seq" "a resizable mutable sequence" } }
 585 { $description "Removes the last element and shortens the sequence." }
 586 { $side-effects "seq" }
 587 { $errors "Throws an error if the sequence is empty." } ;
 588
 589 HELP: pop
 590 { $values { "seq" "a resizable mutable sequence" } { "elt" object } }
 591 { $description "Outputs the last element after removing it and shortening the sequence." }
 592 { $side-effects "seq" }
 593 { $errors "Throws an error if the sequence is empty." } ;
 594
 595 HELP: mismatch
 596 { $values { "seq1" sequence } { "seq2" sequence } { "i" "an index" } }
 597 { $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." } ;
 598
 599 HELP: flip
 600 { $values { "matrix" "a sequence of equal-length sequences" } { "newmatrix" "a sequence of equal-length sequences" } }
 601 { $description "Transposes the matrix; that is, rows become columns and columns become rows." }
 602 { $examples { $example "USING: prettyprint sequences ;" "{ { 1 2 3 } { 4 5 6 } } flip ." "{ { 1 4 } { 2 5 } { 3 6 } }" } } ;
 603
 604 HELP: exchange
 605 { $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "seq" "a mutable sequence" } }
 606 { $description "Exchanges the " { $snippet "m" } "th and " { $snippet "n" } "th elements of " { $snippet "seq" } "." } ;
 607
 608 HELP: reverse!
 609 { $values { "seq" "a mutable sequence" } }
 610 { $description "Reverses a sequence in-place and outputs that sequence." }
 611 { $side-effects "seq" } ;
 612
 613 HELP: padding
 614 { $values { "seq" sequence } { "n" "a non-negative integer" } { "elt" object } { "quot" { $quotation "( seq1 seq2 -- newseq )" } } { "newseq" "a new sequence" } }
 615 { $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." } ;
 616
 617 HELP: pad-head
 618 { $values { "seq" sequence } { "n" "a non-negative integer" } { "elt" object } { "padded" "a new sequence" } }
 619 { $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" } "." }
 620 { $examples { $example "USING: io sequences ;" "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-head print ] each" "---ab\n-quux" } } ;
 621
 622 HELP: pad-tail
 623 { $values { "seq" sequence } { "n" "a non-negative integer" } { "elt" object } { "padded" "a new sequence" } }
 624 { $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" } "." }
 625 { $examples { $example "USING: io sequences ;" "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-tail print ] each" "ab---\nquux-" } } ;
 626
 627 HELP: sequence=
 628 { $values { "seq1" sequence } { "seq2" sequence } { "?" "a boolean" } }
 629 { $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." } ;
 630
 631 HELP: reversed
 632 { $class-description "A virtual sequence which presents a reversed view of an underlying sequence. New instances can be created by calling " { $link <reversed> } "." } ;
 633
 634 HELP: reverse
 635 { $values { "seq" sequence } { "newseq" "a new sequence" } }
 636 { $description "Outputs a new sequence having the same elements as " { $snippet "seq" } " but in reverse order." } ;
 637
 638 { reverse <reversed> reverse! } related-words
 639
 640 HELP: <reversed>
 641 { $values { "seq" sequence } { "reversed" "a new sequence" } }
 642 { $description "Creates an instance of the " { $link reversed } " class." }
 643 { $see-also "virtual-sequences" } ;
 644
 645 HELP: slice-error
 646 { $values { "str" "a reason" } }
 647 { $description "Throws a " { $link slice-error } "." }
 648 { $error-description "Thrown by " { $link <slice> } " if one of the following invalid conditions holds:"
 649     { $list
 650         "The start index is negative"
 651         "The end index is greater than the length of the sequence"
 652         "The start index is greater than the end index"
 653     }
 654 } ;
 655
 656 HELP: slice
 657 { $class-description "A virtual sequence which presents a subrange of the elements of an underlying sequence. New instances can be created by calling " { $link <slice> } ". Convenience words are also provided for creating slices where one endpoint is the start or end of the sequence; see " { $link "sequences-slices" } " for a list."
 658 $nl
 659 "Slices are mutable if the underlying sequence is mutable, and mutating a slice changes the underlying sequence. However, slices cannot be resized after creation." } ;
 660
 661 HELP: check-slice
 662 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } }
 663 { $description "Ensures that " { $snippet "m" } " is less than or equal to " { $snippet "m" } ", and that both indices are within bounds for " { $snippet "seq" } "." }
 664 { $errors "Throws a " { $link slice-error } " if the preconditions are not met." } ;
 665
 666 HELP: collapse-slice
 667 { $values { "m" "a non-negative integer" } { "n" "a non-negative integer" } { "slice" slice } { "m'" "a non-negative integer" } { "n'" "a non-negative integer" } { "seq" sequence } }
 668 { $description "Prepares to take the slice of a slice by adjusting the start and end indices accordingly, and replacing the slice with its underlying sequence." }
 669 ;
 670
 671 HELP: <flat-slice>
 672 { $values { "seq" sequence } { "slice" slice } }
 673 { $description "Outputs a slice with the same elements as " { $snippet "seq" } ", and " { $snippet "from" } " equal to 0 and " { $snippet "to" } " equal to the length of " { $snippet "seq" } "." }
 674 { $notes "Some words create slices then proceed to read the " { $snippet "to" } " and " { $snippet "from" } " slots of the slice. To behave predictably when they are themselves given a slice as input, they apply this word first to get a canonical slice." } ;
 675
 676 HELP: <slice>
 677 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } { "slice" slice } }
 678 { $description "Outputs a new virtual sequence sharing storage with the subrange of elements in " { $snippet "seq" } " with indices starting from and including " { $snippet "m" } ", and up to but not including " { $snippet "n" } "." }
 679 { $errors "Throws an error if " { $snippet "m" } " or " { $snippet "n" } " is out of bounds." }
 680 { $notes "Taking the slice of a slice outputs a slice of the underlying sequence of the original slice. Keep this in mind when writing code which depends on the values of " { $snippet "from" } " and " { $snippet "to" } " being equal to the inputs to this word. The " { $link <flat-slice> } " word might be helpful in such situations." } ;
 681
 682 { <slice> subseq } related-words
 683
 684 HELP: repetition
 685 { $class-description "A virtual sequence consisting of " { $snippet "elt" } " repeated " { $snippet "len" } " times. Repetitions are created by calling " { $link <repetition> } "." } ;
 686
 687 HELP: <repetition>
 688 { $values { "len" "a non-negative integer" } { "elt" object } { "repetition" repetition } }
 689 { $description "Creates a new " { $link repetition } "." }
 690 { $examples
 691     { $example "USING: arrays prettyprint sequences ;" "10 \"X\" <repetition> >array ." "{ \"X\" \"X\" \"X\" \"X\" \"X\" \"X\" \"X\" \"X\" \"X\" \"X\" }" }
 692     { $example "USING: prettyprint sequences ;" "10 \"X\" <repetition> concat ." "\"XXXXXXXXXX\"" }
 693 } ;
 694 HELP: copy
 695 { $values { "src" sequence } { "i" "an index in " { $snippet "dest" } } { "dst" "a mutable sequence" } }
 696 { $description "Copies all elements of " { $snippet "src" } " to " { $snippet "dest" } ", with destination indices starting from " { $snippet "i" } ". Grows " { $snippet "to" } " first if necessary." }
 697 { $side-effects "dest" }
 698 { $errors "An error is thrown if " { $snippet "to" } " is not resizable, and not large enough to hold the copied elements." } ;
 699
 700 HELP: push-all
 701 { $values { "src" sequence } { "dest" "a resizable mutable sequence" } }
 702 { $description "Appends " { $snippet "src" } " to the end of " { $snippet "dest" } "." }
 703 { $side-effects "dest" }
 704 { $errors "Throws an error if " { $snippet "src" } " contains elements not permitted in " { $snippet "dest" } "." } ;
 705
 706 HELP: append
 707 { $values { "seq1" sequence } { "seq2" sequence } { "newseq" sequence } }
 708 { $description "Outputs a new sequence of the same type as " { $snippet "seq1" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." }
 709 { $errors "Throws an error if " { $snippet "seq2" } " contains elements not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 710 { $examples
 711     { $example "USING: prettyprint sequences ;"
 712         "{ 1 2 } B{ 3 4 } append ."
 713         "{ 1 2 3 4 }"
 714     }
 715     { $example "USING: prettyprint sequences strings ;"
 716         "\"go\" \"ing\" append ."
 717         "\"going\""
 718     }
 719 } ;
 720
 721 HELP: append-as
 722 { $values { "seq1" sequence } { "seq2" sequence } { "exemplar" sequence } { "newseq" sequence } }
 723 { $description "Outputs a new sequence of the same type as " { $snippet "exemplar" } " consisting of the elements of " { $snippet "seq1" } " followed by " { $snippet "seq2" } "." }
 724 { $errors "Throws an error if " { $snippet "seq1" } " or " { $snippet "seq2" } " contain elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." }
 725 { $examples
 726     { $example "USING: prettyprint sequences ;"
 727         "{ 1 2 } B{ 3 4 } B{ } append-as ."
 728         "B{ 1 2 3 4 }"
 729     }
 730     { $example "USING: prettyprint sequences strings ;"
 731         "\"go\" \"ing\" SBUF\" \" append-as ."
 732         "SBUF\" going\""
 733     }
 734 } ;
 735
 736 { append append-as } related-words
 737
 738 HELP: prepend
 739 { $values { "seq1" sequence } { "seq2" sequence } { "newseq" sequence } }
 740 { $description "Outputs a new sequence of the same type as " { $snippet "seq2" } " consisting of the elements of " { $snippet "seq2" } " followed by " { $snippet "seq1" } "." }
 741 { $errors "Throws an error if " { $snippet "seq1" } " contains elements not permitted in sequences of the same class as " { $snippet "seq2" } "." }
 742 { $examples { $example "USING: prettyprint sequences ;"
 743         "{ 1 2 } B{ 3 4 } prepend ."
 744         "B{ 3 4 1 2 }"
 745     }
 746     { $example "USING: prettyprint sequences strings ;"
 747         "\"go\" \"car\" prepend ."
 748         "\"cargo\""
 749     }
 750 } ;
 751
 752 HELP: 3append
 753 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "newseq" sequence } }
 754 { $description "Outputs a new sequence consisting of the elements of " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn." }
 755 { $errors "Throws an error if " { $snippet "seq2" } " or " { $snippet "seq3" } " contain elements not permitted in sequences of the same class as " { $snippet "seq1" } "." }
 756 { $examples
 757     { $example "USING: prettyprint sequences ;"
 758         "\"a\" \"b\" \"c\" 3append ."
 759         "\"abc\""
 760     }
 761 } ;
 762
 763 HELP: 3append-as
 764 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "exemplar" sequence } { "newseq" sequence } }
 765 { $description "Outputs a new sequence consisting of the elements of " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn of the same type as " { $snippet "exemplar" } "." }
 766 { $errors "Throws an error if " { $snippet "seq1" } ", " { $snippet "seq2" } ", or " { $snippet "seq3" } " contain elements not permitted in sequences of the same class as " { $snippet "exemplar" } "." }
 767 { $examples
 768     { $example "USING: prettyprint sequences ;"
 769         "\"a\" \"b\" \"c\" SBUF\" \" 3append-as ."
 770         "SBUF\" abc\""
 771     }
 772 } ;
 773
 774 { 3append 3append-as } related-words
 775
 776 HELP: surround
 777 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "newseq" sequence } }
 778 { $description "Outputs a new sequence with " { $snippet "seq1" } " inserted between " { $snippet "seq2" } " and " { $snippet "seq3" } "." }
 779 { $examples
 780     { $example "USING: sequences prettyprint ;"
 781                "\"sssssh\" \"(\" \")\" surround ."
 782                "\"(sssssh)\""
 783     }
 784 } ;
 785
 786 HELP: glue
 787 { $values { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "newseq" sequence } }
 788 { $description "Outputs a new sequence with " { $snippet "seq3" } " inserted between " { $snippet "seq1" } " and " { $snippet "seq2" } "." }
 789 { $examples
 790     { $example "USING: sequences prettyprint ;"
 791                "\"a\" \"b\" \",\" glue ."
 792                "\"a,b\""
 793     }
 794 } ;
 795
 796 HELP: subseq
 797 { $values { "from" "a non-negative integer" } { "to" "a non-negative integer" } { "seq" sequence } { "subseq" "a new sequence" } }
 798 { $description "Outputs a new sequence consisting of all elements starting from and including " { $snippet "from" } ", and up to but not including " { $snippet "to" } "." }
 799 { $errors "Throws an error if " { $snippet "from" } " or " { $snippet "to" } " is out of bounds." } ;
 800
 801 HELP: clone-like
 802 { $values { "seq" sequence } { "exemplar" sequence } { "newseq" "a new sequence" } }
 803 { $description "Outputs a newly-allocated sequence with the same elements as " { $snippet "seq" } " but of the same type as " { $snippet "exemplar" } "." }
 804 { $notes "Unlike " { $link like } ", this word always creates a new sequence which never shares storage with the original." } ;
 805
 806 HELP: head-slice
 807 { $values { "seq" sequence } { "n" "a non-negative integer" } { "slice" "a slice" } }
 808 { $description "Outputs a virtual sequence sharing storage with the first " { $snippet "n" } " elements of the input sequence." }
 809 { $errors "Throws an error if the index is out of bounds." } ;
 810
 811 HELP: tail-slice
 812 { $values { "seq" sequence } { "n" "a non-negative integer" } { "slice" "a slice" } }
 813 { $description "Outputs a virtual sequence sharing storage with all elements from the " { $snippet "n" } "th index until the end of the input sequence." }
 814 { $errors "Throws an error if the index is out of bounds." } ;
 815
 816 HELP: but-last-slice
 817 { $values { "seq" sequence } { "slice" "a slice" } }
 818 { $description "Outputs a virtual sequence sharing storage with all but the last element of the input sequence." }
 819 { $errors "Throws an error on an empty sequence." } ;
 820
 821 HELP: rest-slice
 822 { $values { "seq" sequence } { "slice" "a slice" } }
 823 { $description "Outputs a virtual sequence sharing storage with all elements from the 1st index until the end of the input sequence." }
 824 { $notes "Equivalent to " { $snippet "1 tail" } }
 825 { $errors "Throws an error on an empty sequence." } ;
 826
 827 HELP: head-slice*
 828 { $values { "seq" sequence } { "n" "a non-negative integer" } { "slice" "a slice" } }
 829 { $description "Outputs a virtual sequence sharing storage with all elements of " { $snippet "seq" } " until the " { $snippet "n" } "th element from the end. In other words, it outputs a sequence of the first " { $snippet "l-n" } " elements of the input sequence, where " { $snippet "l" } " is its length." }
 830 { $errors "Throws an error if the index is out of bounds." } ;
 831
 832 HELP: tail-slice*
 833 { $values { "seq" sequence } { "n" "a non-negative integer" } { "slice" "a slice" } }
 834 { $description "Outputs a virtual sequence sharing storage with the last " { $snippet "n" } " elements of the input sequence." }
 835 { $errors "Throws an error if the index is out of bounds." } ;
 836
 837 HELP: head
 838 { $values { "seq" sequence } { "n" "a non-negative integer" } { "headseq" "a new sequence" } }
 839 { $description "Outputs a new sequence consisting of the first " { $snippet "n" } " elements of the input sequence." }
 840 { $errors "Throws an error if the index is out of bounds." } ;
 841
 842 HELP: tail
 843 { $values { "seq" sequence } { "n" "a non-negative integer" } { "tailseq" "a new sequence" } }
 844 { $description "Outputs a new sequence consisting of the input sequence with the first n items removed." }
 845 { $errors "Throws an error if the index is out of bounds." } ;
 846
 847 HELP: but-last
 848 { $values { "seq" sequence } { "headseq" "a new sequence" } }
 849 { $description "Outputs a new sequence consisting of the input sequence with the last item removed." }
 850 { $errors "Throws an error on an empty sequence." } ;
 851
 852 HELP: rest
 853 { $values { "seq" sequence } { "tailseq" "a new sequence" } }
 854 { $description "Outputs a new sequence consisting of the input sequence with the first item removed." }
 855 { $errors "Throws an error on an empty sequence." } ;
 856
 857 HELP: head*
 858 { $values { "seq" sequence } { "n" "a non-negative integer" } { "headseq" "a new sequence" } }
 859 { $description "Outputs a new sequence consisting of all elements of " { $snippet "seq" } " until the " { $snippet "n" } "th element from the end. In other words, it outputs a sequence of the first " { $snippet "l-n" } " elements of the input sequence, where " { $snippet "l" } " is its length." }
 860 { $errors "Throws an error if the index is out of bounds." } ;
 861
 862 HELP: tail*
 863 { $values { "seq" sequence } { "n" "a non-negative integer" } { "tailseq" "a new sequence" } }
 864 { $description "Outputs a new sequence consisting of the last " { $snippet "n" } " elements of the input sequence." }
 865 { $errors "Throws an error if the index is out of bounds." } ;
 866
 867 HELP: shorter?
 868 { $values { "seq1" sequence } { "seq2" sequence } { "?" "a boolean" } }
 869 { $description "Tets if the length of " { $snippet "seq1" } " is smaller than the length of " { $snippet "seq2" } "." } ;
 870
 871 HELP: head?
 872 { $values { "seq" sequence } { "begin" sequence } { "?" "a boolean" } }
 873 { $description "Tests if " { $snippet "seq" } " starts with " { $snippet "begin" } ". If " { $snippet "begin" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." } ;
 874
 875 HELP: tail?
 876 { $values { "seq" sequence } { "end" sequence } { "?" "a boolean" } }
 877 { $description "Tests if " { $snippet "seq" } " ends with " { $snippet "end" } ". If " { $snippet "end" } " is longer than " { $snippet "seq" } ", this word outputs " { $link f } "." } ;
 878
 879 { remove remove-nth remove-eq remove-eq! remove! remove-nth! } related-words
 880
 881 HELP: cut-slice
 882 { $values { "seq" sequence } { "n" "a non-negative integer" } { "before-slice" sequence } { "after-slice" "a slice" } }
 883 { $description "Outputs a pair of sequences, where " { $snippet "before" } " consists of the first " { $snippet "n" } " elements of " { $snippet "seq" } " and has the same type, while " { $snippet "after" } " is a slice of the remaining elements." }
 884 { $notes "Unlike " { $link cut } ", the run time of this word is proportional to the length of " { $snippet "before" } ", not " { $snippet "after" } ", so it is suitable for use in an iterative algorithm which cuts successive pieces off a sequence." } ;
 885
 886 HELP: cut
 887 { $values { "seq" sequence } { "n" "a non-negative integer" } { "before" sequence } { "after" sequence } }
 888 { $description "Outputs a pair of sequences, where " { $snippet "before" } " consists of the first " { $snippet "n" } " elements of " { $snippet "seq" } ", while " { $snippet "after" } " holds the remaining elements. Both output sequences have the same type as " { $snippet "seq" } "." }
 889 { $notes "Since this word copies the entire tail of the sequence, it should not be used in a loop. If this is important, consider using " { $link cut-slice } " instead, since it returns a slice for the tail instead of copying." } ;
 890
 891 HELP: cut*
 892 { $values { "seq" sequence } { "n" "a non-negative integer" } { "before" sequence } { "after" sequence } }
 893 { $description "Outputs a pair of sequences, where " { $snippet "after" } " consists of the last " { $snippet "n" } " elements of " { $snippet "seq" } ", while " { $snippet "before" } " holds the remaining elements. Both output sequences have the same type as " { $snippet "seq" } "." } ;
 894
 895 HELP: start*
 896 { $values { "subseq" sequence } { "seq" sequence } { "n" "a start index" } { "i" "a start index" } }
 897 { $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", starting the search from the " { $snippet "n" } "th element. If no matching subsequence is found, outputs " { $link f } "." } ;
 898
 899 HELP: start
 900 { $values { "subseq" sequence } { "seq" sequence } { "i" "a start index" } }
 901 { $description "Outputs the start index of the first contiguous subsequence equal to " { $snippet "subseq" } ", or " { $link f } " if no matching subsequence is found." } ;
 902
 903 HELP: subseq?
 904 { $values { "subseq" sequence } { "seq" sequence } { "?" "a boolean" } }
 905 { $description "Tests if " { $snippet "seq" } " contains the elements of " { $snippet "subseq" } " as a contiguous subsequence." } ;
 906
 907 HELP: drop-prefix
 908 { $values { "seq1" sequence } { "seq2" sequence } { "slice1" "a slice" } { "slice2" "a slice" } }
 909 { $description "Outputs a pair of virtual sequences with the common prefix of " { $snippet "seq1" } " and " { $snippet "seq2" } " removed." } ;
 910
 911 HELP: unclip
 912 { $values { "seq" sequence } { "rest" sequence } { "first" object } }
 913 { $description "Outputs a tail sequence and the first element of " { $snippet "seq" } "; the tail sequence consists of all elements of " { $snippet "seq" } " but the first." }
 914 { $examples
 915     { $example "USING: prettyprint sequences ;" "{ 1 2 3 } unclip suffix ." "{ 2 3 1 }" }
 916 } ;
 917
 918 HELP: unclip-slice
 919 { $values { "seq" sequence } { "rest-slice" slice } { "first" object } }
 920 { $description "Outputs a tail sequence and the first element of " { $snippet "seq" } "; the tail sequence consists of all elements of " { $snippet "seq" } " but the first. Unlike " { $link unclip } ", this word does not make a copy of the input sequence, and runs in constant time." }
 921 { $examples { $example "USING: math.order prettyprint sequences ;" "{ 3 -1 -10 5 7 } unclip-slice [ min ] reduce ." "-10" } } ;
 922
 923 HELP: unclip-last
 924 { $values { "seq" sequence } { "butlast" sequence } { "last" object } }
 925 { $description "Outputs a head sequence and the last element of " { $snippet "seq" } "; the head sequence consists of all elements of " { $snippet "seq" } " but the last." }
 926 { $examples
 927     { $example "USING: prettyprint sequences ;" "{ 1 2 3 } unclip-last prefix ." "{ 3 1 2 }" }
 928 } ;
 929
 930 HELP: unclip-last-slice
 931 { $values { "seq" sequence } { "butlast-slice" slice } { "last" object } }
 932 { $description "Outputs a head sequence and the last element of " { $snippet "seq" } "; the head sequence consists of all elements of " { $snippet "seq" } " but the last Unlike " { $link unclip-last } ", this word does not make a copy of the input sequence, and runs in constant time." } ;
 933
 934 HELP: sum
 935 { $values { "seq" "a sequence of numbers" } { "n" "a number" } }
 936 { $description "Outputs the sum of all elements of " { $snippet "seq" } ". Outputs zero given an empty sequence." } ;
 937
 938 HELP: product
 939 { $values { "seq" "a sequence of numbers" } { "n" "a number" } }
 940 { $description "Outputs the product of all elements of " { $snippet "seq" } ". Outputs one given an empty sequence." } ;
 941
 942 HELP: infimum
 943 { $values { "seq" "a sequence of real numbers" } { "n" "a number" } }
 944 { $description "Outputs the least element of " { $snippet "seq" } "." }
 945 { $errors "Throws an error if the sequence is empty." } ;
 946
 947 HELP: supremum
 948 { $values { "seq" "a sequence of real numbers" } { "n" "a number" } }
 949 { $description "Outputs the greatest element of " { $snippet "seq" } "." }
 950 { $errors "Throws an error if the sequence is empty." } ;
 951
 952 HELP: produce
 953 { $values { "pred" { $quotation "( -- ? )" } } { "quot" { $quotation "( -- obj )" } } { "seq" "a sequence" } }
 954 { $description "Calls " { $snippet "pred" } " repeatedly. If the predicate yields " { $link f } ", stops, otherwise, calls " { $snippet "quot" } " to yield a value. Values are accumulated and returned in a sequence at the end." }
 955 { $examples
 956     "The following example divides a number by two until we reach zero, and accumulates intermediate results:"
 957     { $example "USING: kernel math prettyprint sequences ;" "1337 [ dup 0 > ] [ 2/ dup ] produce nip ." "{ 668 334 167 83 41 20 10 5 2 1 0 }" }
 958     "The following example collects random numbers as long as they are greater than 1:"
 959     { $unchecked-example "USING: kernel prettyprint random sequences ;" "[ 10 random dup 1 > ] [ ] produce nip ." "{ 8 2 2 9 }" }
 960 } ;
 961
 962 HELP: produce-as
 963 { $values { "pred" { $quotation "( -- ? )" } } { "quot" { $quotation "( -- obj )" } } { "exemplar" sequence } { "seq" "a sequence" } }
 964 { $description "Calls " { $snippet "pred" } " repeatedly. If the predicate yields " { $link f } ", stops, otherwise, calls " { $snippet "quot" } " to yield a value. Values are accumulated and returned in a sequence of type " { $snippet "exemplar" } " at the end." }
 965 { $examples "See " { $link produce } " for examples." } ;
 966
 967 HELP: sigma
 968 { $values { "seq" sequence } { "quot" quotation } { "n" number } }
 969 { $description "Like map sum, but without creating an intermediate sequence." }
 970 { $example
 971     "! Find the sum of the squares [0,99]"
 972     "USING: math math.ranges sequences prettyprint ;"
 973     "100 [1,b] [ sq ] sigma ."
 974     "338350"
 975 } ;
 976
 977 HELP: count
 978 { $values { "seq" sequence } { "quot" quotation } { "n" integer } }
 979 { $description "Efficiently returns the number of elements that the predicate quotation matches." }
 980 { $example
 981     "USING: math math.ranges sequences prettyprint ;"
 982     "100 [1,b] [ even? ] count ."
 983     "50"
 984 } ;
 985
 986 HELP: pusher
 987 { $values
 988      { "quot" "a predicate quotation" }
 989      { "quot" quotation } { "accum" vector } }
 990 { $description "Creates a new vector to accumulate the values which return true for a predicate.  Returns a new quotation which accepts an object to be tested and stored in the accumulator if the test yields true. The accumulator is left on the stack for convenience." }
 991 { $example "! Find all the even numbers:" "USING: prettyprint sequences math kernel ;"
 992            "10 [ even? ] pusher [ each ] dip ."
 993            "V{ 0 2 4 6 8 }"
 994 }
 995 { $notes "Used to implement the " { $link filter } " word." } ;
 996
 997 HELP: trim-head
 998 { $values
 999      { "seq" sequence } { "quot" quotation }
1000      { "newseq" sequence } }
1001 { $description "Removes elements starting from the left side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." }
1002 { $example "" "USING: prettyprint math sequences ;"
1003            "{ 0 0 1 2 3 0 0 } [ zero? ] trim-head ."
1004            "{ 1 2 3 0 0 }"
1005 } ;
1006
1007 HELP: trim-head-slice
1008 { $values
1009      { "seq" sequence } { "quot" quotation }
1010      { "slice" slice } }
1011 { $description "Removes elements starting from the left side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice" }
1012 { $example "" "USING: prettyprint math sequences ;"
1013            "{ 0 0 1 2 3 0 0 } [ zero? ] trim-head-slice ."
1014            "T{ slice { from 2 } { to 7 } { seq { 0 0 1 2 3 0 0 } } }"
1015 } ;
1016
1017 HELP: trim-tail
1018 { $values
1019      { "seq" sequence } { "quot" quotation }
1020      { "newseq" sequence } }
1021 { $description "Removes elements starting from the right side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." }
1022 { $example "" "USING: prettyprint math sequences ;"
1023            "{ 0 0 1 2 3 0 0 } [ zero? ] trim-tail ."
1024            "{ 0 0 1 2 3 }"
1025 } ;
1026
1027 HELP: trim-tail-slice
1028 { $values
1029      { "seq" sequence } { "quot" quotation }
1030      { "slice" slice } }
1031 { $description "Removes elements starting from the right side of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice." }
1032 { $example "" "USING: prettyprint math sequences ;"
1033            "{ 0 0 1 2 3 0 0 } [ zero? ] trim-tail-slice ."
1034            "T{ slice { from 0 } { to 5 } { seq { 0 0 1 2 3 0 0 } } }"
1035 } ;
1036
1037 HELP: trim
1038 { $values
1039      { "seq" sequence } { "quot" quotation }
1040      { "newseq" sequence } }
1041 { $description "Removes elements starting from the left and right sides of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a new sequence." }
1042 { $example "" "USING: prettyprint math sequences ;"
1043            "{ 0 0 1 2 3 0 0 } [ zero? ] trim ."
1044            "{ 1 2 3 }"
1045 } ;
1046
1047 HELP: trim-slice
1048 { $values
1049      { "seq" sequence } { "quot" quotation }
1050      { "slice" slice } }
1051 { $description "Removes elements starting from the left and right sides of a sequence if they match a predicate. Once an element does not match, the test stops and the rest of the sequence is left on the stack as a slice." }
1052 { $example "" "USING: prettyprint math sequences ;"
1053            "{ 0 0 1 2 3 0 0 } [ zero? ] trim-slice ."
1054            "T{ slice { from 2 } { to 5 } { seq { 0 0 1 2 3 0 0 } } }"
1055 } ;
1056
1057 { trim trim-slice trim-head trim-head-slice trim-tail trim-tail-slice } related-words
1058
1059 HELP: sift
1060 { $values
1061      { "seq" sequence }
1062      { "newseq" sequence } }
1063  { $description "Outputs a new sequence with all instance of " { $link f  } " removed." }
1064  { $examples
1065     { $example "USING: prettyprint sequences ;"
1066         "{ \"a\" 3 { } f } sift ."
1067         "{ \"a\" 3 { } }"
1068     }
1069 } ;
1070
1071 HELP: harvest
1072 { $values
1073      { "seq" sequence }
1074      { "newseq" sequence } }
1075 { $description "Outputs a new sequence with all empty sequences removed." }
1076 { $examples
1077     { $example "USING: prettyprint sequences ;"
1078                "{ { } { 2 3 } { 5 } { } } harvest ."
1079                "{ { 2 3 } { 5 } }"
1080     }
1081 } ;
1082
1083 { filter filter! sift harvest } related-words
1084
1085 HELP: set-first
1086 { $values
1087      { "first" object } { "seq" sequence } }
1088 { $description "Sets the first element of a sequence." }
1089 { $examples
1090     { $example "USING: prettyprint kernel sequences ;"
1091         "{ 1 2 3 4  } 5 over set-first ."
1092         "{ 5 2 3 4 }"
1093     }
1094 } ;
1095
1096 HELP: set-second
1097 { $values
1098      { "second" object } { "seq" sequence } }
1099 { $description "Sets the second element of a sequence." }
1100 { $examples
1101     { $example "USING: prettyprint kernel sequences ;"
1102         "{ 1 2 3 4  } 5 over set-second ."
1103         "{ 1 5 3 4 }"
1104     }
1105 } ;
1106
1107 HELP: set-third
1108 { $values
1109      { "third" object } { "seq" sequence } }
1110 { $description "Sets the third element of a sequence." }
1111 { $examples
1112     { $example "USING: prettyprint kernel sequences ;"
1113         "{ 1 2 3 4  } 5 over set-third ."
1114         "{ 1 2 5 4 }"
1115     }
1116 } ;
1117
1118 HELP: set-fourth
1119 { $values
1120      { "fourth" object } { "seq" sequence } }
1121 { $description "Sets the fourth element of a sequence." }
1122 { $examples
1123     { $example "USING: prettyprint kernel sequences ;"
1124         "{ 1 2 3 4  } 5 over set-fourth ."
1125         "{ 1 2 3 5 }"
1126     }
1127 } ;
1128
1129 { set-first set-second set-third set-fourth } related-words
1130
1131 HELP: replicate
1132 { $values
1133      { "seq" sequence } { "quot" { $quotation "( -- elt )" } }
1134      { "newseq" sequence } }
1135 { $description "Calls the quotation for every element of the sequence in order. However, the element is not passed to the quotation -- it is dropped, and the quotation produces an element of its own that is collected into a sequence of the same class as the input sequence." }
1136 { $examples
1137     { $unchecked-example "USING: kernel prettyprint random sequences ;"
1138         "5 [ 100 random ] replicate ."
1139         "{ 52 10 45 81 30 }"
1140     }
1141 } ;
1142
1143 HELP: replicate-as
1144 { $values
1145      { "seq" sequence } { "quot" quotation } { "exemplar" sequence }
1146      { "newseq" sequence } }
1147 { $description "Calls the quotation for every element of the sequence in order. However, the element is not passed to the quotation -- it is dropped, and the quotation produces an element of its own that is collected into a sequence of the same class as the exemplar sequence." }
1148 { $examples
1149     { $unchecked-example "USING: prettyprint kernel sequences ;"
1150         "5 [ 100 random ] B{ } replicate-as ."
1151         "B{ 44 8 2 33 18 }"
1152     }
1153 } ;
1154 { replicate replicate-as } related-words
1155
1156 HELP: partition
1157 { $values
1158      { "seq" sequence } { "quot" quotation }
1159      { "trueseq" sequence } { "falseseq" sequence } }
1160      { $description "Calls a predicate quotation on each element of the input sequence.  If the test yields true, the element is added to " { $snippet "trueseq" } "; if false, it's added to " { $snippet "falseseq" } "." }
1161 { $examples
1162     { $example "USING: prettyprint kernel math sequences ;"
1163         "{ 1 2 3 4 5 } [ even? ] partition [ . ] bi@"
1164         "{ 2 4 }\n{ 1 3 5 }"
1165     }
1166 } ;
1167
1168 HELP: virtual-seq
1169 { $values
1170      { "seq" sequence }
1171      { "seq'" sequence } }
1172 { $description "Part of the virtual sequence protocol, this word is used to return an underlying array from which to look up a value at an index given by " { $link virtual@ } "." } ;
1173
1174 HELP: virtual@
1175 { $values
1176      { "n" integer } { "seq" sequence }
1177      { "n'" integer } { "seq'" sequence } }
1178 { $description "Part of the sequence protocol, this word translates the input index " { $snippet "n" } " into an index into the underlying storage returned by " { $link virtual-seq } "." } ;
1179
1180 HELP: 2map-reduce
1181 { $values
1182      { "seq1" sequence } { "seq2" sequence } { "map-quot" quotation } { "reduce-quot" quotation }
1183      { "result" object } }
1184 { $description "Unclips the first element of each sequence and calls " { $snippet "map-quot" } " on both objects. The result of this calculation is passed, along with the rest of both sequences, to " { $link 2reduce } ", with the computed object as the identity." }
1185 { $examples { $example "USING: sequences prettyprint math ;"
1186     "{ 10 30 50 } { 200 400 600 } [ + ] [ + ] 2map-reduce ."
1187     "1290"
1188 } } ;
1189
1190 HELP: 2pusher
1191 { $values
1192      { "quot" quotation }
1193      { "quot" quotation } { "accum1" vector } { "accum2" vector } }
1194 { $description "Creates two new vectors to accumultate values based on a predicate. The first vector accumulates values for which the predicate yields true; the second for false." } ;
1195
1196 HELP: 2reverse-each
1197 { $values
1198      { "seq1" sequence } { "seq2" sequence } { "quot" quotation } }
1199 { $description "Reverse the sequences using the " { $link <reversed> } " word and calls " { $link 2each } " on the reversed sequences." }
1200 { $examples { $example "USING: sequences math prettyprint ;"
1201     "{ 10 20 30 } { 1 2 3 } [ + . ] 2reverse-each"
1202     "33\n22\n11"
1203 } } ;
1204
1205 HELP: 2unclip-slice
1206 { $values
1207      { "seq1" sequence } { "seq2" sequence }
1208      { "rest-slice1" sequence } { "rest-slice2" sequence } { "first1" object } { "first2" object } }
1209 { $description "Unclips the first element of each sequence and leaves two slice elements and the two unclipped objects on the stack." }
1210 { $examples { $example "USING: sequences prettyprint kernel arrays ;"
1211     "{ 1 2 } { 3 4 } 2unclip-slice 4array [ . ] each"
1212     "T{ slice { from 1 } { to 2 } { seq { 1 2 } } }\nT{ slice { from 1 } { to 2 } { seq { 3 4 } } }\n1\n3"
1213 } } ;
1214
1215 HELP: accumulator
1216 { $values
1217      { "quot" quotation }
1218      { "quot'" quotation } { "vec" vector } }
1219 { $description "Creates a new quotation that pushes its result to a vector and outputs that vector on the stack." }
1220 { $examples { $example "USING: sequences prettyprint kernel math ;"
1221     "{ 1 2 } [ 30 + ] accumulator [ each ] dip ."
1222     "V{ 31 32 }"
1223 } } ;
1224
1225 HELP: binary-reduce
1226 { $values
1227      { "seq" sequence } { "start" integer } { "quot" quotation }
1228      { "value" object } }
1229 { $description "Like " { $link reduce } ", but splits the sequence in half recursively until each sequence is small enough, and calls the quotation on these smaller sequences. If the quotation computes values that depend on the size of their input, such as bignum arithmetic, then this algorithm can be more efficient than using " { $link reduce } "." }
1230 { $examples "Computing factorial:"
1231     { $example "USING: prettyprint sequences math ;"
1232     "40 rest-slice 1 [ * ] binary-reduce ."
1233     "20397882081197443358640281739902897356800000000" }
1234 } ;
1235
1236 HELP: follow
1237 { $values
1238      { "obj" object } { "quot" quotation }
1239      { "seq" sequence } }
1240 { $description "Outputs a sequence containing the input object and all of the objects generated by successively feeding the result of the quotation called on the input object to the quotation recursuively. Objects yielded by the quotation are added to the output sequence until the quotation yields " { $link f } ", at which point the recursion terminates." }
1241 { $examples "Get random numbers until zero is reached:"
1242     { $unchecked-example
1243     "USING: random sequences prettyprint math ;"
1244     "100 [ random [ f ] when-zero ] follow ."
1245     "{ 100 86 34 32 24 11 7 2 }"
1246 } } ;
1247
1248 HELP: halves
1249 { $values
1250      { "seq" sequence }
1251      { "first-slice" slice } { "second-slice" slice } }
1252 { $description "Splits a sequence into two slices at the midpoint. If the sequence has an odd number of elements, the extra element is returned in the second slice." }
1253 { $examples { $example "USING: arrays sequences prettyprint kernel ;"
1254     "{ 1 2 3 4 5 } halves [ >array . ] bi@"
1255     "{ 1 2 }\n{ 3 4 5 }"
1256 } } ;
1257
1258 HELP: indices
1259 { $values
1260      { "obj" object } { "seq" sequence }
1261      { "indices" sequence } }
1262 { $description "Compares the input object to every element in the sequence and returns a vector containing the index of every position where the element was found." }
1263 { $examples { $example "USING: sequences prettyprint ;"
1264     "2 { 2 4 2 6 2 8 2 10 } indices ."
1265     "V{ 0 2 4 6 }"
1266 } } ;
1267
1268 HELP: insert-nth
1269 { $values
1270      { "elt" object } { "n" integer } { "seq" sequence }
1271      { "seq'" sequence } }
1272 { $description "Creates a new sequence where the " { $snippet "n" } "th index is set to the input object." }
1273 { $examples { $example "USING: prettyprint sequences ;"
1274     "40 3 { 10 20 30 50 } insert-nth ."
1275     "{ 10 20 30 40 50 }"
1276 } } ;
1277
1278 HELP: map-reduce
1279 { $values
1280      { "seq" sequence } { "map-quot" quotation } { "reduce-quot" quotation }
1281      { "result" object } }
1282 { $description "Unclips the first element of the sequence, calls " { $snippet "map-quot" } " on that element, and proceeds like a " { $link reduce } ", where the calculated element is the identity element and the rest of the sequence is the sequence to reduce." }
1283 { $examples { $example "USING: sequences prettyprint math ;"
1284     "{ 1 3 5 } [ sq ] [ + ] map-reduce ."
1285     "35"
1286 } } ;
1287
1288 HELP: new-like
1289 { $values
1290      { "len" integer } { "exemplar" "an exemplar sequence" } { "quot" quotation }
1291      { "seq" sequence } }
1292 { $description "Creates a new sequence of length " { $snippet "len" } " and calls the quotation with this sequence on the stack. The output of the quotation and the original exemplar are then passed to " { $link like } " so that the output sequence is the exemplar's type." } ;
1293
1294 HELP: push-either
1295 { $values
1296      { "elt" object } { "quot" quotation } { "accum1" vector } { "accum2" vector } }
1297 { $description "Pushes the input object onto one of the accumualators; the first if the quotation yields true, the second if false." } ;
1298
1299 HELP: sequence-hashcode
1300 { $values
1301      { "n" integer } { "seq" sequence }
1302      { "x" integer } }
1303 { $description "Iterates over a sequence, computes a hashcode with " { $link hashcode* } " for each element, and combines them using " { $link sequence-hashcode-step } "." } ;
1304
1305 HELP: sequence-hashcode-step
1306 { $values
1307      { "oldhash" integer } { "newpart" integer }
1308      { "newhash" integer } }
1309 { $description "An implementation word that computes a running hashcode of a sequence using some bit-twiddling. The resulting hashcode is always a fixnum." } ;
1310
1311 HELP: short
1312 { $values
1313      { "seq" sequence } { "n" integer }
1314      { "seq" sequence } { "n'" integer } }
1315 { $description "Returns the input sequence and its length or " { $snippet "n" } ", whichever is less." }
1316 { $examples { $example "USING: sequences kernel prettyprint ;"
1317     "\"abcd\" 3 short [ . ] bi@"
1318     "\"abcd\"\n3"
1319 } } ;
1320
1321 HELP: shorten
1322 { $values
1323      { "n" integer } { "seq" sequence } }
1324 { $description "Shortens a " { $link "growable" } " sequence to by " { $snippet "n" } " elements long." }
1325 { $examples { $example "USING: sequences prettyprint kernel ;"
1326     "V{ 1 2 3 4 5 } 3 over shorten ."
1327     "V{ 1 2 3 }"
1328 } } ;
1329
1330 HELP: iota
1331 { $values { "n" integer } { "iota" iota } }
1332 { $description "Creates an immutable virtual sequence containing the integers from 0 to " { $snippet "n-1" } "." }
1333 { $examples
1334   { $example
1335     "USING: math sequences prettyprint ;"
1336     "3 iota [ sq ] map ."
1337     "{ 0 1 4 }"
1338   }
1339 } ;
1340
1341 HELP: assert-sequence=
1342 { $values
1343     { "a" sequence } { "b" sequence }
1344 }
1345 { $description "Throws an error if all the elements of two sequences, taken pairwise, are not equal." }
1346 { $notes "The sequences need not be of the same type." }
1347 { $examples
1348   { $example
1349     "USING: prettyprint sequences ;"
1350     "{ 1 2 3 } V{ 1 2 3 } assert-sequence="
1351     ""
1352   }
1353 } ;
1354
1355 ARTICLE: "sequences-unsafe" "Unsafe sequence operations"
1356 "The " { $link nth-unsafe } " and " { $link set-nth-unsafe } " sequence protocol bypasses bounds checks for increased performance."
1357 $nl
1358 "These words assume the sequence index given is within bounds; if it is not, memory corruption can occur. Great care must be exercised when using these words. First, make sure the code in question is actually a bottleneck; next, try improving the algorithm first. If all else fails, then the unsafe sequence words can be used."
1359 $nl
1360 "There is a very important invariant these word must preserve: if at some point in time, the length of a sequence was " { $snippet "n" } ", then any future lookups of elements with indices below " { $snippet "n" } " must not crash the VM, even if the sequence length is now less than " { $snippet "n" } ". For example, vectors preserve this invariant by never shrinking the underlying storage, only growing it as necessary."
1361 $nl
1362 "The justification for this is that the VM should not crash if a resizable sequence is resized during the execution of an iteration combinator."
1363 $nl
1364 "Indeed, iteration combinators are the primary use-case for these words; if the iteration index is already guarded by a loop test which ensures it is within bounds, then additional bounds checks are redundant. For example, see the implementation of " { $link each } "." ;
1365
1366 ARTICLE: "sequence-protocol" "Sequence protocol"
1367 "All sequences must be instances of a mixin class:"
1368 { $subsections sequence sequence? }
1369 "All sequences must know their length:"
1370 { $subsections length }
1371 "At least one of the following two generic words must have a method for accessing elements; the " { $link sequence } " mixin has default definitions which are mutually recursive:"
1372 { $subsections nth nth-unsafe }
1373 "Note that sequences are always indexed starting from zero."
1374 $nl
1375 "At least one of the following two generic words must have a method for storing elements; the " { $link sequence } " mixin has default definitions which are mutually recursive:"
1376 { $subsections set-nth set-nth-unsafe }
1377 "If your sequence is immutable, then you must implement either " { $link set-nth } " or " { $link set-nth-unsafe } " to simply call " { $link immutable } " to signal an error."
1378 $nl
1379 "The following two generic words are optional, as not all sequences are resizable:"
1380 { $subsections set-length lengthen }
1381 "An optional generic word for creating sequences of the same class as a given sequence:"
1382 { $subsections like }
1383 "Optional generic words for optimization purposes:"
1384 { $subsections new-sequence new-resizable }
1385 { $see-also "sequences-unsafe" } ;
1386
1387 ARTICLE: "virtual-sequences-protocol" "Virtual sequence protocol"
1388 "Virtual sequences must know their length:"
1389 { $subsections length }
1390 "The underlying sequence to look up a value in:"
1391 { $subsections virtual-seq }
1392 "The index of the value in the underlying sequence:"
1393 { $subsections virtual@ } ;
1394
1395 ARTICLE: "virtual-sequences" "Virtual sequences"
1396 "A virtual sequence is an implementation of the " { $link "sequence-protocol" } " which does not store its own elements, and instead computes them, either from scratch or by retrieving them from another sequence."
1397 $nl
1398 "Implementations include the following:"
1399 { $subsections reversed slice iota }
1400 "Virtual sequences can be implemented with the " { $link "virtual-sequences-protocol" } ", by translating an index in the virtual sequence into an index in another sequence." ;
1401
1402 ARTICLE: "sequences-integers" "Counted loops"
1403 "Integers support the sequence protocol in a trivial fashion; a non-negative integer presents its non-negative predecessors as elements. For example, the integer 3, when viewed as a sequence, contains the elements 0, 1, and 2. This is very useful for performing counted loops."
1404 $nl
1405 "For example, the " { $link each } " combinator, given an integer, simply calls a quotation that number of times, pushing a counter on each iteration that ranges from 0 up to that integer:"
1406 { $example "3 [ . ] each" "0\n1\n2" }
1407 "A common idiom is to iterate over a sequence, while also maintaining a loop counter. This can be done using " { $link each-index } ", " { $link map-index } " and " { $link reduce-index } "."
1408 $nl
1409 "Combinators that produce new sequences, such as " { $link map } ", will output an array if the input is an integer."
1410 $nl
1411 "More elaborate counted loops can be performed with " { $link "math.ranges" } "." ;
1412
1413 ARTICLE: "sequences-if" "Control flow with sequences"
1414 "To reduce the boilerplate of checking if a sequence is empty, several combinators are provided."
1415 $nl
1416 "Checking if a sequence is empty:"
1417 { $subsections if-empty when-empty unless-empty } ;
1418
1419 ARTICLE: "sequences-access" "Accessing sequence elements"
1420 "Element access by index, without raising exceptions:"
1421 { $subsections ?nth }
1422 "Concise way of extracting one of the first four elements:"
1423 { $subsections first second third fourth }
1424 "Extracting the last element:"
1425 { $subsections last }
1426 "Unpacking sequences:"
1427 { $subsections first2 first3 first4 }
1428 { $see-also nth } ;
1429
1430 ARTICLE: "sequences-add-remove" "Adding and removing sequence elements"
1431 "Adding elements:"
1432 { $subsections prefix suffix insert-nth }
1433 "Removing elements:"
1434 { $subsections remove remove-eq remove-nth } ;
1435
1436 ARTICLE: "sequences-reshape" "Reshaping sequences"
1437 "A " { $emphasis "repetition" } " is a virtual sequence consisting of a single element repeated multiple times:"
1438 { $subsections repetition <repetition> }
1439 "Reversing a sequence:"
1440 { $subsections reverse }
1441 "A " { $emphasis "reversal" } " presents a reversed view of an underlying sequence:"
1442 { $subsections reversed <reversed> }
1443 "Transposing a matrix:"
1444 { $subsections flip } ;
1445
1446 ARTICLE: "sequences-appending" "Appending sequences"
1447 "Basic append operations:"
1448 { $subsections
1449     append
1450     append-as
1451     prepend
1452     3append
1453     3append-as
1454     surround
1455     glue
1456 }
1457 "Collapse a sequence unto itself:"
1458 { $subsections concat join }
1459 "A pair of words useful for aligning strings:"
1460 { $subsections pad-head pad-tail } ;
1461
1462 ARTICLE: "sequences-slices" "Subsequences and slices"
1463 "There are two ways to extract a subrange of elements from a sequence. The first approach creates a new sequence of the same type as the input, which does not share storage with the underlying sequence. This takes time proportional to the number of elements being extracted. The second approach creates a " { $emphasis "slice" } ", which is a virtual sequence (see " { $link "virtual-sequences" } ") sharing storage with the original sequence. Slices are constructed in constant time."
1464 $nl
1465 "Some general guidelines for choosing between the two approaches:"
1466 { $list
1467   "If you are using mutable state, the choice has to be made one way or another because of semantics; mutating a slice will change the underlying sequence."
1468   { "Using a slice can improve algorithmic complexity. For example, if each iteration of a loop decomposes a sequence using " { $link first } " and " { $link rest } ", then the loop will run in quadratic time, relative to the length of the sequence. Using " { $link rest-slice } " changes the loop to run in linear time, since " { $link rest-slice } " does not copy any elements. Taking a slice of a slice will “collapse” the slice so to avoid the double indirection, so it is safe to use slices in recursive code." }
1469   "Accessing elements from a concrete sequence (such as a string or an array) is often faster than accessing elements from a slice, because slice access entails additional indirection. However, in some cases, if the slice is immediately consumed by an iteration combinator, the compiler can eliminate the slice allocation and indirect altogether."
1470   "If the slice outlives the original sequence, the original sequence will still remain in memory, since the slice will reference it. This can increase memory consumption unnecessarily."
1471 }
1472 { $heading "Subsequence operations" }
1473 "Extracting a subsequence:"
1474 { $subsections
1475     subseq
1476     head
1477     tail
1478     head*
1479     tail*
1480 }
1481 "Removing the first or last element:"
1482 { $subsections rest but-last }
1483 "Taking a sequence apart into a head and a tail:"
1484 { $subsections
1485     unclip
1486     unclip-last
1487     cut
1488     cut*
1489 }
1490 { $heading "Slice operations" }
1491 "The slice data type:"
1492 { $subsections slice slice? }
1493 "Extracting a slice:"
1494 { $subsections
1495     <slice>
1496     head-slice
1497     tail-slice
1498     head-slice*
1499     tail-slice*
1500 }
1501 "Removing the first or last element:"
1502 { $subsections rest-slice but-last-slice }
1503 "Taking a sequence apart into a head and a tail:"
1504 { $subsections unclip-slice unclip-last-slice cut-slice }
1505 "A utility for words which use slices as iterators:"
1506 { $subsections <flat-slice> }
1507 "Replacing slices with new elements:"
1508 { $subsections replace-slice } ;
1509
1510 ARTICLE: "sequences-combinators" "Sequence combinators"
1511 "Iteration:"
1512 { $subsections
1513     each
1514     each-index
1515     reduce
1516     interleave
1517     replicate
1518     replicate-as
1519 }
1520 "Mapping:"
1521 { $subsections
1522     map
1523     map-as
1524     map-index
1525     map-reduce
1526     accumulate
1527     accumulate-as
1528     produce
1529     produce-as
1530 }
1531 "Filtering:"
1532 { $subsections
1533     filter
1534     filter-as
1535     partition
1536 }
1537 "Testing if a sequence contains elements satisfying a predicate:"
1538 { $subsections
1539     any?
1540     all?
1541 }
1542 { $heading "Related Articles" }
1543 { $subsections
1544     "sequence-2combinators"
1545     "sequence-3combinators"
1546 } ;
1547
1548 ARTICLE: "sequence-2combinators" "Pair-wise sequence combinators"
1549 "There is a set of combinators which traverse two sequences pairwise. If one sequence is shorter than the other, then only the prefix having the length of the minimum of the two is examined."
1550 { $subsections
1551     2each
1552     2reduce
1553     2map
1554     2map-as
1555     2map-reduce
1556     2all?
1557 } ;
1558
1559 ARTICLE: "sequence-3combinators" "Triple-wise sequence combinators"
1560 "There is a set of combinators which traverse three sequences triple-wise. If one sequence is shorter than the others, then only the prefix having the length of the minimum of the three is examined."
1561 { $subsections 3each 3map 3map-as } ;
1562
1563 ARTICLE: "sequences-tests" "Testing sequences"
1564 "Testing for an empty sequence:"
1565 { $subsections empty? }
1566 "Testing indices:"
1567 { $subsections bounds-check? }
1568 "Testing if a sequence contains an object:"
1569 { $subsections member? member-eq? }
1570 "Testing if a sequence contains a subsequence:"
1571 { $subsections head? tail? subseq? } ;
1572
1573 ARTICLE: "sequences-search" "Searching sequences"
1574 "Finding the index of an element:"
1575 { $subsections
1576     index
1577     index-from
1578     last-index
1579     last-index-from
1580 }
1581 "Finding the start of a subsequence:"
1582 { $subsections start start* }
1583 "Finding the index of an element satisfying a predicate:"
1584 { $subsections
1585     find
1586     find-from
1587     find-last
1588     find-last-from
1589     map-find
1590 } ;
1591
1592 ARTICLE: "sequences-trimming" "Trimming sequences"
1593 "Trimming words:"
1594 { $subsections trim trim-head trim-tail }
1595 "Potentially more efficient trim:"
1596 { $subsections trim-slice trim-head-slice trim-tail-slice } ;
1597
1598 ARTICLE: "sequences-destructive-discussion" "When to use destructive operations"
1599 "Constructive (non-destructive) operations should be preferred where possible because code without side-effects is usually more re-usable and easier to reason about. There are two main reasons to use destructive operations:"
1600 { $list
1601     "For the side-effect. Some code is simpler to express with destructive operations; constructive operations return new objects, and sometimes ``threading'' the objects through the program manually complicates stack shuffling."
1602     { "As an optimization. Some code can be written to use constructive operations, however would suffer from worse performance. An example is a loop which adds an element to a sequence on each iteration; one could use either " { $link suffix } " or " { $link push } ", however the former copies the entire sequence first, which would cause the loop to run in quadratic time." }
1603 }
1604 "The second reason is much weaker than the first one. In particular, many combinators (see " { $link map } ", " { $link produce } " and " { $link "namespaces-make" } ") as well as more advanced data structures (such as " { $vocab-link "persistent.vectors" } ") alleviate the need for explicit use of side effects." ;
1605
1606 ARTICLE: "sequences-destructive" "Destructive operations"
1607 "Changing elements:"
1608 { $subsections map! change-nth }
1609 "Deleting elements:"
1610 { $subsections
1611     remove!
1612     remove-eq!
1613     remove-nth!
1614     delete-slice
1615     delete-all
1616     filter!
1617 }
1618 "Other destructive words:"
1619 { $subsections
1620     reverse!
1621     push-all
1622     move
1623     exchange
1624     copy
1625 }
1626 "Many operations have constructive and destructive variants:"
1627 { $table
1628     { "Constructive" "Destructive" }
1629     { { $link suffix } { $link suffix! } }
1630     { { $link but-last } { $link pop* } }
1631     { { $link unclip-last } { $link pop } }
1632     { { $link remove } { $link remove! } }
1633     { { $link remove-eq } { $link remove-eq! } }
1634     { { $link remove-nth } { $link remove-nth! } }
1635     { { $link reverse } { $link reverse! } }
1636     { { $link append } { $link append! } }
1637     { { $link map } { $link map! } }
1638     { { $link filter } { $link filter! } }
1639 }
1640 { $heading "Related Articles" }
1641 { $subsections
1642     "sequences-destructive-discussion"
1643     "sequences-stacks"
1644 }
1645 { $see-also set-nth push pop } ;
1646
1647 ARTICLE: "sequences-stacks" "Treating sequences as stacks"
1648 "The classical stack operations, modifying a sequence in place:"
1649 { $subsections push pop pop* }
1650 { $see-also empty? } ;
1651
1652 ARTICLE: "sequences-comparing" "Comparing sequences"
1653 "Element equality testing:"
1654 { $subsections
1655     sequence=
1656     mismatch
1657     drop-prefix
1658     assert-sequence=
1659 }
1660 "The " { $link <=> } " generic word performs lexicographic comparison when applied to sequences." ;
1661
1662 ARTICLE: "sequences-f" "The f object as a sequence"
1663 "The " { $link f } " object supports the sequence protocol in a trivial way. It responds with a length of zero and throws an out of bounds error when an attempt is made to access elements." ;
1664
1665 ARTICLE: "sequences" "Sequence operations"
1666 "A " { $emphasis "sequence" } " is a finite, linearly-ordered collection of elements. Words for working with sequences are in the " { $vocab-link "sequences" } " vocabulary."
1667 $nl
1668 "Sequences implement a protocol:"
1669 { $subsections
1670     "sequence-protocol"
1671     "sequences-f"
1672 }
1673 "Sequence utility words can operate on any object whose class implements the sequence protocol. Most implementations are backed by storage. Some implementations obtain their elements from an underlying sequence, or compute them on the fly. These are known as " { $link "virtual-sequences" } "."
1674 { $subsections
1675     "sequences-access"
1676     "sequences-combinators"
1677     "sequences-add-remove"
1678     "sequences-appending"
1679     "sequences-slices"
1680     "sequences-reshape"
1681     "sequences-tests"
1682     "sequences-search"
1683     "sequences-comparing"
1684     "sequences-split"
1685     "grouping"
1686     "sequences-destructive"
1687     "sequences-stacks"
1688     "sequences-sorting"
1689     "binary-search"
1690     "sets"
1691     "sequences-trimming"
1692     "sequences.deep"
1693 }
1694 "Using sequences for looping:"
1695 { $subsections
1696     "sequences-integers"
1697     "math.ranges"
1698 }
1699 "Using sequences for control flow:"
1700 { $subsections "sequences-if" }
1701 "For inner loops:"
1702 { $subsections "sequences-unsafe" } ;
1703
1704 ABOUT: "sequences"