Add more documentation for sequences.extras

diff --git a/extra/sequences/extras/extras-docs.factor b/extra/sequences/extras/extras-docs.factor
index 17d7e3a8118b2d9dfbddb842264699550c4f6920..4e347eec45a8d3b3d8318915d7114ea3587df479 100644 (file)
--- 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: <evens>
+{ $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 <odds> } ;
+
+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: <odds>
+{ $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 <evens> } ;
+
+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 (file)
index 0000000..e648c68
--- /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 (file)
index 0000000..63926bb
--- /dev/null
+++ b/extra/sequences/extras/tags.txt
@@ -0,0 +1 @@
+sequences