extra/sequences/extras/extras-docs.factor

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