extra/sequences/extras/extras-docs.factor

   1 USING: arrays help.markup help.syntax kernel math multiline
   2 quotations sequences ;
   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: count*
  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? ] count* ." "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 sequence with the largest item." } ;
 245
 246 HELP: arg-min
 247 { $values { "seq" sequence } { "n" integer } }
 248 { $description "Outputs the sequence with the smallest item." } ;
 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 { $description "" } ;
 434
 435 HELP: (each-integer-with-previous)
 436 { $values
 437     { "prev" object } { "i" integer } { "n" integer } { "quot" quotation }
 438 }
 439 { $description "" } ;
 440
 441 HELP: (start-all)
 442 { $values
 443     { "seq" sequence } { "subseq" object } { "increment" object }
 444     { "indices" object }
 445 }
 446 { $description "" } ;
 447
 448 HELP: 2map-into
 449 { $values
 450     { "seq1" sequence } { "seq2" sequence } { "quot" quotation } { "into" object }
 451 }
 452 { $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" } "." } ;
 453
 454 HELP: 2map-sum
 455 { $values
 456     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 457     { "n" integer }
 458 }
 459 { $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." } ;
 460
 461 HELP: 2nested-each
 462 { $values
 463     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 464 }
 465 { $description "Applies quotation to all pairs of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ". Order is the same as a nested for loop." } ;
 466
 467 HELP: 2nested-map
 468 { $values
 469     { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
 470     { "seq" sequence }
 471 }
 472 { $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." } ;
 473
 474 HELP: 3each-from
 475 { $values
 476     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation } { "i" integer }
 477 }
 478 { $description "" } ;
 479
 480 HELP: 3map-reduce
 481 { $values
 482     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "map-quot" object } { "reduce-quot" object }
 483     { "result" object }
 484 }
 485 { $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" } "." } ;
 486
 487 HELP: 3nested-each
 488 { $values
 489     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
 490 }
 491 { $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." } ;
 492
 493 HELP: 3nested-map
 494 { $values
 495     { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
 496     { "seq" sequence }
 497 }
 498 { $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." } ;
 499
 500 HELP: <step-slice>
 501 { $values
 502     { "from" integer } { "to" integer } { "step" object } { "seq" sequence }
 503     { "step-slice" slice }
 504 }
 505 { $description "Outputs a new virtual sequence sharing storage with the subrange of elements in " { $snippet "seq" } " with indices starting from and including " { $snippet "from" } ", and up to but not including " { $snippet "to" } ", with step " { $snippet "step" } "." } ;
 506
 507 HELP: <zip-index>
 508 { $values
 509     { "seq" sequence }
 510     { "virtual-zip-index" object }
 511 }
 512 { $description "Outputs a new virtual sequence which pairs the elements of " { $snippet "seq" } " with their 0-based indices." } ;
 513
 514 HELP: >string-list
 515 { $values
 516     { "seq" sequence }
 517     { "seq'" sequence }
 518 }
 519 { $description "Surrounds each element of " { $snippet "seq" } " in quotes and joins the sequence with commas."  } ;
 520
 521 HELP: ?<slice>
 522 { $values
 523     { "from/f" { $maybe integer } } { "to/f" { $maybe integer } } { "sequence" sequence }
 524     { "slice" slice }
 525 }
 526 { $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." } ;
 527
 528 HELP: ?first2
 529 { $values
 530     { "seq" sequence }
 531     { "first/f" object } { "second/f" object }
 532 }
 533 { $description "Pushes the first two elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 534
 535 HELP: ?first3
 536 { $values
 537     { "seq" sequence }
 538     { "first/f" object } { "second/f" object } { "third/f" object }
 539 }
 540 { $description "Pushes the first three elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 541
 542 HELP: ?first4
 543 { $values
 544     { "seq" sequence }
 545     { "first/f" object } { "second/f" object } { "third/f" object } { "fourth/f" object }
 546 }
 547 { $description "Pushes the first four elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
 548
 549 HELP: ?heap-pop-value>array
 550 { $values
 551     { "heap" object }
 552     { "array" array }
 553 }
 554 { $description "Pushes the value at the top of " { $snippet "heap" } " as a single element array. Returns an empty array if the heap is empty." } ;
 555
 556 HELP: ?span-slices
 557 { $values
 558     { "slice1/f" { $maybe slice } } { "slice2/f" { $maybe slice } }
 559     { "slice" slice }
 560 }
 561 { $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." } ;
 562
 563 HELP: ?trim
 564 { $values
 565     { "seq" sequence } { "quot" quotation }
 566     { "seq/newseq" object }
 567 }
 568 { $description "Similar to " { $link "trim" } ", but sequences that do not require trimming are left as is." } ;
 569
 570 HELP: ?trim-head
 571 { $values
 572     { "seq" sequence } { "quot" quotation }
 573     { "seq/newseq" object }
 574 }
 575 { $description "Similar to " { $link "trim-head" } ", but sequences that do not require trimming are left as is." } ;
 576
 577 HELP: ?trim-tail
 578 { $values
 579     { "seq" sequence } { "quot" quotation }
 580     { "seq/newseq" object }
 581 }
 582 { $description "Similar to " { $link "trim-tail" } ", but sequences that do not require trimming are left as is." } ;
 583
 584 HELP: all-longest
 585 { $values
 586     { "seqs" object }
 587     { "seqs'" object }
 588 }
 589 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the longest length." } ;
 590
 591 HELP: all-rotations
 592 { $values
 593     { "seq" sequence }
 594     { "seq'" sequence }
 595 }
 596 { $description "Pushes a sequence containing all the rotations of " { $snippet "seq" } ", including the original array." } ;
 597
 598 HELP: all-shortest
 599 { $values
 600     { "seqs" object }
 601     { "seqs'" object }
 602 }
 603 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the shortest length." } ;
 604
 605 HELP: all-subseqs
 606 { $values
 607     { "seq" sequence }
 608     { "seqs" object }
 609 }
 610 { $description "Pushes a sequence containing all subsequences in " { $snippet "seq" } " excluding the empty sequence." } ;
 611
 612 HELP: appender
 613 { $values
 614     { "quot" quotation }
 615     { "appender" quotation } { "accum" vector }
 616 }
 617 { $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." } ;
 618
 619 HELP: appender-for
 620 { $values
 621     { "quot" quotation } { "exemplar" object }
 622     { "appender" object } { "accum" object }
 623 }
 624 { $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." } ;
 625
 626 HELP: arg-sort
 627 { $values
 628     { "seq" sequence }
 629     { "indices" object }
 630 }
 631 { $description "Given a sequence " { $snippet "seq" } ", push a sequence of indices that when indexed into, sort the given sequence." } ;
 632
 633 HELP: arg-where
 634 { $values
 635     { "seq" sequence } { "quot" quotation }
 636     { "indices" object }
 637 }
 638 { $description "Push a sequence of all indices in " { $snippet "seq" } " where " { $snippet "quot" } "applied to the element at each index is true." } ;
 639
 640 HELP: assoc-zip-with
 641 { $values
 642     { "seq" assoc } { "quot" quotation }
 643     { "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 { $description "" } ;
 670
 671 HELP: count-head
 672 { $values
 673     { "seq" sequence } { "quot" quotation }
 674     { "n" integer }
 675 }
 676 { $description "Count the number of values at the beginning of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
 677
 678 HELP: count-tail
 679 { $values
 680     { "seq" sequence } { "quot" quotation }
 681     { "n" integer }
 682 }
 683 { $description "Count the number of values at the beginning of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
 684
 685 HELP: cut-when
 686 { $values
 687     { "seq" sequence } { "quot" quotation }
 688     { "before" object } { "after" object }
 689 }
 690 { $description "Cut the given sequence before the first element of " { $snippet "seq" } " that returns a truthy value when passed into " { $snippet "quot" } "." } ;
 691
 692 HELP: drop-while
 693 { $values
 694     { "seq" sequence } { "quot" quotation }
 695     { "tail-slice" object }
 696 }
 697 { $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." } ;
 698
 699 HELP: each-index-from
 700 { $values
 701     { "seq" sequence } { "quot" quotation } { "i" integer }
 702 }
 703 { $description "" } ;
 704
 705 HELP: each-integer-with-previous
 706 { $values
 707     { "n" integer } { "quot" quotation }
 708 }
 709 { $description "" } ;
 710
 711 HELP: each-prior
 712 { $values
 713     { "seq" sequence } { "quot" quotation }
 714 }
 715 { $description "" } ;
 716
 717 HELP: each-subseq
 718 { $values
 719     { "seq" sequence } { "quot" quotation }
 720 }
 721 { $description "" } ;
 722
 723 HELP: ensure-same-underlying
 724 { $values
 725     { "slice1" slice } { "slice2" slice }
 726 }
 727 { $description "" } ;
 728
 729 HELP: even-indices
 730 { $values
 731     { "seq" sequence }
 732     { "seq'" sequence }
 733 }
 734 { $description "Push a sequence containing the even-indexed elements in " { $snippet "seq" } "." } ;
 735
 736 HELP: evens
 737 { $class-description "The class of virtual sequences which contain the even-indexed elements of a given sequence." } ;
 738
 739 HELP: extract!
 740 { $values
 741     { "seq" sequence } { "quot" quotation }
 742 }
 743 { $description "" } ;
 744
 745 HELP: filter-all-subseqs
 746 { $values
 747     { "seq" sequence } { "quot" quotation }
 748 }
 749 { $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" } "." } ;
 750
 751 HELP: filter-all-subseqs-range
 752 { $values
 753     { "seq" sequence } { "range" object } { "quot" quotation }
 754 }
 755 { $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" } "." } ;
 756
 757 HELP: filter-index
 758 { $values
 759     { "seq" sequence } { "quot" quotation }
 760     { "seq'" sequence }
 761 }
 762 { $description "Perform a " { $link "filter" } " on the given sequence, with the index provided as an additional argument to " { $snippet "quot" } "." } ;
 763
 764 HELP: filter-index-as
 765 { $values
 766     { "seq" sequence } { "quot" quotation } { "exemplar" object }
 767     { "seq'" sequence }
 768 }
 769 { $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" } "." } ;
 770
 771 HELP: filter-length
 772 { $values
 773     { "seq" sequence } { "n" integer }
 774     { "seq'" sequence }
 775 }
 776 { $description "Push a sequence that contains all elements of " { $snippet "seq" } " that have length " { $snippet "n" } "." } ;
 777
 778 HELP: filter-map
 779 { $values
 780     { "seq" sequence } { "filter-quot" object } { "map-quot" 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" } "." } ;
 784
 785 HELP: filter-map-as
 786 { $values
 787     { "seq" sequence } { "filter-quot" object } { "map-quot" object } { "exemplar" object }
 788     { "newseq" sequence }
 789 }
 790 { $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" } "." } ;
 791
 792 HELP: find-last-index
 793 { $values
 794     { "seq" sequence } { "quot" quotation }
 795     { "i" integer } { "elt" object }
 796 }
 797 { $description "A simpler variant of " { $link "find-last-index-from" } ", with starting index set to 0." } ;
 798
 799 HELP: find-last-index-from
 800 { $values
 801     { "n" integer } { "seq" sequence } { "quot" quotation }
 802     { "i" integer } { "elt" object }
 803 }
 804 { $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." } ;
 805
 806 HELP: find-pred-loop
 807 { $values
 808     { "i" integer } { "n" integer } { "seq" sequence } { "quot" quotation }
 809     { "calc/f" object } { "i/f" { $maybe integer } } { "elt/f" object }
 810 }
 811 { $description "" } ;
 812
 813 HELP: harvest!
 814 { $values
 815     { "seq" sequence }
 816     { "newseq" sequence }
 817 }
 818 { $description "Outputs a new sequence with all empty sequences removed. Modifies " { $snippet "seq" } "in place." } ;
 819
 820 HELP: harvest-as
 821 { $values
 822     { "seq" sequence } { "exemplar" object }
 823     { "newseq" sequence }
 824 }
 825 { $description "Outputs a new sequence with all empty sequences removed. Resulting sequence is the same class as " { $snippet "exemplar" } "." } ;
 826
 827 HELP: head*-as
 828 { $values
 829     { "seq" sequence } { "n" integer } { "exemplar" object }
 830     { "seq'" sequence }
 831 }
 832 { $description "A version of " { $link "head*" } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
 833
 834 HELP: head-as
 835 { $values
 836     { "seq" sequence } { "n" integer } { "exemplar" object }
 837     { "seq'" sequence }
 838 }
 839 { $description "A version of " { $link "head" } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
 840
 841 HELP: heap>pairs
 842 { $values
 843     { "heap" object }
 844     { "pairs" object }
 845 }
 846 { $description "Collect the pairs inside a heap into a sequence. Ordering of the sequence is based on the ordering of the heap." } ;
 847
 848 HELP: index-selector
 849 { $values
 850     { "quot" quotation }
 851     { "selector" object } { "accum" object }
 852 }
 853 { $description "" } ;
 854
 855 HELP: index-selector-as
 856 { $values
 857     { "quot" quotation } { "exemplar" object }
 858     { "selector" object } { "accum" object }
 859 }
 860 { $description "" } ;
 861
 862 HELP: infimum-by*
 863 { $values
 864     { "seq" sequence } { "quot" quotation }
 865     { "i" integer } { "elt" object }
 866 }
 867 { $description "A variant of " { $link "infimum-by" } " that pushes the index of the least element along with the least element." } ;
 868
 869 HELP: insert-nth!
 870 { $values
 871     { "elt" object } { "n" integer } { "seq" sequence }
 872 }
 873 { $description "A variant of " { $link "insert-nth" } " that modifies " { $snippet "seq" } " in place." } ;
 874
 875 HELP: interleaved
 876 { $values
 877     { "seq" sequence } { "glue" object }
 878     { "newseq" sequence }
 879 }
 880 { $description "Insert " { $link "glue" } " between every pair of elements in " { $snippet "seq" } "." } ;
 881
 882 HELP: interleaved-as
 883 { $values
 884     { "seq" sequence } { "glue" object } { "exemplar" object }
 885     { "newseq" sequence }
 886 }
 887 { $description "Insert " { $link "glue" } " between every pair of elements in " { $snippet "seq" } ". Resulting sequence will be the same class as " { $snippet "exemplar" } "." } ;
 888
 889 HELP: iterate-heap-while
 890 { $values
 891     { "heap" object } { "quot1" quotation } { "quot2" quotation }
 892     { "obj/f" { $maybe object } } { "loop?" object }
 893 }
 894 { $description "" } ;
 895
 896 HELP: last=
 897 { $values
 898     { "seq" sequence } { "elt" object }
 899     { "?" boolean }
 900 }
 901 { $description "Check if the last element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
 902
 903 HELP: last?
 904 { $values
 905     { "seq" sequence } { "quot" quotation }
 906     { "?" boolean }
 907 }
 908 { $description "Check if the last element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
 909
 910 HELP: longest-subseq
 911 { $values
 912     { "seq1" sequence } { "seq2" sequence }
 913     { "subseq" object }
 914 }
 915 { $description "Pushes the longest subsequence of " { $snippet "seq" } "." } ;
 916
 917 HELP: map-concat
 918 { $values
 919     { "seq" sequence } { "quot" quotation }
 920     { "newseq" sequence }
 921 }
 922 { $description "Perform a " { $link "map" } " on the given sequence with " { $snippet "quot" } ", then perform a " { $link "concat" } " on the result." } ;
 923
 924 HELP: map-concat-as
 925 { $values
 926     { "seq" sequence } { "quot" quotation } { "exemplar" object }
 927     { "newseq" sequence }
 928 }
 929 { $description "A version of " { $link "map-concat" } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 930
 931 HELP: map-filter
 932 { $values
 933     { "seq" sequence } { "map-quot" object } { "filter-quot" object }
 934     { "subseq" object }
 935 }
 936 { $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" } "." } ;
 937
 938 HELP: map-filter-as
 939 { $values
 940     { "seq" sequence } { "map-quot" object } { "filter-quot" object } { "exemplar" object }
 941     { "subseq" object }
 942 }
 943 { $description "A version of " { $link "map-filter" } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 944
 945 HELP: map-find-index
 946 { $values
 947     { "seq" sequence } { "quot" quotation }
 948     { "result" object } { "i" integer } { "elt" object }
 949 }
 950 { $description "A version of " { $link "map-find" } " where the index of the found element, if any, is returned." } ;
 951
 952 HELP: map-find-last-index
 953 { $values
 954     { "seq" sequence } { "quot" quotation }
 955     { "result" object } { "i" integer } { "elt" object }
 956 }
 957 { $description "A version of " { $link "map-find-index" } " where the index of the found element, if any, is returned." } ;
 958
 959 HELP: map-from
 960 { $values
 961     { "seq" sequence } { "quot" quotation } { "i" integer }
 962     { "newseq" sequence }
 963 }
 964 { $description "A version of " { $link "map" } " that maps the slice of " { $snippet "seq" } " beginning at index " { $snippet "i" } "." } ;
 965
 966 HELP: map-from-as
 967 { $values
 968     { "seq" sequence } { "quot" quotation } { "i" integer } { "exemplar" object }
 969     { "newseq" sequence }
 970 }
 971 { $description "A version of " { $link "map-from" } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
 972
 973 HELP: map-harvest
 974 { $values
 975     { "seq" sequence } { "quot" quotation }
 976     { "newseq" sequence }
 977 }
 978 { $description "A version of " { $link "map" } " with all empty sequences removed from the result." } ;
 979
 980 HELP: map-if
 981 { $values
 982     { "seq" sequence } { "if-quot" object } { "map-quot" object }
 983     { "newseq" sequence }
 984 }
 985 { $description "A version of " { $link "map" } " where " { $snippet "map-quot" } " is applied only if " { $snippet "if-quot" } " returns true for a given element." } ;
 986
 987 HELP: map-index!
 988 { $values
 989     { "seq" sequence } { "quot" quotation }
 990 }
 991 { $description "A version of " { $link "map-index" } " which modifies " { $snippet "seq" } " in place." } ;
 992
 993 HELP: map-integers-with
 994 { $values
 995     { "len" object } { "quot" quotation } { "exemplar" object }
 996     { "newseq" sequence }
 997 }
 998 { $description "" } ;
 999
1000 HELP: map-like
1001 { $values
1002     { "seq" sequence } { "exemplar" object }
1003     { "seq'" sequence }
1004 }
1005 { $description "" } ;
1006
1007 HELP: map-prior
1008 { $values
1009     { "seq" sequence } { "quot" quotation }
1010     { "seq'" sequence }
1011 }
1012 { $description "" } ;
1013
1014 HELP: map-prior-as
1015 { $values
1016     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1017     { "seq'" sequence }
1018 }
1019 { $description "" } ;
1020
1021 HELP: map-product
1022 { $values
1023     { "seq" sequence } { "quot" quotation }
1024     { "n" integer }
1025 }
1026 { $description "Like " { $link "map product" } ", but without creating an intermediate sequence." } ;
1027
1028 HELP: map-sift
1029 { $values
1030     { "seq" sequence } { "quot" quotation }
1031     { "newseq" sequence }
1032 }
1033 { $description "A version of " { $link "map" } " with all instances of " { $link "f" } " removed from the result." } ;
1034
1035 HELP: map-with-previous
1036 { $values
1037     { "seq" sequence } { "quot" quotation }
1038     { "newseq" sequence }
1039 }
1040 { $description "" } ;
1041
1042 HELP: map-with-previous-as
1043 { $values
1044     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1045     { "newseq" sequence }
1046 }
1047 { $description "" } ;
1048
1049 HELP: map-zip-swap
1050 { $values
1051     { "quot" quotation }
1052     { "alist" "an array of key/value pairs" }
1053 }
1054 { $description "" } ;
1055
1056 HELP: max-subarray-sum
1057 { $values
1058     { "seq" sequence }
1059     { "sum" object }
1060 }
1061 { $description "Output the maximum subarray sum of the sequence." } ;
1062
1063 HELP: merge-slices
1064 { $values
1065     { "slice1" slice } { "slice2" slice }
1066     { "slice/*" object }
1067 }
1068 { $description "" } ;
1069
1070 HELP: nth*
1071 { $values
1072     { "n" integer } { "seq" sequence }
1073     { "elt" object }
1074 }
1075 { $description "Pushes the nth element of the sequence if it exists, otherwise pushes sequence length - 1." } ;
1076
1077 HELP: nth=
1078 { $values
1079     { "n" integer } { "seq" sequence } { "elt" object }
1080     { "?" boolean }
1081 }
1082 { $description "Check if the nth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
1083
1084 HELP: nth?
1085 { $values
1086     { "n" integer } { "seq" sequence } { "quot" quotation }
1087     { "?" boolean }
1088 }
1089 { $description "Check if the nth element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
1090
1091 HELP: odd-indices
1092 { $values
1093     { "seq" sequence }
1094     { "seq'" sequence }
1095 }
1096 { $description "Push a sequence containing the odd-indexed elements in " { $snippet "seq" } "." } ;
1097
1098 HELP: odds
1099 { $class-description "The class of virtual sequences which contain the odd-indexed elements of a given sequence." } ;
1100
1101 HELP: one?
1102 { $values
1103     { "seq" sequence } { "quot" quotation }
1104     { "?" boolean }
1105 }
1106 { $description "" } ;
1107
1108 HELP: ordered-slices-overlap?
1109 { $values
1110     { "slice-lt" object } { "slice-gt" object }
1111     { "?" boolean }
1112 }
1113 { $description "" } ;
1114
1115 HELP: ordered-slices-range
1116 { $values
1117     { "slice-lt" object } { "slice-gt" object }
1118     { "to" integer } { "from" integer }
1119 }
1120 { $description "" } ;
1121
1122 HELP: ordered-slices-touch?
1123 { $values
1124     { "slice-lt" object } { "slice-gt" object }
1125     { "?" boolean }
1126 }
1127 { $description "" } ;
1128
1129 HELP: pad-longest
1130 { $values
1131     { "seq1" sequence } { "seq2" sequence } { "elt" object }
1132 }
1133 { $description "Perform " { $link "pad-tail" } " on both sequences, padding with " { $snippet "elt" } " to the longest length between the two." } ;
1134
1135 HELP: prepend-lines-with-spaces
1136 { $values
1137     { "str" string }
1138     { "str'" string }
1139 }
1140 { $description "Prepend four spaces to each line in " { $snippet "str" } "." } ;
1141
1142 HELP: push-if*
1143 { $values
1144     { "elt" object } { "quot" quotation } { "accum" object }
1145 }
1146 { $description "" } ;
1147
1148 HELP: push-if-index
1149 { $values
1150     { "elt" object } { "i" integer } { "quot" quotation } { "accum" object }
1151 }
1152 { $description "" } ;
1153
1154 HELP: reduce-from
1155 { $values
1156     { "seq" sequence } { "identity" object } { "quot" quotation } { "i" integer }
1157     { "result" object }
1158 }
1159 { $description "" } ;
1160
1161 HELP: remove-first
1162 { $values
1163     { "obj" object } { "seq" sequence }
1164     { "seq'" sequence }
1165 }
1166 { $description "Remove the first occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1167
1168 HELP: remove-first!
1169 { $values
1170     { "obj" object } { "seq" sequence }
1171 }
1172 { $description "A version of " { $link "remove-first" } " that modifies " { $snippet "seq" } " in place." } ;
1173
1174 HELP: remove-last
1175 { $values
1176     { "obj" object } { "seq" sequence }
1177     { "seq'" sequence }
1178 }
1179 { $description "Remove the last occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1180
1181 HELP: remove-last!
1182 { $values
1183     { "obj" object } { "seq" sequence }
1184 }
1185 { $description "A version of " { $link "remove-last" } " that modifies " { $snippet "seq" } " in place." } ;
1186
1187 HELP: replicate-into
1188 { $values
1189     { "seq" sequence } { "quot" quotation }
1190 }
1191 { $description "" } ;
1192
1193 HELP: reverse-as
1194 { $values
1195     { "seq" sequence } { "exemplar" object }
1196     { "newseq" sequence }
1197 }
1198 { $description "A version of " { $link "reverse" } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
1199
1200 HELP: rotate
1201 { $values
1202     { "seq" sequence } { "n" integer }
1203     { "seq'" sequence }
1204 }
1205 { $description "Move the first " { $snippet "n" } " elements of " { $snippet "seq" } " to the end." } ;
1206
1207 HELP: rotate!
1208 { $values
1209     { "seq" sequence } { "n" integer }
1210 }
1211 { $description "A version of " { $link "rotate!" } " that modifies " { $snippet "seq" } " in place." } ;
1212
1213 HELP: round-robin
1214 { $values
1215     { "seq" sequence }
1216     { "newseq" sequence }
1217 }
1218 { $description "List all elements of " { $snippet "seq" } " in column-major order." } ;
1219
1220 HELP: safe-subseq
1221 { $values
1222     { "from" integer } { "to" integer } { "seq" sequence }
1223     { "subseq" object }
1224 }
1225 { $description "A safe version of " { $link "subseq" } "." } ;
1226
1227 HELP: selector*
1228 { $values
1229     { "quot" quotation }
1230     { "selector" object } { "accum" object }
1231 }
1232 { $description "" } ;
1233
1234 HELP: selector-as*
1235 { $values
1236     { "quot" quotation } { "exemplar" object }
1237     { "selector" object } { "accum" object }
1238 }
1239 { $description "" } ;
1240
1241 HELP: sequence-index-operator-last
1242 { $values
1243     { "n" integer } { "seq" sequence } { "quot" quotation }
1244     { "quot'" quotation }
1245 }
1246 { $description "" } ;
1247
1248 HELP: sequence>slice
1249 { $values
1250     { "sequence" sequence }
1251     { "slice" slice }
1252 }
1253 { $description "Create a virtual sequence that represents the given sequence." } ;
1254
1255 HELP: set-nths
1256 { $values
1257     { "value" object } { "indices" object } { "seq" sequence }
1258 }
1259 { $description "Set the elements at all given indices to " { $snippet "value" } ". modifies " { $snippet "seq" } " in place." } ;
1260
1261 HELP: set-nths-unsafe
1262 { $values
1263     { "value" object } { "indices" object } { "seq" sequence }
1264 }
1265 { $description "Unsafe version of " { $link "set-nths" } } ;
1266
1267 HELP: shorten*
1268 { $values
1269     { "vector" object } { "n" integer }
1270     { "seq" sequence }
1271 }
1272 { $description "" } ;
1273
1274 HELP: sift!
1275 { $values
1276     { "seq" sequence }
1277     { "newseq" sequence }
1278 }
1279 { $description "" } ;
1280
1281 HELP: sift-as
1282 { $values
1283     { "seq" sequence } { "exemplar" object }
1284     { "newseq" sequence }
1285 }
1286 { $description "" } ;
1287
1288 HELP: slice-order-by-from
1289 { $values
1290     { "slice1" slice } { "slice2" slice }
1291     { "slice-lt" object } { "slice-gt" object }
1292 }
1293 { $description "" } ;
1294
1295 HELP: slice-when
1296 { $values
1297     { "seq" sequence } { "quot" quotation }
1298     { "seq'" sequence }
1299 }
1300 { $description "" } ;
1301
1302 HELP: slices-don't-touch
1303 { $values
1304     { "slice1" slice } { "slice2" slice }
1305 }
1306 { $description "Throws a " { $link slices-don't-touch } " error." }
1307 { $error-description "" } ;
1308
1309 HELP: slices-overlap?
1310 { $values
1311     { "slice1" slice } { "slice2" slice }
1312     { "?" boolean }
1313 }
1314 { $description "" } ;
1315
1316 HELP: slices-touch?
1317 { $values
1318     { "slice1" slice } { "slice2" slice }
1319     { "?" boolean }
1320 }
1321 { $description "" } ;
1322
1323 HELP: slurp-heap-while-map
1324 { $values
1325     { "heap" object } { "quot1" quotation } { "quot2" quotation }
1326     { "seq" sequence }
1327 }
1328 { $description "" } ;
1329
1330 HELP: span-slices
1331 { $values
1332     { "slice1" slice } { "slice2" slice }
1333     { "slice" slice }
1334 }
1335 { $description "Create a virtual sequence spanning the length covered by " { $snippet "slice1" } " and " { $snippet "slice2" } ". Slices must refer to the same sequence." } ;
1336
1337 HELP: step-slice
1338 { $class-description "" } ;
1339
1340 HELP: supremum-by*
1341 { $values
1342     { "seq" sequence } { "quot" quotation }
1343     { "i" integer } { "elt" object }
1344 }
1345 { $description "" } ;
1346
1347 HELP: tail*-as
1348 { $values
1349     { "seq" sequence } { "n" integer } { "exemplar" object }
1350     { "seq'" sequence }
1351 }
1352 { $description "" } ;
1353
1354 HELP: tail-as
1355 { $values
1356     { "seq" sequence } { "n" integer } { "exemplar" object }
1357     { "seq'" sequence }
1358 }
1359 { $description "" } ;
1360
1361 HELP: take-while
1362 { $values
1363     { "seq" sequence } { "quot" quotation }
1364     { "head-slice" object }
1365 }
1366 { $description "" } ;
1367
1368 HELP: trim-as
1369 { $values
1370     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1371     { "newseq" sequence }
1372 }
1373 { $description "" } ;
1374
1375 HELP: underlying-mismatch
1376 { $values
1377     { "slice1" slice } { "slice2" slice }
1378 }
1379 { $description "Throws an " { $link underlying-mismatch } " error." }
1380 { $error-description "" } ;
1381
1382 HELP: unordered-slices-overlap?
1383 { $values
1384     { "slice1" slice } { "slice2" slice }
1385     { "?" boolean }
1386 }
1387 { $description "" } ;
1388
1389 HELP: unordered-slices-range
1390 { $values
1391     { "slice1" slice } { "slice2" slice }
1392     { "to" integer } { "from" integer }
1393 }
1394 { $description "" } ;
1395
1396 HELP: unordered-slices-touch?
1397 { $values
1398     { "slice1" slice } { "slice2" slice }
1399     { "?" boolean }
1400 }
1401 { $description "" } ;
1402
1403 HELP: until-empty
1404 { $values
1405     { "seq" sequence } { "quot" quotation }
1406 }
1407 { $description "" } ;
1408
1409 HELP: virtual-zip-index
1410 { $class-description "" } ;
1411
1412 HELP: with-string-lines
1413 { $values
1414     { "str" string } { "quot" quotation }
1415     { "str'" string }
1416 }
1417 { $description "" } ;