1 USING: arrays help.markup help.syntax kernel math multiline
2 quotations sequences vectors assocs strings ;
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-" } } ;
12 { "seq/f" { $maybe sequence } }
13 { "elt/f" { $maybe object } }
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 } "." }
17 { $example "USING: prettyprint sequences.extras ;"
18 "{ 1 f 3 2 } ?maximum ."
24 { "seq/f" { $maybe sequence } }
25 { "elt/f" { $maybe object } }
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 } "." }
29 { $example "USING: prettyprint sequences.extras ;"
30 "{ 1 f 3 2 } ?minimum ."
34 { ?maximum ?minimum } related-words
40 { "quot" { $quotation ( ... elt1 elt2 -- ... ? ) } }
42 { $description "Efficiently counts how many pairwise elements of " { $snippet "seq1" } " and " { $snippet "seq2" } " that the predicate quotation matches." }
44 { $example "USING: kernel prettyprint sequences.extras ;" "{ 1 2 3 } { 3 2 1 } [ = ] 2count ." "1" } }
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 } ;
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! } ;
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 } ;
75 { "quot" { $quotation ( ... elt -- ... ? ) } }
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" } } ;
83 { "quot" { $quotation ( ... elt -- ... ? ) } }
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" } "." }
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 \"" } } ;
95 { "quot" { $quotation ( ... elt -- ... ? ) } }
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 }
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\"" } } ;
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> } ;
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." } ;
123 { $description "Checks whether the first element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
128 { "quot" { $quotation ( ... elt -- ... ? ) } }
130 { $description "Tests whether the first element of " { $snippet "seq" } " satisfies the provided predicate." } ;
137 { $description "Checks whether the fourth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
142 { "quot" { $quotation ( ... elt -- ... ? ) } }
144 { $description "Tests whether the fourth element of " { $snippet "seq" } " satisfies the provided predicate." } ;
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> } ;
153 { $values { "seq" sequence } { "accum" sequence } }
154 { $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ;
161 { $description "Checks whether the second element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
166 { "quot" { $quotation ( ... elt -- ... ? ) } }
168 { $description "Tests whether the second element of " { $snippet "seq" } " satisfies the provided predicate." } ;
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" } "." }
176 "Using a negative relative index:"
177 { $example "USING: prettyprint sequences.extras ; 2 -1 \"abcdefg\" subseq* ."
180 "Using optional indices:"
181 { $example "USING: prettyprint sequences.extras ; f -4 \"abcdefg\" subseq* ."
184 "Using larger-than-necessary indices:"
185 { $example "USING: prettyprint sequences.extras ; 0 10 \"abcdefg\" subseq* ."
188 "Trimming from either end of the sequence."
189 { $example "USING: prettyprint sequences.extras ; 1 -1 \"abcdefg\" subseq* ."
199 { $description "Checks whether the third element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
204 { "quot" { $quotation ( ... elt -- ... ? ) } }
206 { $description "Tests whether the third element of " { $snippet "seq" } " satisfies the provided predicate." } ;
210 { "newseq" 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 } ;
219 { "seq" sequence } { "subseq" sequence } { "indices" sequence } }
220 { $description "Outputs the starting indices of the non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
222 { $example "USING: prettyprint sequences.extras ;"
223 "\"ABABA\" \"ABA\" start-all ."
226 { $example "USING: prettyprint sequences.extras ;"
227 "\"ABAABA\" \"ABA\" start-all ."
234 { "seq" sequence } { "subseq" sequence } { "indices" sequence } }
235 { $description "Outputs the starting indices of the possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
237 { $example "USING: prettyprint sequences.extras ;"
238 "\"ABABA\" \"ABA\" start-all* ."
243 { $values { "seq" sequence } { "n" integer } }
244 { $description "Outputs the index of the element with the largest value in " { $snippet "seq" } "." } ;
247 { $values { "seq" sequence } { "n" integer } }
248 { $description "Outputs the index of the element with the smallest value in " { $snippet "seq" } "." } ;
250 { arg-max arg-min } related-words
254 { "seq" sequence } { "subseq" sequence } { "n" integer } }
255 { $description "Outputs the number of non-overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
257 { $example "USING: prettyprint sequences.extras ;"
258 "\"ABABA\" \"ABA\" count-subseq ."
265 { "seq" sequence } { "subseq" sequence } { "n" integer } }
266 { $description "Outputs the number of possibly overlapping occurrences of " { $snippet "subseq" } " in " { $snippet "seq" } "." }
268 { $example "USING: prettyprint sequences.extras ;"
269 "\"ABABA\" \"ABA\" count-subseq* ."
273 { start-all start-all* count-subseq count-subseq* } related-words
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" } "." }
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 ."
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." }
298 { $example "USING: sequences.extras prettyprint io.encodings.binary"
299 "random random.mersenne-twister kernel math ;"
300 "123 <mersenne-twister> ["
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." }
316 { $example "USING: sequences.extras prettyprint io.encodings.binary"
317 "random random.mersenne-twister kernel math ;"
318 "123 <mersenne-twister> ["
330 { "quot" quotation } { "exemplar" object }
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" } "." }
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 ."
346 { "quot" quotation } { "exemplar" object }
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." }
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> ["
358 " ] V{ } loop>sequence*"
364 HELP: loop>sequence**
366 { "quot" quotation } { "exemplar" object }
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." }
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> ["
378 " ] V{ } loop>sequence**"
385 loop>array loop>array* loop>array**
386 loop>sequence loop>sequence* loop>sequence**
387 zero-loop>array zero-loop>sequence
390 HELP: zero-loop>array
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" } "." }
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" }]]
404 HELP: zero-loop>sequence
406 { "quot" quotation } { "exemplar" object }
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" } "." }
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" }]]
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. }
422 [=[ USING: math kernel sequences.extras prettyprint ;
423 { 4 5 6 } [ sq ] [ 20 > ] find-pred [ . ] tri@
428 HELP: (collect-with-previous)
430 { "quot" quotation } { "into" object }
431 { "quot'" quotation }
434 HELP: (each-integer-with-previous)
436 { "prev" object } { "i" integer } { "n" integer } { "quot" quotation }
441 { "seq" sequence } { "subseq" object } { "increment" object }
447 { "seq1" sequence } { "seq2" sequence } { "quot" quotation } { "into" object }
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" } "." } ;
453 { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
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." } ;
460 { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
462 { $description "Applies quotation to all pairs of elements from " { $snippet "seq1" } " and " { $snippet "seq2" } ". Order is the same as a nested for loop." } ;
466 { "seq1" sequence } { "seq2" sequence } { "quot" quotation }
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." } ;
473 { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation } { "i" integer }
478 { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "map-quot" object } { "reduce-quot" object }
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" } "." } ;
485 { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
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." } ;
491 { "seq1" sequence } { "seq2" sequence } { "seq3" sequence } { "quot" quotation }
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." } ;
498 { "from/f" { $maybe integer } } { "to/f" { $maybe integer } } { "step" object } { "seq" sequence }
499 { "step-slice" slice }
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" } "."
503 "If " { $link f } "is given in place of " { $snippet "from/f" } ", it is taken as 0."
505 "If " { $link f } "is given in place of " { $snippet "to/f" } ", it is taken as the length of " { $snippet "seq" } "." }
511 { "virtual-zip-index" object }
513 { $description "Outputs a new virtual sequence which pairs the elements of " { $snippet "seq" } " with their 0-based indices." } ;
520 { $description "Surrounds each element of " { $snippet "seq" } " in quotes and joins the sequence with commas." } ;
524 { "from/f" { $maybe integer } } { "to/f" { $maybe integer } } { "sequence" sequence }
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." } ;
532 { "first/f" object } { "second/f" object }
534 { $description "Pushes the first two elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
539 { "first/f" object } { "second/f" object } { "third/f" object }
541 { $description "Pushes the first three elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
546 { "first/f" object } { "second/f" object } { "third/f" object } { "fourth/f" object }
548 { $description "Pushes the first four elements of " { $snippet "seq" } ". Pushes " { $snippet "f" } " for missing elements." } ;
550 HELP: ?heap-pop-value>array
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." } ;
559 { "slice1/f" { $maybe slice } } { "slice2/f" { $maybe slice } }
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." } ;
566 { "seq" sequence } { "quot" quotation }
567 { "seq/newseq" object }
569 { $description "Similar to " { $link trim } ", but sequences that do not require trimming are left as is." } ;
573 { "seq" sequence } { "quot" quotation }
574 { "seq/newseq" object }
576 { $description "Similar to " { $link trim-head } ", but sequences that do not require trimming are left as is." } ;
580 { "seq" sequence } { "quot" quotation }
581 { "seq/newseq" object }
583 { $description "Similar to " { $link trim-tail } ", but sequences that do not require trimming are left as is." } ;
590 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the longest length." } ;
597 { $description "Pushes a sequence containing all the rotations of " { $snippet "seq" } ", including the original array." } ;
604 { $description "Pushes a sequence containing all of the sequences in " { $snippet "seqs" } " that have the shortest length." } ;
611 { $description "Pushes a sequence containing all subsequences in " { $snippet "seq" } " excluding the empty sequence." } ;
616 { "appender" quotation } { "accum" vector }
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." } ;
622 { "quot" quotation } { "exemplar" object }
623 { "appender" object } { "accum" object }
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." } ;
632 { $description "Given a sequence " { $snippet "seq" } ", push a sequence of indices that when indexed into, sort the given sequence." } ;
636 { "seq" sequence } { "quot" quotation }
639 { $description "Push a sequence of all indices in " { $snippet "seq" } " where " { $snippet "quot" } "applied to the element at each index is true." } ;
643 { "quot" quotation } { "alist" "an array of key/value pairs" }
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." } ;
649 { "seq" sequence } { "quot" quotation }
651 { $description "Applies " { $snippet "quot" } " to the last element of a sequence, modifying it in place." } ;
653 HELP: change-last-unsafe
655 { "seq" sequence } { "quot" quotation }
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." } ;
661 { "indices" object } { "seq" sequence } { "quot" quotation }
663 { $description "Applies " { $snippet "quot" } " to the locations present in " { $snippet "indices" } " in sequence " { $snippet "seq" } ", modifying it in place." } ;
665 HELP: collect-with-previous
667 { "n" integer } { "quot" quotation } { "into" object }
672 { "seq" sequence } { "quot" quotation }
675 { $description "Count the number of values at the beginning of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
679 { "seq" sequence } { "quot" quotation }
682 { $description "Count the number of values from the end of " { $snippet "seq" } " that return a truthy value when passed into " { $snippet "quot" } "." } ;
686 { "seq" sequence } { "quot" quotation } { "n" integer }
689 { $description "Returns " { $link t } " if the sequence has exactly " { $snippet "n" } " elements where " { $snippet "quot" } " returns true, otherwise returns " { $link f } "." } ;
694 { "seq" sequence } { "quot" quotation }
695 { "before" object } { "after" object }
697 { $description "Cut the given sequence before the first element of " { $snippet "seq" } " that returns a truthy value when passed into " { $snippet "quot" } "." } ;
701 { "seq" sequence } { "quot" quotation }
702 { "tail-slice" object }
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." } ;
706 HELP: each-index-from
708 { "seq" sequence } { "quot" quotation } { "i" integer }
711 HELP: each-integer-with-previous
713 { "n" integer } { "quot" quotation }
718 { "seq" sequence } { "quot" quotation }
723 { "seq" sequence } { "quot" quotation }
726 HELP: ensure-same-underlying
728 { "slice1" slice } { "slice2" slice }
736 { $description "Push a sequence containing the even-indexed elements in " { $snippet "seq" } "." } ;
739 { $class-description "The class of virtual sequences which contain the even-indexed elements of a given sequence." } ;
743 { "seq" sequence } { "quot" quotation }
746 HELP: filter-all-subseqs
748 { "seq" sequence } { "quot" quotation }
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" } "." } ;
752 HELP: filter-all-subseqs-range
754 { "seq" sequence } { "range" object } { "quot" quotation }
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" } "." } ;
760 { "seq" sequence } { "quot" quotation }
763 { $description "Perform a " { $link filter } " on the given sequence, with the index provided as an additional argument to " { $snippet "quot" } "." } ;
765 HELP: filter-index-as
767 { "seq" sequence } { "quot" quotation } { "exemplar" object }
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" } "." } ;
774 { "seq" sequence } { "n" integer }
777 { $description "Push a sequence that contains all elements of " { $snippet "seq" } " that have length " { $snippet "n" } "." } ;
781 { "seq" sequence } { "filter-quot" object } { "map-quot" object }
782 { "newseq" sequence }
784 { $description "Filter the given sequence with " { $snippet "filter-quot" } ", then perform a map on the filtered sequence with " { $snippet "map-quot" } "." } ;
788 { "seq" sequence } { "filter-quot" object } { "map-quot" object } { "exemplar" object }
789 { "newseq" sequence }
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" } "." } ;
793 HELP: find-last-index
795 { "seq" sequence } { "quot" quotation }
796 { "i" integer } { "elt" object }
798 { $description "A simpler variant of " { $link find-last-index-from } ", with starting index set to 0." } ;
800 HELP: find-last-index-from
802 { "n" integer } { "seq" sequence } { "quot" quotation }
803 { "i" integer } { "elt" object }
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." } ;
809 { "i" integer } { "n" integer } { "seq" sequence } { "quot" quotation }
810 { "calc/f" object } { "i/f" { $maybe integer } } { "elt/f" object }
816 { "newseq" sequence }
818 { $description "Outputs a new sequence with all empty sequences removed. Modifies " { $snippet "seq" } "in place." } ;
822 { "seq" sequence } { "exemplar" object }
823 { "newseq" sequence }
825 { $description "Outputs a new sequence with all empty sequences removed. Resulting sequence is the same class as " { $snippet "exemplar" } "." } ;
829 { "seq" sequence } { "n" integer } { "exemplar" object }
832 { $description "A version of " { $link head* } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
836 { "seq" sequence } { "n" integer } { "exemplar" object }
839 { $description "A version of " { $link head } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
846 { $description "Collect the pairs inside a heap into a sequence. Ordering of the sequence is based on the ordering of the heap." } ;
851 { "selector" object } { "accum" object }
854 HELP: index-selector-as
856 { "quot" quotation } { "exemplar" object }
857 { "selector" object } { "accum" object }
862 { "seq" sequence } { "quot" quotation }
863 { "i" integer } { "elt" object }
865 { $description "A variant of " { $link minimum-by } " that pushes the index of the least element along with the least element." } ;
869 { "elt" object } { "n" integer } { "seq" sequence }
871 { $description "A variant of " { $link insert-nth } " that modifies " { $snippet "seq" } " in place." } ;
875 { "seq" sequence } { "glue" object }
876 { "newseq" sequence }
878 { $description "Insert " { $link glue } " between every pair of elements in " { $snippet "seq" } "." } ;
882 { "seq" sequence } { "glue" object } { "exemplar" object }
883 { "newseq" sequence }
885 { $description "Insert " { $link glue } " between every pair of elements in " { $snippet "seq" } ". Resulting sequence will be the same class as " { $snippet "exemplar" } "." } ;
887 HELP: iterate-heap-while
889 { "heap" object } { "quot1" quotation } { "quot2" quotation }
890 { "obj/f" { $maybe object } } { "loop?" object }
895 { "seq" sequence } { "elt" object }
898 { $description "Check if the last element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
902 { "seq" sequence } { "quot" quotation }
905 { $description "Check if the last element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
909 { "seq1" sequence } { "seq2" sequence }
912 { $description "Pushes the longest subsequence of " { $snippet "seq" } "." } ;
916 { "seq" sequence } { "quot" quotation }
917 { "newseq" sequence }
919 { $description "Perform a " { $link map } " on the given sequence with " { $snippet "quot" } ", then perform a " { $link concat } " on the result." } ;
923 { "seq" sequence } { "quot" quotation } { "exemplar" object }
924 { "newseq" sequence }
926 { $description "A version of " { $link map-concat } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
930 { "seq" sequence } { "map-quot" object } { "filter-quot" object }
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" } "." } ;
937 { "seq" sequence } { "map-quot" object } { "filter-quot" object } { "exemplar" object }
940 { $description "A version of " { $link map-filter } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
944 { "seq" sequence } { "quot" quotation }
945 { "result" object } { "i" integer } { "elt" object }
947 { $description "A version of " { $link map-find } " where the index of the found element, if any, is returned." } ;
949 HELP: map-find-last-index
951 { "seq" sequence } { "quot" quotation }
952 { "result" object } { "i" integer } { "elt" object }
954 { $description "A version of " { $link map-find-index } " where the index of the found element, if any, is returned." } ;
958 { "seq" sequence } { "quot" quotation } { "from" integer }
959 { "newseq" sequence }
961 { $description "A version of " { $link map } " that maps the slice of " { $snippet "seq" } " beginning at index " { $snippet "i" } "." } ;
965 { "seq" sequence } { "quot" quotation } { "from" integer } { "exemplar" object }
966 { "newseq" sequence }
968 { $description "A version of " { $link map-from } " where the resultant sequence has the same class as " { $snippet "exemplar" } } ;
972 { "seq" sequence } { "quot" quotation }
973 { "newseq" sequence }
975 { $description "A version of " { $link map } " with all empty sequences removed from the result." } ;
979 { "seq" sequence } { "if-quot" object } { "map-quot" object }
980 { "newseq" sequence }
982 { $description "A version of " { $link map } " where " { $snippet "map-quot" } " is applied only if " { $snippet "if-quot" } " returns true for a given element." } ;
986 { "seq" sequence } { "quot" quotation }
988 { $description "A version of " { $link map-index } " which modifies " { $snippet "seq" } " in place." } ;
990 HELP: map-integers-with
992 { "len" object } { "quot" quotation } { "exemplar" object }
993 { "newseq" sequence }
998 { "seq" sequence } { "exemplar" object }
1004 { "seq" sequence } { "quot" quotation }
1010 { "seq" sequence } { "quot" quotation } { "exemplar" object }
1016 { "seq" sequence } { "quot" quotation }
1019 { $description "Like " { $code "map product" } ", but without creating an intermediate sequence." } ;
1023 { "seq" sequence } { "quot" quotation }
1024 { "newseq" sequence }
1026 { $description "A version of " { $link map } " with all instances of " { $link f } " removed from the result." } ;
1028 HELP: map-with-previous
1030 { "seq" sequence } { "quot" quotation }
1031 { "newseq" sequence }
1034 HELP: map-with-previous-as
1036 { "seq" sequence } { "quot" quotation } { "exemplar" object }
1037 { "newseq" sequence }
1042 { "quot" quotation }
1043 { "alist" "an array of key/value pairs" }
1046 HELP: max-subarray-sum
1051 { $description "Output the maximum subarray sum of the sequence." } ;
1055 { "slice1" slice } { "slice2" slice }
1056 { "slice/*" object }
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." } ;
1066 { "n" integer } { "seq" sequence }
1069 { $description "Pushes the nth element of the sequence if it exists, otherwise pushes sequence length - 1." } ;
1073 { "n" integer } { "seq" sequence } { "elt" object }
1076 { $description "Check if the nth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
1080 { "n" integer } { "seq" sequence } { "quot" quotation }
1083 { $description "Check if the nth element of " { $snippet "seq" } " satisfies the condition given by " { $snippet "quot" } "." } ;
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." } ;
1094 { $description "Push a sequence containing the odd-indexed elements in " { $snippet "seq" } "." } ;
1097 { $class-description "The class of virtual sequences which contain the odd-indexed elements of a given sequence." } ;
1101 { "seq" sequence } { "quot" quotation }
1105 HELP: ordered-slices-overlap?
1107 { "slice-lt" object } { "slice-gt" object }
1111 HELP: ordered-slices-range
1113 { "slice-lt" object } { "slice-gt" object }
1114 { "to" integer } { "from" integer }
1117 HELP: ordered-slices-touch?
1119 { "slice-lt" object } { "slice-gt" object }
1125 { "seq1" sequence } { "seq2" sequence } { "elt" object }
1127 { $description "Perform " { $link pad-tail } " on both sequences, padding with " { $snippet "elt" } " to the longest length between the two." } ;
1129 HELP: prepend-lines-with-spaces
1134 { $description "Prepend four spaces to each line in " { $snippet "str" } "." } ;
1138 { "elt" object } { "quot" quotation } { "accum" object }
1143 { "elt" object } { "i" integer } { "quot" quotation } { "accum" object }
1148 { "seq" sequence } { "identity" object } { "quot" quotation } { "from" integer }
1154 { "obj" object } { "seq" sequence }
1157 { $description "Remove the first occurrence of " { $snippet "obj" } " in " { $snippet "seq" } "." } ;
1161 { "obj" object } { "seq" sequence }
1163 { $description "A version of " { $link remove-first } " that modifies " { $snippet "seq" } " in place." } ;
1167 { "obj" object } { "seq" sequence }
1170 { $description "Remove the last occurrence of " { $snippet "obj" } " in " { $snippet "seq" } "." } ;
1174 { "obj" object } { "seq" sequence }
1176 { $description "A version of " { $link remove-last } " that modifies " { $snippet "seq" } " in place." } ;
1178 HELP: replicate-into
1180 { "seq" sequence } { "quot" quotation }
1185 { "seq" sequence } { "exemplar" object }
1186 { "newseq" sequence }
1188 { $description "A version of " { $link reverse } " where " { $snippet "seq'" } " is the same class as " { $snippet "exemplar" } "." } ;
1192 { "seq" sequence } { "n" integer }
1195 { $description "Move the first " { $snippet "n" } " elements of " { $snippet "seq" } " to the end." } ;
1199 { "seq" sequence } { "n" integer }
1201 { $description "A version of " { $link rotate } " that modifies " { $snippet "seq" } " in place." } ;
1206 { "newseq" sequence }
1208 { $description "List all elements of " { $snippet "seq" } " in column-major order." } ;
1212 { "from" integer } { "to" integer } { "seq" sequence }
1215 { $description "A safe version of " { $link subseq } "." } ;
1219 { "quot" quotation }
1220 { "selector" object } { "accum" object }
1225 { "quot" quotation } { "exemplar" object }
1226 { "selector" object } { "accum" object }
1229 HELP: sequence-index-operator-last
1231 { "n" integer } { "seq" sequence } { "quot" quotation }
1232 { "quot'" quotation }
1235 HELP: sequence>slice
1237 { "sequence" sequence }
1240 { $description "Create a virtual sequence that represents the given sequence." } ;
1244 { "value" object } { "indices" object } { "seq" sequence }
1246 { $description "Set the elements at all given indices to " { $snippet "value" } ". modifies " { $snippet "seq" } " in place." } ;
1248 HELP: set-nths-unsafe
1250 { "value" object } { "indices" object } { "seq" sequence }
1252 { $description "Unsafe version of " { $link set-nths } } ;
1256 { "vector" object } { "n" integer }
1262 { "seq" { "a resizable mutable " { $link sequence } } }
1263 { "seq'" { "a resizable mutable " { $link sequence } } }
1265 { $description "Removes all instances of " { $link f } " from a sequence." }
1266 { $notes "The sequence " { $snippet "seq" } " MUST be growable. See " { $link "growable" } "." }
1267 { $side-effects "seq" }
1270 "USING: prettyprint sequences.extras ;"
1271 "V{ 2 f \"a\" f { } f } sift! ."
1275 { $see-also sift filter! filter harvest! harvest } ;
1279 { "seq" sequence } { "exemplar" object }
1280 { "newseq" sequence }
1283 HELP: slice-order-by-from
1285 { "slice1" slice } { "slice2" slice }
1286 { "slice-lt" object } { "slice-gt" object }
1291 { "seq" sequence } { "quot" quotation }
1295 HELP: slices-don't-touch
1297 { "slice1" slice } { "slice2" slice }
1299 { $description "Throws a " { $link slices-don't-touch } " error." }
1300 { $error-description "" } ;
1302 HELP: slices-overlap?
1304 { "slice1" slice } { "slice2" slice }
1310 { "slice1" slice } { "slice2" slice }
1314 HELP: slurp-heap-while-map
1316 { "heap" object } { "quot1" quotation } { "quot2" quotation }
1322 { "slice1" slice } { "slice2" slice }
1325 { $description "Create a virtual sequence spanning the length covered by " { $snippet "slice1" } " and " { $snippet "slice2" } ". Slices must refer to the same sequence." } ;
1329 { "seq" sequence } { "quot" quotation }
1330 { "i" integer } { "elt" object }
1332 { $description "A variant of " { $link maximum-by } " that pushes the index of the greated element along with the greatest element." } ;
1336 { "seq" sequence } { "n" integer } { "exemplar" object }
1342 { "seq" sequence } { "n" integer } { "exemplar" object }
1348 { "seq" sequence } { "quot" quotation }
1349 { "head-slice" object }
1354 { "seq" sequence } { "quot" quotation } { "exemplar" object }
1355 { "newseq" sequence }
1358 HELP: underlying-mismatch
1360 { "slice1" slice } { "slice2" slice }
1362 { $description "Throws an " { $link underlying-mismatch } " error." }
1363 { $error-description "" } ;
1365 HELP: unordered-slices-overlap?
1367 { "slice1" slice } { "slice2" slice }
1371 HELP: unordered-slices-range
1373 { "slice1" slice } { "slice2" slice }
1374 { "to" integer } { "from" integer }
1377 HELP: unordered-slices-touch?
1379 { "slice1" slice } { "slice2" slice }
1385 { "seq" sequence } { "quot" quotation }
1388 HELP: with-string-lines
1390 { "str" string } { "quot" quotation }
1394 HELP: exchange-subseq
1396 { "len" { "a non-negative " { $link integer } } }
1397 { "pos1" { "a non-negative " { $link integer } } }
1398 { "pos2" { "a non-negative " { $link integer } } }
1399 { "seq" { "a mutable " { $link sequence } } }
1401 { $description "Exchanges the contents of subsequences "
1402 { $snippet "[pos1, pos1+len)" } " and " { $snippet "[pos2, pos2+len)" } " in "
1403 { $snippet "seq" } ". Overlapping ranges are allowed. If either of the ranges exceeds the "
1404 { $snippet "seq" } " length, throws an error before any modifications take place. If "
1405 { $snippet "len" } " = 1, the behavior is equivalent to " { $link exchange } "." }
1407 "Non-overlapping ranges:"
1408 { $example "USING: kernel sequences.extras prettyprint ;"
1409 "2 0 3 \"01_34_\" [ exchange-subseq ] keep ."
1412 "Overlapping ranges:"
1413 { $example "USING: kernel sequences.extras prettyprint ;"
1414 "3 0 2 \"abcdef\" [ exchange-subseq ] keep ."
1418 { $side-effects "seq" }
1419 { $see-also exchange } ;