extra/sequences/extras/extras-docs.factor

   1 USING: arrays help.markup help.syntax kernel math multiline
   2 quotations sequences vectors assocs strings ;
   3 IN: sequences.extras
   4
   5 HELP: pad-center
   6 { $values { "seq" sequence } { "n" "a non-negative integer" } { "elt" object } { "padded" "a new sequence" } }
   7 { $description "Outputs a new sequence consisting of " { $snippet "seq" } " padded on the left and right with enough repetitions of " { $snippet "elt" } " to have the result be of length " { $snippet "n" } "." }
   8 { $examples { $example "USING: io sequences sequences.extras ;" "{ \"ab\" \"quux\" } [ 5 CHAR: - pad-center print ] each" "-ab--\nquux-" } } ;
   9
  10 HELP: ?supremum
  11 { $values
  12     { "seq/f" { $maybe sequence } }
  13     { "elt/f" { $maybe object } }
  14 }
  15 { $description "Outputs the greatest element of " { $snippet "seq" } ", ignoring any " { $link POSTPONE: f } " elements in it. If " { $snippet "seq" } " is empty or " { $link POSTPONE: f } ", returns " { $link POSTPONE: f } "." }
  16 { $examples
  17     { $example "USING: prettyprint sequences.extras ;"
  18     "{ 1 f 3 2 } ?supremum ."
  19     "3" }
  20 } ;
  21
  22 HELP: ?infimum
  23 { $values
  24     { "seq/f" { $maybe sequence } }
  25     { "elt/f" { $maybe object } }
  26 }
  27 { $description "Outputs the least element of " { $snippet "seq" } ", ignoring any " { $link POSTPONE: f } " elements in it. If " { $snippet "seq" } " is empty or " { $link POSTPONE: f } ", returns " { $link POSTPONE: f } "." }
  28 { $examples
  29     { $example "USING: prettyprint sequences.extras ;"
  30     "{ 1 f 3 2 } ?infimum ."
  31     "1" }
  32 } ;
  33
  34 { ?supremum ?infimum } related-words
  35
  36 HELP: 2count
  37 { $values
  38     { "seq1" sequence }
  39     { "seq2" sequence }
  40     { "quot" { $quotation ( ... elt1 elt2 -- ... ? ) } }
  41     { "n" integer } }
  42 { $description "Efficiently counts how many pairwise elements of " { $snippet "seq1" } " and " { $snippet "seq2" } " that the predicate quotation matches." }
  43 { $examples
  44     { $example "USING: kernel prettyprint sequences.extras ;" "{ 1 2 3 } { 3 2 1 } [ = ] 2count ." "1" } }
  45 { $see-also count } ;
  46
  47 HELP: 2each-index
  48 { $values
  49     { "seq1" sequence }
  50     { "seq2" sequence }
  51     { "quot" { $quotation ( ... elt1 elt2 index -- ... ) } } }
  52 { $description "Applies " { $snippet "quot" } " to each pair of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ", providing the index of the elements at the top of the stack." }
  53 { $see-also 2each each-index } ;
  54
  55 HELP: 2map!
  56 { $values
  57     { "seq1" sequence }
  58     { "seq2" sequence }
  59     { "quot" { $quotation ( ... elt1 elt2 -- ... newelt ) } } }
  60 { $description "Applies the quotation to each pair of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ", yielding a new element, and storing it back into " { $snippet "seq1" } ". Returns " { $snippet "seq1" } "." }
  61 { $see-also 2map map! } ;
  62
  63 HELP: 2map-index
  64 { $values
  65     { "seq1" sequence }
  66     { "seq2" sequence }
  67     { "quot" { $quotation ( ... elt1 elt2 index -- ... newelt ) } }
  68     { "newseq" sequence } }
  69 { $description "Calls the quotation with each pair of elements of the two sequences and their index on the stack, with the index on the top of the stack. Collects the outputs of the quotation and outputs them into a new sequence of the same type as the first sequence." }
  70 { $see-also 2map map-index } ;
  71
  72 HELP: percent-of
  73 { $values
  74     { "seq" sequence }
  75     { "quot" { $quotation ( ... elt -- ... ? ) } }
  76     { "%" rational } }
  77 { $description "Outputs the fraction of elements in the sequence for which the predicate quotation matches." }
  78 { $examples { $example "USING: math ranges prettyprint sequences.extras ;" "100 [1..b] [ even? ] percent-of ." "1/2" } } ;
  79
  80 HELP: collapse
  81 { $values
  82     { "seq" sequence }
  83     { "quot" { $quotation ( ... elt -- ... ? ) } }
  84     { "elt" object }
  85     { "seq'" sequence } }
  86 { $description "Generate a new sequence where all runs of elements for which the predicate returns true are replaced by a single instance of " { $snippet "elt" } "." }
  87 { $see-also compact }
  88 { $examples
  89     "Collapse multiple spaces in a string down to a single space"
  90     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" collapse ." "\" Hello, crazy world \"" } } ;
  91
  92 HELP: compact
  93 { $values
  94     { "seq" sequence }
  95     { "quot" { $quotation ( ... elt -- ... ? ) } }
  96     { "elt" object }
  97     { "seq'" sequence } }
  98 { $description "Generate a new sequence where all runs of elements for which the predicate returns true are replaced by a single instance of " { $snippet "elt" } ". Runs at the beginning or end of the sequence for which the predicate returns true are removed." }
  99 { $see-also collapse }
 100 { $examples
 101     "Collapse multiple spaces in a string down to a single space"
 102     { $example "USING: kernel prettyprint sequences.extras ;" "\"   Hello,    crazy    world   \" [ CHAR: \\s = ] \" \" compact ." "\"Hello, crazy world\"" } } ;
 103
 104 HELP: <evens>
 105 { $values { "seq" sequence } { "evens" evens } }
 106 { $description "Create a virtual sequence whose elements consist of the even-indexed elements from the original sequence." }
 107 { $notes "Because sequences are zero-indexed, this collection includes the first, third, fifth, etc. elements of the actual sequence which can be counterintuitive." }
 108 { $see-also <odds> } ;
 109
 110 HELP: find-all
 111 { $values
 112     { "seq" sequence }
 113     { "quot" { $quotation ( ... elt -- ... ? ) } }
 114     { "elts" "the indices of the matching elements" } }
 115 { $description "Similar to " { $link find } ", but finds all of the indices and elements that match the provided quotation, not just the first." }
 116 { $notes "The result is provided as an array of arrays, whose first value is the index and whose second value is the element." } ;
 117
 118 HELP: first=
 119 { $values
 120     { "seq" sequence }
 121     { "elt" object }
 122     { "?" boolean } }
 123 { $description "Checks whether the first element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 124
 125 HELP: first?
 126 { $values
 127     { "seq" sequence }
 128     { "quot" { $quotation ( ... elt -- ... ? ) } }
 129     { "?" boolean } }
 130 { $description "Tests whether the first element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 131
 132 HELP: fourth=
 133 { $values
 134     { "seq" sequence }
 135     { "elt" object }
 136     { "?" boolean } }
 137 { $description "Checks whether the fourth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 138
 139 HELP: fourth?
 140 { $values
 141     { "seq" sequence }
 142     { "quot" { $quotation ( ... elt -- ... ? ) } }
 143     { "?" boolean } }
 144 { $description "Tests whether the fourth element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 145
 146 HELP: <odds>
 147 { $values { "seq" sequence } { "odds" odds } }
 148 { $description "Create a virtual sequence whose elements consist of the odd-indexed elements from the original sequence." }
 149 { $notes "Because sequences are zero-indexed, this collection includes the second, fourth, sixth, etc. elements of the actual sequence which can be counterintuitive." }
 150 { $see-also <evens> } ;
 151
 152 HELP: >resizable
 153 { $values { "seq" sequence } { "accum" sequence } }
 154 { $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ;
 155
 156 HELP: second=
 157 { $values
 158     { "seq" sequence }
 159     { "elt" object }
 160     { "?" boolean } }
 161 { $description "Checks whether the second element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 162
 163 HELP: second?
 164 { $values
 165     { "seq" sequence }
 166     { "quot" { $quotation ( ... elt -- ... ? ) } }
 167     { "?" boolean } }
 168 { $description "Tests whether the second element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 169
 170 HELP: subseq*
 171 { $values
 172     { "from" integer } { "to" integer } { "seq" sequence } { "subseq" sequence } }
 173 { $description "Outputs a new sequence using positions relative to one or both ends of the sequence. Positive values describes offsets relative to the start of the sequence, negative values relative to the end. Values of " { $link f } " for " { $snippet "from" } " indicate the beginning of the sequence, while an " { $link f } " for " { $snippet "to" } " indicates the end of the sequence." }
 174 { $notes "Both " { $snippet "from" } " and " { $snippet "to" } " can be safely set to values outside the length of the sequence. Also, " { $snippet "from" } " can safely reference a smaller or greater index position than " { $snippet "to" } "." }
 175 { $examples
 176     "Using a negative relative index:"
 177     { $example "USING: prettyprint sequences.extras ; 2 -1 \"abcdefg\" subseq* ."
 178                "\"cdef\""
 179     }
 180     "Using optional indices:"
 181     { $example "USING: prettyprint sequences.extras ; f -4 \"abcdefg\" subseq* ."
 182                "\"abc\""
 183     }
 184     "Using larger-than-necessary indices:"
 185     { $example "USING: prettyprint sequences.extras ; 0 10 \"abcdefg\" subseq* ."
 186                "\"abcdefg\""
 187     }
 188     "Trimming from either end of the sequence."
 189     { $example "USING: prettyprint sequences.extras ; 1 -1 \"abcdefg\" subseq* ."
 190                "\"bcdef\""
 191     }
 192 } ;
 193
 194 HELP: third=
 195 { $values
 196     { "seq" sequence }
 197     { "elt" object }
 198     { "?" boolean } }
 199 { $description "Checks whether the third element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 200
 201 HELP: third?
 202 { $values
 203     { "seq" sequence }
 204     { "quot" { $quotation ( ... elt -- ... ? ) } }
 205     { "?" boolean } }
 206 { $description "Tests whether the third element of " { $snippet "seq" } " satisfies the provided predicate." } ;
 207
 208 HELP: unsurround
 209 { $values
 210     { "newseq" sequence }
 211     { "seq2" sequence }
 212     { "seq3" sequence }
 213     { "seq1" sequence } }
 214 { $description "Reverses the result of a " { $link surround } " call, stripping off the prefix " { $snippet "seq2" } " and suffix " { $snippet "seq3" } " to restore the original sequence " { $snippet "seq" } "." }
 215 { $see-also surround } ;
 216
 217 HELP: start-all
 218 { $values
 219     { "seq" sequence } { "subseq" sequence } { "indices" sequence } }
 220 { $description "Outputs the starting indices of the non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 221 { $examples
 222     { $example "USING: prettyprint sequences.extras ;"
 223                "\"ABABA\" \"ABA\" start-all ."
 224                "{ 0 }"
 225     }
 226     { $example "USING: prettyprint sequences.extras ;"
 227                "\"ABAABA\" \"ABA\" start-all ."
 228       "{ 0 3 }"
 229     }
 230 } ;
 231
 232 HELP: start-all*
 233 { $values
 234     { "seq" sequence } { "subseq" sequence } { "indices" sequence } }
 235 { $description "Outputs the starting indices of the possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 236 { $examples
 237     { $example "USING: prettyprint sequences.extras ;"
 238                "\"ABABA\" \"ABA\" start-all* ."
 239                "{ 0 2 }"
 240     } } ;
 241
 242 HELP: arg-max
 243 { $values { "seq" sequence } { "n" integer } }
 244 { $description "Outputs the index of the element with the largest value in " { $snippet "seq" } "." } ;
 245
 246 HELP: arg-min
 247 { $values { "seq" sequence } { "n" integer } }
 248 { $description "Outputs the index of the element with the smallest value in " { $snippet "seq" } "." } ;
 249
 250 { arg-max arg-min } related-words
 251
 252 HELP: count-subseq
 253 { $values
 254     { "seq" sequence } { "subseq" sequence } { "n" integer } }
 255 { $description "Outputs the number of non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 256 { $examples
 257     { $example "USING: prettyprint sequences.extras ;"
 258                "\"ABABA\" \"ABA\" count-subseq ."
 259                "1"
 260     } } ;
 261
 262
 263 HELP: count-subseq*
 264 { $values
 265     { "seq" sequence } { "subseq" sequence } { "n" integer } }
 266 { $description "Outputs the number of possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
 267 { $examples
 268     { $example "USING: prettyprint sequences.extras ;"
 269                "\"ABABA\" \"ABA\" count-subseq* ."
 270                "2"
 271     } } ;
 272
 273 { start-all start-all* count-subseq count-subseq* } related-words
 274
 275 HELP: loop>array
 276 { $values
 277     { "quot" quotation }
 278     { "array" array }
 279 }
 280 { $description "Call the " { $snippet "quot" } ", which should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 281 { $examples
 282     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 283     "io.streams.byte-array io ;"
 284         "B{ 10 20 30 } binary ["
 285         "   [ read1 ] loop>array"
 286         "] with-byte-reader ."
 287         "{ 10 20 30 }"
 288     }
 289 } ;
 290
 291 HELP: loop>array*
 292 { $values
 293     { "quot" quotation }
 294     { "array" array }
 295 }
 296 { $description "Call the " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do collect the last object." }
 297 { $examples
 298     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 299                "random random.mersenne-twister kernel math ;"
 300     "123 <mersenne-twister> ["
 301     "   ["
 302     "      10 random dup 5 >"
 303     "   ] loop>array* ."
 304     "] with-random"
 305     "{ 6 7 2 }"
 306     }
 307 } ;
 308
 309 HELP: loop>array**
 310 { $values
 311     { "quot" quotation }
 312     { "array" array }
 313 }
 314 { $description "Call the " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do not collect the last object." }
 315 { $examples
 316     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 317                "random random.mersenne-twister kernel math ;"
 318     "123 <mersenne-twister> ["
 319     "   ["
 320     "      10 random dup 5 >"
 321     "   ] loop>array** ."
 322     "] with-random"
 323     "{ 6 7 }"
 324     }
 325 } ;
 326
 327
 328 HELP: loop>sequence
 329 { $values
 330     { "quot" quotation } { "exemplar" object }
 331     { "seq" sequence }
 332 }
 333 { $description "Call " { $snippet "quot" } ", which should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 334 { $examples
 335     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 336     "io.streams.byte-array io ;"
 337         "B{ 10 20 30 } binary ["
 338         "   [ read1 ] V{ } loop>sequence"
 339         "] with-byte-reader ."
 340         "V{ 10 20 30 }"
 341     }
 342 } ;
 343
 344 HELP: loop>sequence*
 345 { $values
 346     { "quot" quotation } { "exemplar" object }
 347     { "seq" sequence }
 348 }
 349 { $description "Call " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do collect the last object." }
 350 { $examples
 351     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 352                "random random.mersenne-twister kernel math ;"
 353     "! Get random numbers until one of them is greater than 5"
 354     "! but also output the last number"
 355     "123 <mersenne-twister> ["
 356     "   ["
 357     "      10 random dup 5 >"
 358     "   ] V{ } loop>sequence*"
 359     "] with-random ."
 360     "V{ 6 7 2 }"
 361     }
 362 } ;
 363
 364 HELP: loop>sequence**
 365 { $values
 366     { "quot" quotation } { "exemplar" object }
 367     { "seq" sequence }
 368 }
 369 { $description "Call " { $snippet "quot" } ", which should output an object and a " { $snippet "bool" } ", and collect the objects in " { $snippet "seq" } " of type " { $snippet "exemplar" } " until " { $snippet "quot" } " outputs " { $snippet "f" } ". Do not collect the last object." }
 370 { $examples
 371     { $example "USING: sequences.extras prettyprint io.encodings.binary"
 372                "random random.mersenne-twister kernel math ;"
 373     "! Get random numbers until one of them is greater than 5"
 374     "! but also output the last number"
 375     "123 <mersenne-twister> ["
 376     "   ["
 377     "      10 random dup 5 >"
 378     "   ] V{ } loop>sequence**"
 379     "] with-random ."
 380     "V{ 6 7 }"
 381     }
 382 } ;
 383
 384 {
 385     loop>array loop>array* loop>array**
 386     loop>sequence loop>sequence* loop>sequence**
 387     zero-loop>array zero-loop>sequence
 388 } related-words
 389
 390 HELP: zero-loop>array
 391 { $values
 392     { "quot" quotation }
 393     { "seq" sequence }
 394 }
 395 { $description "Call " { $snippet "quot" } ", which takes an integer starting from zero and incrementing on every loop, and should output an object, and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 396 { $examples
 397     "Example:"
 398     { $example "USING: sequences.extras prettyprint math.text.english math kernel ;"
 399         "[ dup 5 < [ number>text ] [ drop f ] if ] zero-loop>array ."
 400         [[ { "zero" "one" "two" "three" "four" }]]
 401     }
 402 } ;
 403
 404 HELP: zero-loop>sequence
 405 { $values
 406     { "quot" quotation } { "exemplar" object }
 407     { "seq" sequence }
 408 }
 409 { $description "Call the " { $snippet "quot" } ", which takes an integer starting from zero and incrementing on every loop, and should output an object or " { $snippet "f" } ", and collect the objects in " { $snippet "array" } " until " { $snippet "quot" } " outputs " { $snippet "f" } "." }
 410 { $examples
 411     "Example:"
 412     { $example "USING: sequences.extras prettyprint math.text.english math kernel ;"
 413         "[ dup 5 < [ number>text ] [ drop f ] if ] V{ } zero-loop>sequence ."
 414         [[ V{ "zero" "one" "two" "three" "four" }]]
 415     }
 416 } ;
 417
 418 HELP: find-pred
 419 { $values seq: sequence quot: quotation pred: quotation calc/f: object i/f: object elt/f: object }
 420 { $description A version of \ find that saves the calculation done by the first quotation and returns the calulation, element, and index if the calculation matches a predicate quotation. }
 421 { $examples
 422     [=[ USING: math kernel sequences.extras prettyprint ;
 423         { 4 5 6 } [ sq ] [ 20 > ] find-pred [ . ] tri@
 424         25\n5\n1
 425     ]=]
 426 } ;
 427
 428 HELP: (collect-with-previous)
 429 { $values
 430     { "quot" quotation } { "into" object }
 431     { "quot'" quotation }
 432 } ;
 433
 434 HELP: (each-integer-with-previous)
 435 { $values
 436     { "prev" object } { "i" integer } { "n" integer } { "quot" quotation }
 437 } ;
 438
 439 HELP: (start-all)
 440 { $values
 441     { "seq" sequence } { "subseq" object } { "increment" object }
 442     { "indices" object }
 443 } ;
 444
 445 HELP: 2map-into
 446 { $values
 447     { "seq1" sequence } { "seq2" sequence } { "quot" quotation } { "into" object }
 448 }
 449 { $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 "into" } "." } ;
 450
 451 HELP: 2map-sum
 452 { $values
 453     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 454     { "n" integer }
 455 }
 456 { $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" } ". The resulting sequence is summed." } ;
 457
 458 HELP: 2nested-each
 459 { $values
 460     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 461 }
 462 { $description "Applies quotation to all pairs of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ". Order is the same as a nested for loop." } ;
 463
 464 HELP: 2nested-map
 465 { $values
 466     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 467     { "seq" sequence }
 468 }
 469 { $description "Applies quotation to all pairs of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ", yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } ". Order is the same as a nested for loop." } ;
 470
 471 HELP: 3each-from
 472 { $values
 473     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation } { "i" integer }
 474 } ;
 475
 476 HELP: 3map-reduce
 477 { $values
 478     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "map-quot" object } { "reduce-quot" object }
 479     { "result" object }
 480 }
 481 { $description "Applies " { $snippet "map-quot" } " to each triple of elements in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } ". The resultant sequence is then reduced with " { $snippet "reduce-quot" } "." } ;
 482
 483 HELP: 3nested-each
 484 { $values
 485     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
 486 }
 487 { $description "Applies quotation to all triples of elements from " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } ". Order is the same as a nested for loop." } ;
 488
 489 HELP: 3nested-map
 490 { $values
 491     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
 492     { "seq" sequence }
 493 }
 494 { $description "Applies quotation to all triples of elements from " { $snippet "seq1" } ", " { $snippet "seq2" } " and " { $snippet "seq3" } " in turn, yielding new elements which are collected into a new sequence having the same class as " { $snippet "seq1" } ". Order is the same as a nested for loop." } ;
 495
 496 HELP: <step-slice>
 497 { $values
 498     { "from/f" { $maybe integer } } { "to/f" { $maybe integer } } { "step" object } { "seq" sequence }
 499     { "step-slice" slice }
 500 }
 501 { $description "Outputs a new virtual sequence sharing storage with the subrange of elements in " { $snippet "seq" } " with indices starting from and including " { $snippet "from/f" } ", and up to but not including " { $snippet "to/f" } ", with step " { $snippet "step" } "."
 502   $nl
 503   "If " { $link f } "is given in place of " { $snippet "from/f" } ", it is taken as 0."
 504   $nl
 505   "If " { $link f } "is given in place of " { $snippet "to/f" } ", it is taken as the length of " { $snippet "seq" } "." }
 506 ;
 507
 508 HELP: <zip-index>
 509 { $values
 510     { "seq" sequence }
 511     { "virtual-zip-index" object }
 512 }
 513 { $description "Outputs a new virtual sequence which pairs the elements of " { $snippet "seq" } " with their 0-based indices." } ;
 514
 515 HELP: >string-list
 516 { $values
 517     { "seq" sequence }
 518     { "seq'" sequence }
 519 }
 520 { $description "Surrounds each element of " { $snippet "seq" } " in quotes and joins the sequence with commas."  } ;
 521
 522 HELP: ?<slice>
 523 { $values
 524     { "from/f" { $maybe integer } } { "to/f" { $maybe integer } } { "sequence" sequence }
 525     { "slice" slice }
 526 }
 527 { $description "Outputs a new virtual sequence sharing storage with the subrange of elements in " { $snippet "seq" } " with indices starting from and including " { $snippet "from/f" } ", and up to but not including " { $snippet "to/f" } ". If either of these is not specified, they are substituted with the array's bounds: 0 and its length." } ;
 528
 529 HELP: ?first2
 530 { $values
 531     { "seq" sequence }
 532     { "first/f" object } { "second/f" object }
 533 }
 534 { $description "Pushes the first two elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 535
 536 HELP: ?first3
 537 { $values
 538     { "seq" sequence }
 539     { "first/f" object } { "second/f" object } { "third/f" object }
 540 }
 541 { $description "Pushes the first three elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 542
 543 HELP: ?first4
 544 { $values
 545     { "seq" sequence }
 546     { "first/f" object } { "second/f" object } { "third/f" object } { "fourth/f" object }
 547 }
 548 { $description "Pushes the first four elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 549
 550 HELP: ?heap-pop-value>array
 551 { $values
 552     { "heap" object }
 553     { "array" array }
 554 }
 555 { $description "Pushes the value at the top of " { $snippet "heap" } " as a single element array. Returns an empty array if the heap is empty." } ;
 556
 557 HELP: ?span-slices
 558 { $values
 559     { "slice1/f" { $maybe slice } } { "slice2/f" { $maybe slice } }
 560     { "slice" slice }
 561 }
 562 { $description "Create a virtual sequence spanning the length covered by " { $snippet "slice1" } " and " { $snippet "slice2" } ". Slices must refer to the same sequence. If " { $snippet "f" } "is one of the inputs, it is omitted." } ;
 563
 564 HELP: ?trim
 565 { $values
 566     { "seq" sequence } { "quot" quotation }
 567     { "seq/newseq" object }
 568 }
 569 { $description "Similar to " { $link trim } ", but sequences that do not require trimming are left as is." } ;
 570
 571 HELP: ?trim-head
 572 { $values
 573     { "seq" sequence } { "quot" quotation }
 574     { "seq/newseq" object }
 575 }
 576 { $description "Similar to " { $link trim-head } ", but sequences that do not require trimming are left as is." } ;
 577
 578 HELP: ?trim-tail
 579 { $values
 580     { "seq" sequence } { "quot" quotation }
 581     { "seq/newseq" object }
 582 }
 583 { $description "Similar to " { $link trim-tail } ", but sequences that do not require trimming are left as is." } ;
 584
 585 HELP: all-longest
 586 { $values
 587     { "seqs" object }
 588     { "seqs'" object }
 589 }
 590 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the longest length." } ;
 591
 592 HELP: all-rotations
 593 { $values
 594     { "seq" sequence }
 595     { "seq'" sequence }
 596 }
 597 { $description "Pushes a sequence containing all the rotations of " { $snippet "seq" } ", including the original array." } ;
 598
 599 HELP: all-shortest
 600 { $values
 601     { "seqs" object }
 602     { "seqs'" object }
 603 }
 604 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the shortest length." } ;
 605
 606 HELP: all-subseqs
 607 { $values
 608     { "seq" sequence }
 609     { "seqs" object }
 610 }
 611 { $description "Pushes a sequence containing all subsequences in " { $snippet "seq" } " excluding the empty sequence." } ;
 612
 613 HELP: appender
 614 { $values
 615     { "quot" quotation }
 616     { "appender" quotation } { "accum" vector }
 617 }
 618 { $description "Given a quotation " { $snippet "quot" } ", creates an appender quotation and empty vector to append new sequences to it. The appender quotation will apply " { $snippet "quot" } " to its argument before appending it to the vector." } ;
 619
 620 HELP: appender-for
 621 { $values
 622     { "quot" quotation } { "exemplar" object }
 623     { "appender" object } { "accum" object }
 624 }
 625 { $description "Given a quotation " { $snippet "quot" } ", creates an appender quotation and empty vector with a maximum storage limit the size of " { $snippet "exemplar" } ". The appender quotation will apply " { $snippet "quot" } " to its argument before appending it to the vector." } ;
 626
 627 HELP: arg-sort
 628 { $values
 629     { "seq" sequence }
 630     { "indices" object }
 631 }
 632 { $description "Given a sequence " { $snippet "seq" } ", push a sequence of indices that when indexed into, sort the given sequence." } ;
 633
 634 HELP: arg-where
 635 { $values
 636     { "seq" sequence } { "quot" quotation }
 637     { "indices" object }
 638 }
 639 { $description "Push a sequence of all indices in " { $snippet "seq" } " where " { $snippet "quot" } "applied to the element at each index is true." } ;
 640
 641 HELP: assoc-zip-with
 642 { $values
 643     { "quot" quotation } { "alist" "an array of key/value pairs" }
 644 }
 645 { $description "Applies " { $snippet "quot" } " to each key-value pair in the given assoc, pushing a new assoc with the key-value pairs as keys, and the values computed by " { $snippet "quot" } " as values." } ;
 646
 647 HELP: change-last
 648 { $values
 649     { "seq" sequence } { "quot" quotation }
 650 }
 651 { $description "Applies " { $snippet "quot" } " to the last element of a sequence, modifying it in place." } ;
 652
 653 HELP: change-last-unsafe
 654 { $values
 655     { "seq" sequence } { "quot" quotation }
 656 }
 657 { $description "Applies " { $snippet "quot" } " to the last element of a sequence, modifying it in place. Does not check if the array has a last element." } ;
 658
 659 HELP: change-nths
 660 { $values
 661     { "indices" object } { "seq" sequence } { "quot" quotation }
 662 }
 663 { $description "Applies " { $snippet "quot" } " to the locations present in " { $snippet "indices" } " in sequence " { $snippet "seq" } ", modifying it in place." } ;
 664
 665 HELP: collect-with-previous
 666 { $values
 667     { "n" integer } { "quot" quotation } { "into" object }
 668 } ;
 669
 670 HELP: count-head
 671 { $values
 672     { "seq" sequence } { "quot" quotation }
 673     { "n" integer }
 674 }
 675 { $description "Count the number of values at the beginning of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
 676
 677 HELP: count-tail
 678 { $values
 679     { "seq" sequence } { "quot" quotation }
 680     { "n" integer }
 681 }
 682 { $description "Count the number of values from the end of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
 683
 684 HELP: cut-when
 685 { $values
 686     { "seq" sequence } { "quot" quotation }
 687     { "before" object } { "after" object }
 688 }
 689 { $description "Cut the given sequence before the first element of " { $snippet "seq" } " that returns a truthy value when passed into " { $snippet "quot" } "." } ;
 690
 691 HELP: drop-while
 692 { $values
 693     { "seq" sequence } { "quot" quotation }
 694     { "tail-slice" object }
 695 }
 696 { $description "Remove all values at the beginning of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } ". Return a virtual sequence containing those elements." } ;
 697
 698 HELP: each-index-from
 699 { $values
 700     { "seq" sequence } { "quot" quotation } { "i" integer }
 701 } ;
 702
 703 HELP: each-integer-with-previous
 704 { $values
 705     { "n" integer } { "quot" quotation }
 706 } ;
 707
 708 HELP: each-prior
 709 { $values
 710     { "seq" sequence } { "quot" quotation }
 711 } ;
 712
 713 HELP: each-subseq
 714 { $values
 715     { "seq" sequence } { "quot" quotation }
 716 } ;
 717
 718 HELP: ensure-same-underlying
 719 { $values
 720     { "slice1" slice } { "slice2" slice }
 721 } ;
 722
 723 HELP: even-indices
 724 { $values
 725     { "seq" sequence }
 726     { "seq'" sequence }
 727 }
 728 { $description "Push a sequence containing the even-indexed elements in " { $snippet "seq" } "." } ;
 729
 730 HELP: evens
 731 { $class-description "The class of virtual sequences which contain the even-indexed elements of a given sequence." } ;
 732
 733 HELP: extract!
 734 { $values
 735     { "seq" sequence } { "quot" quotation }
 736 } ;
 737
 738 HELP: filter-all-subseqs
 739 { $values
 740     { "seq" sequence } { "quot" quotation }
 741 }
 742 { $description "Perform a filter on all the subsequences of the given sequence, and push a sequence containing the subsequences that satisfy the condition given by " { $snippet "quot" } "." } ;
 743
 744 HELP: filter-all-subseqs-range
 745 { $values
 746     { "seq" sequence } { "range" object } { "quot" quotation }
 747 }
 748 { $description "Perform a filter on all the subsequences of the given sequence that have length within " { $snippet "range" } ", and push a sequence containing the subsequences that satisfy the condition given by " { $snippet "quot" } "." } ;
 749
 750 HELP: filter-index
 751 { $values
 752     { "seq" sequence } { "quot" quotation }
 753     { "seq'" sequence }
 754 }
 755 { $description "Perform a " { $link filter } " on the given sequence, with the index provided as an additional argument to " { $snippet "quot" } "." } ;
 756
 757 HELP: filter-index-as
 758 { $values
 759     { "seq" sequence } { "quot" quotation } { "exemplar" object }
 760     { "seq'" sequence }
 761 }
 762 { $description "Perform a " { $link filter-as } " on the given sequence, with the index provided as an additional argument to " { $snippet "quot" } ". Outputs a sequence of the same class as " { $snippet "exemplar" } "." } ;
 763
 764 HELP: filter-length
 765 { $values
 766     { "seq" sequence } { "n" integer }
 767     { "seq'" sequence }
 768 }
 769 { $description "Push a sequence that contains all elements of " { $snippet "seq" } " that have length " { $snippet "n" } "." } ;
 770
 771 HELP: filter-map
 772 { $values
 773     { "seq" sequence } { "filter-quot" object } { "map-quot" object }
 774     { "newseq" sequence }
 775 }
 776 { $description "Filter the given sequence with " { $snippet "filter-quot" } ", then perform a map on the filtered sequence with " { $snippet "map-quot" } "." } ;
 777
 778 HELP: filter-map-as
 779 { $values
 780     { "seq" sequence } { "filter-quot" object } { "map-quot" object } { "exemplar" object }
 781     { "newseq" sequence }
 782 }
 783 { $description "Filter the given sequence with " { $snippet "filter-quot" } ", then perform a map on the filtered sequence with " { $snippet "map-quot" } ". Outputs a sequence of the same class as " { $snippet "exemplar" } "." } ;
 784
 785 HELP: find-last-index
 786 { $values
 787     { "seq" sequence } { "quot" quotation }
 788     { "i" integer } { "elt" object }
 789 }
 790 { $description "A simpler variant of " { $link find-last-index-from } ", with starting index set to 0." } ;
 791
 792 HELP: find-last-index-from
 793 { $values
 794     { "n" integer } { "seq" sequence } { "quot" quotation }
 795     { "i" integer } { "elt" object }
 796 }
 797 { $description "Similar to " { $snippet "find-from" } ", except " { $snippet "quot" } " is given the index of each element, and the index of the found element is pushed along with the found element." } ;
 798
 799 HELP: find-pred-loop
 800 { $values
 801     { "i" integer } { "n" integer } { "seq" sequence } { "quot" quotation }
 802     { "calc/f" object } { "i/f" { $maybe integer } } { "elt/f" object }
 803 } ;
 804
 805 HELP: harvest!
 806 { $values
 807     { "seq" sequence }
 808     { "newseq" sequence }
 809 }
 810 { $description "Outputs a new sequence with all empty sequences removed. Modifies " { $snippet "seq" } "in place." } ;
 811
 812 HELP: harvest-as
 813 { $values
 814     { "seq" sequence } { "exemplar" object }
 815     { "newseq" sequence }
 816 }
 817 { $description "Outputs a new sequence with all empty sequences removed. Resulting sequence is the same class as " { $snippet "exemplar" } "." } ;
 818
 819 HELP: head*-as
 820 { $values
 821     { "seq" sequence } { "n" integer } { "exemplar" object }
 822     { "seq'" sequence }
 823 }
 824 { $description "A version of " { $link head* } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
 825
 826 HELP: head-as
 827 { $values
 828     { "seq" sequence } { "n" integer } { "exemplar" object }
 829     { "seq'" sequence }
 830 }
 831 { $description "A version of " { $link head } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
 832
 833 HELP: heap>pairs
 834 { $values
 835     { "heap" object }
 836     { "pairs" object }
 837 }
 838 { $description "Collect the pairs inside a heap into a sequence. Ordering of the sequence is based on the ordering of the heap." } ;
 839
 840 HELP: index-selector
 841 { $values
 842     { "quot" quotation }
 843     { "selector" object } { "accum" object }
 844 } ;
 845
 846 HELP: index-selector-as
 847 { $values
 848     { "quot" quotation } { "exemplar" object }
 849     { "selector" object } { "accum" object }
 850 } ;
 851
 852 HELP: infimum-by*
 853 { $values
 854     { "seq" sequence } { "quot" quotation }
 855     { "i" integer } { "elt" object }
 856 }
 857 { $description "A variant of " { $link infimum-by } " that pushes the index of the least element along with the least element." } ;
 858
 859 HELP: insert-nth!
 860 { $values
 861     { "elt" object } { "n" integer } { "seq" sequence }
 862 }
 863 { $description "A variant of " { $link insert-nth } " that modifies " { $snippet "seq" } " in place." } ;
 864
 865 HELP: interleaved
 866 { $values
 867     { "seq" sequence } { "glue" object }
 868     { "newseq" sequence }
 869 }
 870 { $description "Insert " { $link glue } " between every pair of elements in " { $snippet "seq" } "." } ;
 871
 872 HELP: interleaved-as
 873 { $values
 874     { "seq" sequence } { "glue" object } { "exemplar" object }
 875     { "newseq" sequence }
 876 }
 877 { $description "Insert " { $link glue } " between every pair of elements in " { $snippet "seq" } ". Resulting sequence will be the same class as " { $snippet "exemplar" } "." } ;
 878
 879 HELP: iterate-heap-while
 880 { $values
 881     { "heap" object } { "quot1" quotation } { "quot2" quotation }
 882     { "obj/f" { $maybe object } } { "loop?" object }
 883 } ;
 884
 885 HELP: last=
 886 { $values
 887     { "seq" sequence } { "elt" object }
 888     { "?" boolean }
 889 }
 890 { $description "Check if the last element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 891
 892 HELP: last?
 893 { $values
 894     { "seq" sequence } { "quot" quotation }
 895     { "?" boolean }
 896 }
 897 { $description "Check if the last element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
 898
 899 HELP: longest-subseq
 900 { $values
 901     { "seq1" sequence } { "seq2" sequence }
 902     { "subseq" object }
 903 }
 904 { $description "Pushes the longest subsequence of " { $snippet "seq" } "." } ;
 905
 906 HELP: map-concat
 907 { $values
 908     { "seq" sequence } { "quot" quotation }
 909     { "newseq" sequence }
 910 }
 911 { $description "Perform a " { $link map } " on the given sequence with " { $snippet "quot" } ", then perform a " { $link concat } " on the result." } ;
 912
 913 HELP: map-concat-as
 914 { $values
 915     { "seq" sequence } { "quot" quotation } { "exemplar" object }
 916     { "newseq" sequence }
 917 }
 918 { $description "A version of " { $link map-concat } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 919
 920 HELP: map-filter
 921 { $values
 922     { "seq" sequence } { "map-quot" object } { "filter-quot" object }
 923     { "subseq" object }
 924 }
 925 { $description "Perform a " { $link map } " on the given sequence with " { $snippet "map-quot" } ", then perform a " { $link filter } " on the result with " { $snippet "filter-quot" } "." } ;
 926
 927 HELP: map-filter-as
 928 { $values
 929     { "seq" sequence } { "map-quot" object } { "filter-quot" object } { "exemplar" object }
 930     { "subseq" object }
 931 }
 932 { $description "A version of " { $link map-filter } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 933
 934 HELP: map-find-index
 935 { $values
 936     { "seq" sequence } { "quot" quotation }
 937     { "result" object } { "i" integer } { "elt" object }
 938 }
 939 { $description "A version of " { $link map-find } " where the index of the found element, if any, is returned." } ;
 940
 941 HELP: map-find-last-index
 942 { $values
 943     { "seq" sequence } { "quot" quotation }
 944     { "result" object } { "i" integer } { "elt" object }
 945 }
 946 { $description "A version of " { $link map-find-index } " where the index of the found element, if any, is returned." } ;
 947
 948 HELP: map-from
 949 { $values
 950     { "seq" sequence } { "quot" quotation } { "from" integer }
 951     { "newseq" sequence }
 952 }
 953 { $description "A version of " { $link map } " that maps the slice of " { $snippet "seq" } " beginning at index " { $snippet "i" } "." } ;
 954
 955 HELP: map-from-as
 956 { $values
 957     { "seq" sequence } { "quot" quotation } { "from" integer } { "exemplar" object }
 958     { "newseq" sequence }
 959 }
 960 { $description "A version of " { $link map-from } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 961
 962 HELP: map-harvest
 963 { $values
 964     { "seq" sequence } { "quot" quotation }
 965     { "newseq" sequence }
 966 }
 967 { $description "A version of " { $link map } " with all empty sequences removed from the result." } ;
 968
 969 HELP: map-if
 970 { $values
 971     { "seq" sequence } { "if-quot" object } { "map-quot" object }
 972     { "newseq" sequence }
 973 }
 974 { $description "A version of " { $link map } " where " { $snippet "map-quot" } " is applied only if " { $snippet "if-quot" } " returns true for a given element." } ;
 975
 976 HELP: map-index!
 977 { $values
 978     { "seq" sequence } { "quot" quotation }
 979 }
 980 { $description "A version of " { $link map-index } " which modifies " { $snippet "seq" } " in place." } ;
 981
 982 HELP: map-integers-with
 983 { $values
 984     { "len" object } { "quot" quotation } { "exemplar" object }
 985     { "newseq" sequence }
 986 } ;
 987
 988 HELP: map-like
 989 { $values
 990     { "seq" sequence } { "exemplar" object }
 991     { "seq'" sequence }
 992 } ;
 993
 994 HELP: map-prior
 995 { $values
 996     { "seq" sequence } { "quot" quotation }
 997     { "seq'" sequence }
 998 } ;
 999
1000 HELP: map-prior-as
1001 { $values
1002     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1003     { "seq'" sequence }
1004 } ;
1005
1006 HELP: map-product
1007 { $values
1008     { "seq" sequence } { "quot" quotation }
1009     { "n" integer }
1010 }
1011 { $description "Like " { $code "map product" } ", but without creating an intermediate sequence." } ;
1012
1013 HELP: map-sift
1014 { $values
1015     { "seq" sequence } { "quot" quotation }
1016     { "newseq" sequence }
1017 }
1018 { $description "A version of " { $link map } " with all instances of " { $link f } " removed from the result." } ;
1019
1020 HELP: map-with-previous
1021 { $values
1022     { "seq" sequence } { "quot" quotation }
1023     { "newseq" sequence }
1024 } ;
1025
1026 HELP: map-with-previous-as
1027 { $values
1028     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1029     { "newseq" sequence }
1030 } ;
1031
1032 HELP: map-zip-swap
1033 { $values
1034     { "quot" quotation }
1035     { "alist" "an array of key/value pairs" }
1036 } ;
1037
1038 HELP: max-subarray-sum
1039 { $values
1040     { "seq" sequence }
1041     { "sum" object }
1042 }
1043 { $description "Output the maximum subarray sum of the sequence." } ;
1044
1045 HELP: merge-slices
1046 { $values
1047     { "slice1" slice } { "slice2" slice }
1048     { "slice/*" object }
1049 } ;
1050
1051 HELP: nth-of
1052 { $values { "seq" sequence } { "n" "a non-negative integer" } { "elt" "the element at the " { $snippet "n" } "th index" } }
1053 { $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." }
1054 { $errors "Throws a " { $link bounds-error } " if the index is negative, or greater than or equal to the length of the sequence." } ;
1055
1056 HELP: nth*
1057 { $values
1058     { "n" integer } { "seq" sequence }
1059     { "elt" object }
1060 }
1061 { $description "Pushes the nth element of the sequence if it exists, otherwise pushes sequence length - 1." } ;
1062
1063 HELP: nth=
1064 { $values
1065     { "n" integer } { "seq" sequence } { "elt" object }
1066     { "?" boolean }
1067 }
1068 { $description "Check if the nth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
1069
1070 HELP: nth?
1071 { $values
1072     { "n" integer } { "seq" sequence } { "quot" quotation }
1073     { "?" boolean }
1074 }
1075 { $description "Check if the nth element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
1076
1077 HELP: ??nth
1078 { $values { "n" integer } { "seq" sequence } { "elt/f" { $maybe object } } { "?" boolean } }
1079 { $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 } ". Also outputs a boolean to distinguish between the sequence containing an " { $link f } " or an out of bounds index." } ;
1080
1081 HELP: odd-indices
1082 { $values
1083     { "seq" sequence }
1084     { "seq'" sequence }
1085 }
1086 { $description "Push a sequence containing the odd-indexed elements in " { $snippet "seq" } "." } ;
1087
1088 HELP: odds
1089 { $class-description "The class of virtual sequences which contain the odd-indexed elements of a given sequence." } ;
1090
1091 HELP: one?
1092 { $values
1093     { "seq" sequence } { "quot" quotation }
1094     { "?" boolean }
1095 } ;
1096
1097 HELP: ordered-slices-overlap?
1098 { $values
1099     { "slice-lt" object } { "slice-gt" object }
1100     { "?" boolean }
1101 } ;
1102
1103 HELP: ordered-slices-range
1104 { $values
1105     { "slice-lt" object } { "slice-gt" object }
1106     { "to" integer } { "from" integer }
1107 } ;
1108
1109 HELP: ordered-slices-touch?
1110 { $values
1111     { "slice-lt" object } { "slice-gt" object }
1112     { "?" boolean }
1113 } ;
1114
1115 HELP: pad-longest
1116 { $values
1117     { "seq1" sequence } { "seq2" sequence } { "elt" object }
1118 }
1119 { $description "Perform " { $link pad-tail } " on both sequences, padding with " { $snippet "elt" } " to the longest length between the two." } ;
1120
1121 HELP: prepend-lines-with-spaces
1122 { $values
1123     { "str" string }
1124     { "str'" string }
1125 }
1126 { $description "Prepend four spaces to each line in " { $snippet "str" } "." } ;
1127
1128 HELP: push-if*
1129 { $values
1130     { "elt" object } { "quot" quotation } { "accum" object }
1131 } ;
1132
1133 HELP: push-if-index
1134 { $values
1135     { "elt" object } { "i" integer } { "quot" quotation } { "accum" object }
1136 } ;
1137
1138 HELP: reduce-from
1139 { $values
1140     { "seq" sequence } { "identity" object } { "quot" quotation } { "from" integer }
1141     { "result" object }
1142 } ;
1143
1144 HELP: remove-first
1145 { $values
1146     { "obj" object } { "seq" sequence }
1147     { "seq'" sequence }
1148 }
1149 { $description "Remove the first occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1150
1151 HELP: remove-first!
1152 { $values
1153     { "obj" object } { "seq" sequence }
1154 }
1155 { $description "A version of " { $link remove-first } " that modifies " { $snippet "seq" } " in place." } ;
1156
1157 HELP: remove-last
1158 { $values
1159     { "obj" object } { "seq" sequence }
1160     { "seq'" sequence }
1161 }
1162 { $description "Remove the last occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1163
1164 HELP: remove-last!
1165 { $values
1166     { "obj" object } { "seq" sequence }
1167 }
1168 { $description "A version of " { $link remove-last } " that modifies " { $snippet "seq" } " in place." } ;
1169
1170 HELP: replicate-into
1171 { $values
1172     { "seq" sequence } { "quot" quotation }
1173 } ;
1174
1175 HELP: reverse-as
1176 { $values
1177     { "seq" sequence } { "exemplar" object }
1178     { "newseq" sequence }
1179 }
1180 { $description "A version of " { $link reverse } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
1181
1182 HELP: rotate
1183 { $values
1184     { "seq" sequence } { "n" integer }
1185     { "seq'" sequence }
1186 }
1187 { $description "Move the first " { $snippet "n" } " elements of " { $snippet "seq" } " to the end." } ;
1188
1189 HELP: rotate!
1190 { $values
1191     { "seq" sequence } { "n" integer }
1192 }
1193 { $description "A version of " { $link rotate } " that modifies " { $snippet "seq" } " in place." } ;
1194
1195 HELP: round-robin
1196 { $values
1197     { "seq" sequence }
1198     { "newseq" sequence }
1199 }
1200 { $description "List all elements of " { $snippet "seq" } " in column-major order." } ;
1201
1202 HELP: safe-subseq
1203 { $values
1204     { "from" integer } { "to" integer } { "seq" sequence }
1205     { "subseq" object }
1206 }
1207 { $description "A safe version of " { $link subseq } "." } ;
1208
1209 HELP: selector*
1210 { $values
1211     { "quot" quotation }
1212     { "selector" object } { "accum" object }
1213 } ;
1214
1215 HELP: selector-as*
1216 { $values
1217     { "quot" quotation } { "exemplar" object }
1218     { "selector" object } { "accum" object }
1219 } ;
1220
1221 HELP: sequence-index-operator-last
1222 { $values
1223     { "n" integer } { "seq" sequence } { "quot" quotation }
1224     { "quot'" quotation }
1225 } ;
1226
1227 HELP: sequence>slice
1228 { $values
1229     { "sequence" sequence }
1230     { "slice" slice }
1231 }
1232 { $description "Create a virtual sequence that represents the given sequence." } ;
1233
1234 HELP: set-nths
1235 { $values
1236     { "value" object } { "indices" object } { "seq" sequence }
1237 }
1238 { $description "Set the elements at all given indices to " { $snippet "value" } ". modifies " { $snippet "seq" } " in place." } ;
1239
1240 HELP: set-nths-unsafe
1241 { $values
1242     { "value" object } { "indices" object } { "seq" sequence }
1243 }
1244 { $description "Unsafe version of " { $link set-nths } } ;
1245
1246 HELP: shorten*
1247 { $values
1248     { "vector" object } { "n" integer }
1249     { "seq" sequence }
1250 } ;
1251
1252 HELP: sift!
1253 { $values
1254     { "seq" sequence }
1255     { "newseq" sequence }
1256 } ;
1257
1258 HELP: sift-as
1259 { $values
1260     { "seq" sequence } { "exemplar" object }
1261     { "newseq" sequence }
1262 } ;
1263
1264 HELP: slice-order-by-from
1265 { $values
1266     { "slice1" slice } { "slice2" slice }
1267     { "slice-lt" object } { "slice-gt" object }
1268 } ;
1269
1270 HELP: slice-when
1271 { $values
1272     { "seq" sequence } { "quot" quotation }
1273     { "seq'" sequence }
1274 } ;
1275
1276 HELP: slices-don't-touch
1277 { $values
1278     { "slice1" slice } { "slice2" slice }
1279 }
1280 { $description "Throws a " { $link slices-don't-touch } " error." }
1281 { $error-description "" } ;
1282
1283 HELP: slices-overlap?
1284 { $values
1285     { "slice1" slice } { "slice2" slice }
1286     { "?" boolean }
1287 } ;
1288
1289 HELP: slices-touch?
1290 { $values
1291     { "slice1" slice } { "slice2" slice }
1292     { "?" boolean }
1293 } ;
1294
1295 HELP: slurp-heap-while-map
1296 { $values
1297     { "heap" object } { "quot1" quotation } { "quot2" quotation }
1298     { "seq" sequence }
1299 } ;
1300
1301 HELP: span-slices
1302 { $values
1303     { "slice1" slice } { "slice2" slice }
1304     { "slice" slice }
1305 }
1306 { $description "Create a virtual sequence spanning the length covered by " { $snippet "slice1" } " and " { $snippet "slice2" } ". Slices must refer to the same sequence." } ;
1307
1308 HELP: supremum-by*
1309 { $values
1310     { "seq" sequence } { "quot" quotation }
1311     { "i" integer } { "elt" object }
1312 } ;
1313
1314 HELP: tail*-as
1315 { $values
1316     { "seq" sequence } { "n" integer } { "exemplar" object }
1317     { "seq'" sequence }
1318 } ;
1319
1320 HELP: tail-as
1321 { $values
1322     { "seq" sequence } { "n" integer } { "exemplar" object }
1323     { "seq'" sequence }
1324 } ;
1325
1326 HELP: take-while
1327 { $values
1328     { "seq" sequence } { "quot" quotation }
1329     { "head-slice" object }
1330 } ;
1331
1332 HELP: trim-as
1333 { $values
1334     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1335     { "newseq" sequence }
1336 } ;
1337
1338 HELP: underlying-mismatch
1339 { $values
1340     { "slice1" slice } { "slice2" slice }
1341 }
1342 { $description "Throws an " { $link underlying-mismatch } " error." }
1343 { $error-description "" } ;
1344
1345 HELP: unordered-slices-overlap?
1346 { $values
1347     { "slice1" slice } { "slice2" slice }
1348     { "?" boolean }
1349 } ;
1350
1351 HELP: unordered-slices-range
1352 { $values
1353     { "slice1" slice } { "slice2" slice }
1354     { "to" integer } { "from" integer }
1355 } ;
1356
1357 HELP: unordered-slices-touch?
1358 { $values
1359     { "slice1" slice } { "slice2" slice }
1360     { "?" boolean }
1361 } ;
1362
1363 HELP: until-empty
1364 { $values
1365     { "seq" sequence } { "quot" quotation }
1366 } ;
1367
1368 HELP: with-string-lines
1369 { $values
1370     { "str" string } { "quot" quotation }
1371     { "str'" string }
1372 } ;
1373
1374 HELP: exchange-subseq
1375 { $values
1376     { "len" { "a non-negative " { $link integer } } }
1377     { "pos1" { "a non-negative " { $link integer } } }
1378     { "pos2" { "a non-negative " { $link integer } } }
1379     { "seq" { "a mutable " { $link sequence } } }
1380 }
1381 { $description "Exchanges the contents of subsequences "
1382 { $snippet "[pos1, pos1+len)" } " and " { $snippet "[pos2, pos2+len)" } " in "
1383 { $snippet "seq" } ". Overlapping ranges are allowed. If either of the ranges exceeds the "
1384 { $snippet "seq" } " length, throws an error before any modifications take place. If "
1385 { $snippet "len" } " = 1, the behavior is equivalent to " { $link exchange } "." }
1386 { $examples
1387     "Non-overlapping ranges:"
1388     { $example "USING: kernel sequences.extras prettyprint ;"
1389         "2 0 3 \"01_34_\" [ exchange-subseq ] keep ."
1390         "\"34_01_\""
1391     }
1392     "Overlapping ranges:"
1393     { $example "USING: kernel sequences.extras prettyprint ;"
1394         "3 0 2 \"abcdef\" [ exchange-subseq ] keep ."
1395         "\"cdebaf\""
1396     }
1397 }
1398 { $side-effects "seq" }
1399 { $see-also exchange } ;