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: 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 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 } { "i" 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 } { "i" 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 " { $link 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*
1052 { $values
1053     { "n" integer } { "seq" sequence }
1054     { "elt" object }
1055 }
1056 { $description "Pushes the nth element of the sequence if it exists, otherwise pushes sequence length - 1." } ;
1057
1058 HELP: nth=
1059 { $values
1060     { "n" integer } { "seq" sequence } { "elt" object }
1061     { "?" boolean }
1062 }
1063 { $description "Check if the nth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
1064
1065 HELP: nth?
1066 { $values
1067     { "n" integer } { "seq" sequence } { "quot" quotation }
1068     { "?" boolean }
1069 }
1070 { $description "Check if the nth element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
1071
1072 HELP: odd-indices
1073 { $values
1074     { "seq" sequence }
1075     { "seq'" sequence }
1076 }
1077 { $description "Push a sequence containing the odd-indexed elements in " { $snippet "seq" } "." } ;
1078
1079 HELP: odds
1080 { $class-description "The class of virtual sequences which contain the odd-indexed elements of a given sequence." } ;
1081
1082 HELP: one?
1083 { $values
1084     { "seq" sequence } { "quot" quotation }
1085     { "?" boolean }
1086 } ;
1087
1088 HELP: ordered-slices-overlap?
1089 { $values
1090     { "slice-lt" object } { "slice-gt" object }
1091     { "?" boolean }
1092 } ;
1093
1094 HELP: ordered-slices-range
1095 { $values
1096     { "slice-lt" object } { "slice-gt" object }
1097     { "to" integer } { "from" integer }
1098 } ;
1099
1100 HELP: ordered-slices-touch?
1101 { $values
1102     { "slice-lt" object } { "slice-gt" object }
1103     { "?" boolean }
1104 } ;
1105
1106 HELP: pad-longest
1107 { $values
1108     { "seq1" sequence } { "seq2" sequence } { "elt" object }
1109 }
1110 { $description "Perform " { $link pad-tail } " on both sequences, padding with " { $snippet "elt" } " to the longest length between the two." } ;
1111
1112 HELP: prepend-lines-with-spaces
1113 { $values
1114     { "str" string }
1115     { "str'" string }
1116 }
1117 { $description "Prepend four spaces to each line in " { $snippet "str" } "." } ;
1118
1119 HELP: push-if*
1120 { $values
1121     { "elt" object } { "quot" quotation } { "accum" object }
1122 } ;
1123
1124 HELP: push-if-index
1125 { $values
1126     { "elt" object } { "i" integer } { "quot" quotation } { "accum" object }
1127 } ;
1128
1129 HELP: reduce-from
1130 { $values
1131     { "seq" sequence } { "identity" object } { "quot" quotation } { "i" integer }
1132     { "result" object }
1133 } ;
1134
1135 HELP: remove-first
1136 { $values
1137     { "obj" object } { "seq" sequence }
1138     { "seq'" sequence }
1139 }
1140 { $description "Remove the first occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1141
1142 HELP: remove-first!
1143 { $values
1144     { "obj" object } { "seq" sequence }
1145 }
1146 { $description "A version of " { $link remove-first } " that modifies " { $snippet "seq" } " in place." } ;
1147
1148 HELP: remove-last
1149 { $values
1150     { "obj" object } { "seq" sequence }
1151     { "seq'" sequence }
1152 }
1153 { $description "Remove the last occurrence of " { $snippet "obj" } " in  " { $snippet "seq" } "." } ;
1154
1155 HELP: remove-last!
1156 { $values
1157     { "obj" object } { "seq" sequence }
1158 }
1159 { $description "A version of " { $link remove-last } " that modifies " { $snippet "seq" } " in place." } ;
1160
1161 HELP: replicate-into
1162 { $values
1163     { "seq" sequence } { "quot" quotation }
1164 } ;
1165
1166 HELP: reverse-as
1167 { $values
1168     { "seq" sequence } { "exemplar" object }
1169     { "newseq" sequence }
1170 }
1171 { $description "A version of " { $link reverse } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
1172
1173 HELP: rotate
1174 { $values
1175     { "seq" sequence } { "n" integer }
1176     { "seq'" sequence }
1177 }
1178 { $description "Move the first " { $snippet "n" } " elements of " { $snippet "seq" } " to the end." } ;
1179
1180 HELP: rotate!
1181 { $values
1182     { "seq" sequence } { "n" integer }
1183 }
1184 { $description "A version of " { $link rotate } " that modifies " { $snippet "seq" } " in place." } ;
1185
1186 HELP: round-robin
1187 { $values
1188     { "seq" sequence }
1189     { "newseq" sequence }
1190 }
1191 { $description "List all elements of " { $snippet "seq" } " in column-major order." } ;
1192
1193 HELP: safe-subseq
1194 { $values
1195     { "from" integer } { "to" integer } { "seq" sequence }
1196     { "subseq" object }
1197 }
1198 { $description "A safe version of " { $link subseq } "." } ;
1199
1200 HELP: selector*
1201 { $values
1202     { "quot" quotation }
1203     { "selector" object } { "accum" object }
1204 } ;
1205
1206 HELP: selector-as*
1207 { $values
1208     { "quot" quotation } { "exemplar" object }
1209     { "selector" object } { "accum" object }
1210 } ;
1211
1212 HELP: sequence-index-operator-last
1213 { $values
1214     { "n" integer } { "seq" sequence } { "quot" quotation }
1215     { "quot'" quotation }
1216 } ;
1217
1218 HELP: sequence>slice
1219 { $values
1220     { "sequence" sequence }
1221     { "slice" slice }
1222 }
1223 { $description "Create a virtual sequence that represents the given sequence." } ;
1224
1225 HELP: set-nths
1226 { $values
1227     { "value" object } { "indices" object } { "seq" sequence }
1228 }
1229 { $description "Set the elements at all given indices to " { $snippet "value" } ". modifies " { $snippet "seq" } " in place." } ;
1230
1231 HELP: set-nths-unsafe
1232 { $values
1233     { "value" object } { "indices" object } { "seq" sequence }
1234 }
1235 { $description "Unsafe version of " { $link set-nths } } ;
1236
1237 HELP: shorten*
1238 { $values
1239     { "vector" object } { "n" integer }
1240     { "seq" sequence }
1241 } ;
1242
1243 HELP: sift!
1244 { $values
1245     { "seq" sequence }
1246     { "newseq" sequence }
1247 } ;
1248
1249 HELP: sift-as
1250 { $values
1251     { "seq" sequence } { "exemplar" object }
1252     { "newseq" sequence }
1253 } ;
1254
1255 HELP: slice-order-by-from
1256 { $values
1257     { "slice1" slice } { "slice2" slice }
1258     { "slice-lt" object } { "slice-gt" object }
1259 } ;
1260
1261 HELP: slice-when
1262 { $values
1263     { "seq" sequence } { "quot" quotation }
1264     { "seq'" sequence }
1265 } ;
1266
1267 HELP: slices-don't-touch
1268 { $values
1269     { "slice1" slice } { "slice2" slice }
1270 }
1271 { $description "Throws a " { $link slices-don't-touch } " error." }
1272 { $error-description "" } ;
1273
1274 HELP: slices-overlap?
1275 { $values
1276     { "slice1" slice } { "slice2" slice }
1277     { "?" boolean }
1278 } ;
1279
1280 HELP: slices-touch?
1281 { $values
1282     { "slice1" slice } { "slice2" slice }
1283     { "?" boolean }
1284 } ;
1285
1286 HELP: slurp-heap-while-map
1287 { $values
1288     { "heap" object } { "quot1" quotation } { "quot2" quotation }
1289     { "seq" sequence }
1290 } ;
1291
1292 HELP: span-slices
1293 { $values
1294     { "slice1" slice } { "slice2" slice }
1295     { "slice" slice }
1296 }
1297 { $description "Create a virtual sequence spanning the length covered by " { $snippet "slice1" } " and " { $snippet "slice2" } ". Slices must refer to the same sequence." } ;
1298
1299 HELP: supremum-by*
1300 { $values
1301     { "seq" sequence } { "quot" quotation }
1302     { "i" integer } { "elt" object }
1303 } ;
1304
1305 HELP: tail*-as
1306 { $values
1307     { "seq" sequence } { "n" integer } { "exemplar" object }
1308     { "seq'" sequence }
1309 } ;
1310
1311 HELP: tail-as
1312 { $values
1313     { "seq" sequence } { "n" integer } { "exemplar" object }
1314     { "seq'" sequence }
1315 } ;
1316
1317 HELP: take-while
1318 { $values
1319     { "seq" sequence } { "quot" quotation }
1320     { "head-slice" object }
1321 } ;
1322
1323 HELP: trim-as
1324 { $values
1325     { "seq" sequence } { "quot" quotation } { "exemplar" object }
1326     { "newseq" sequence }
1327 } ;
1328
1329 HELP: underlying-mismatch
1330 { $values
1331     { "slice1" slice } { "slice2" slice }
1332 }
1333 { $description "Throws an " { $link underlying-mismatch } " error." }
1334 { $error-description "" } ;
1335
1336 HELP: unordered-slices-overlap?
1337 { $values
1338     { "slice1" slice } { "slice2" slice }
1339     { "?" boolean }
1340 } ;
1341
1342 HELP: unordered-slices-range
1343 { $values
1344     { "slice1" slice } { "slice2" slice }
1345     { "to" integer } { "from" integer }
1346 } ;
1347
1348 HELP: unordered-slices-touch?
1349 { $values
1350     { "slice1" slice } { "slice2" slice }
1351     { "?" boolean }
1352 } ;
1353
1354 HELP: until-empty
1355 { $values
1356     { "seq" sequence } { "quot" quotation }
1357 } ;
1358
1359 HELP: with-string-lines
1360 { $values
1361     { "str" string } { "quot" quotation }
1362     { "str'" string }
1363 } ;