diff --git a/extra/sequences/extras/extras-docs.factor b/extra/sequences/extras/extras-docs.factor index 17d7e3a811..4e347eec45 100644 --- a/extra/sequences/extras/extras-docs.factor +++ b/extra/sequences/extras/extras-docs.factor @@ -1,6 +1,67 @@ USING: help.markup help.syntax math sequences ; IN: sequences.extras +HELP: count* +{ $values + { "seq" sequence } + { "quot" { $quotation ( ... elt -- ... ? ) } } + { "%" rational } } +{ $description "Outputs the fraction of elements in the sequence for which the predicate quotation matches." } +{ $examples { $example "USING: math.ranges prettyprint sequences.extras ;" "100 [1,b] [ even? ] count*" "1/2" } } ; + +HELP: collapse +{ $values + { "seq" sequence } + { "quot" { $quotation ( ... elt -- ... ? ) } } + { "seq'" sequence } } +{ $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" } "." } +{ $see-also compact } +{ $examples + "Collapse multiple spaces in a string down to a single space" + { $example "USING: sequences.extras ;" "\" Hello, crazy world \" [ CHAR: \\s = ] \" \" collapse" "\" Hello, crazy world \"" } } ; + +HELP: compact +{ $values + { "seq" sequence } + { "quot" { $quotation ( ... elt -- ... ? ) } } + { "seq'" sequence } } +{ $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." } +{ $see-also collapse } +{ $examples + "Collapse multiple spaces in a string down to a single space" + { $example "USING: sequences.extras ;" "\" Hello, crazy world \" [ CHAR: \\s = ] \" \" compact" "\"Hello, crazy world\"" } } ; + +HELP: combos +{ $values + { "list1" sequence } + { "list2" sequence } + { "result" sequence } } +{ $description "Returns all combinations of the first sequence with the second sequence. The result is not uniquified: if the sequences contain duplicate elements, then the same pair may appear multiple times in the result sequence." } ; + +HELP: +{ $values { "seq" sequence } { "evens" evens } } +{ $description "Create a virtual sequence whose elements consist of the even-indexed elements from the original sequence." } +{ $notes "Because sequences are zero-indexed, this collection includes the first, third, fifth, etc. elements of the actual sequence which can be counterintuitive." } +{ $see-also } ; + +HELP: find-all +{ $values + { "seq" sequence } + { "quot" { $quotation ( elt -- ? ) } } + { "elts" "the indices of the matching elements" } } +{ $description "Similar to " { $link find } ", but finds all of the indices and elements that match the provided quotation, not just the first." } +{ $notes "The result is provided as an array of arrays, whose first value is the index and whose second value is teh element." } ; + +HELP: +{ $values { "seq" sequence } { "odds" odds } } +{ $description "Create a virtual sequence whose elements consist of the odd-indexed elements from the original sequence." } +{ $notes "Because sequences are zero-indexed, this collection includes the second, fourth, sixth, etc. elements of the actual sequence which can be counterintuitive." } +{ $see-also } ; + +HELP: >resizable +{ $values { "seq" sequence } { "accum" sequence } } +{ $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ; + HELP: subseq* { $values { "from" integer } { "to" integer } { "seq" sequence } { "subseq" sequence } } @@ -24,3 +85,12 @@ HELP: subseq* "\"bcdef\"" } } ; + +HELP: unsurround +{ $values + { "newseq" sequence } + { "seq2" sequence } + { "seq3" sequence } + { "seq1" sequence } } +{ $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" } "." } +{ $see-also surround } ; diff --git a/extra/sequences/extras/summary.txt b/extra/sequences/extras/summary.txt new file mode 100644 index 0000000000..e648c68f9d --- /dev/null +++ b/extra/sequences/extras/summary.txt @@ -0,0 +1 @@ +Contains sequence operations that are not commonly needed. Most of these words are elaborations on functions already available in the main sequences vocabulary. diff --git a/extra/sequences/extras/tags.txt b/extra/sequences/extras/tags.txt new file mode 100644 index 0000000000..63926bbb49 --- /dev/null +++ b/extra/sequences/extras/tags.txt @@ -0,0 +1 @@ +sequences