Add more documentation to sequences.extras

diff --git a/extra/sequences/extras/extras-docs.factor b/extra/sequences/extras/extras-docs.factor
index 26dff24245fb982d11c173efad6d38f1e88ed72d..e547297018a3a6ebbb94ab177cd764da22e3c30b 100644 (file)
--- a/extra/sequences/extras/extras-docs.factor
+++ b/extra/sequences/extras/extras-docs.factor
@@ -1,6 +1,42 @@
 USING: help.markup help.syntax kernel math sequences ;
 IN: sequences.extras
 
+HELP: 2count
+{ $values
+    { "seq1" sequence }
+    { "seq2" sequence }
+    { "quot" { $quotation ( ... elt1 elt2 -- ... ? ) } }
+    { "n" integer } }
+{ $description "Efficiently counts how many pairwise elements of " { $snippet "seq1" } " and " { $snippet "seq2" } " that the predicate quotation matches." }
+{ $examples
+    { $example "USING: kernel prettyprint sequences.extras ;" "{ 1 2 3 } { 3 2 1 } [ = ] 2count ." "1" } }
+{ $see-also count } ;
+
+HELP: 2each-index
+{ $values
+    { "seq1" sequence }
+    { "seq2" sequence }
+    { "quot" { $quotation ( ... elt1 elt2 index -- ... ) } } }
+{ $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." }
+{ $see-also 2each each-index } ;
+
+HELP: 2map!
+{ $values
+    { "seq1" sequence }
+    { "seq2" sequence }
+    { "quot" { $quotation ( ... elt1 elt2 -- ... newelt ) } } }
+{ $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" } "." }
+{ $see-also 2map map! } ;
+
+HELP: 2map-index
+{ $values
+    { "seq1" sequence }
+    { "seq2" sequence }
+    { "quot" { $quotation ( ... elt1 elt2 index -- ... newelt ) } }
+    { "newseq" sequence } }
+{ $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." }
+{ $see-also 2map map-index } ;
+
 HELP: count*
 { $values
     { "seq" sequence }
@@ -54,6 +90,34 @@ HELP: find-all
 { $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: first=
+{ $values
+    { "seq" sequence }
+    { "elt" object }
+    { "?" boolean } }
+{ $description "Checks whether the first element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
+
+HELP: first?
+{ $values
+    { "seq" sequence }
+    { "quot" { $quotation ( ... elt -- ... ? ) } }
+    { "?" boolean } }
+{ $description "Tests whether the first element of " { $snippet "seq" } " satisfies the provided predicate." } ;
+
+HELP: fourth=
+{ $values
+    { "seq" sequence }
+    { "elt" object }
+    { "?" boolean } }
+{ $description "Checks whether the fourth element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
+
+HELP: fourth?
+{ $values
+    { "seq" sequence }
+    { "quot" { $quotation ( ... elt -- ... ? ) } }
+    { "?" boolean } }
+{ $description "Tests whether the fourth element of " { $snippet "seq" } " satisfies the provided predicate." } ;
+
 HELP: <odds>
 { $values { "seq" sequence } { "odds" odds } }
 { $description "Create a virtual sequence whose elements consist of the odd-indexed elements from the original sequence." }
@@ -64,6 +128,20 @@ HELP: >resizable
 { $values { "seq" sequence } { "accum" sequence } }
 { $description "Converts a sequence into the nearest resizable equivalent, preserving its contents." } ;
 
+HELP: second=
+{ $values
+    { "seq" sequence }
+    { "elt" object }
+    { "?" boolean } }
+{ $description "Checks whether the second element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
+
+HELP: second?
+{ $values
+    { "seq" sequence }
+    { "quot" { $quotation ( ... elt -- ... ? ) } }
+    { "?" boolean } }
+{ $description "Tests whether the second element of " { $snippet "seq" } " satisfies the provided predicate." } ;
+
 HELP: subseq*
 { $values
      { "from" integer } { "to" integer } { "seq" sequence } { "subseq" sequence } }
@@ -88,6 +166,20 @@ HELP: subseq*
     }
 } ;
 
+HELP: third=
+{ $values
+    { "seq" sequence }
+    { "elt" object }
+    { "?" boolean } }
+{ $description "Checks whether the third element of " { $snippet "seq" } " is equal to " { $snippet "elt" } "." } ;
+
+HELP: third?
+{ $values
+    { "seq" sequence }
+    { "quot" { $quotation ( ... elt -- ... ? ) } }
+    { "?" boolean } }
+{ $description "Tests whether the third element of " { $snippet "seq" } " satisfies the provided predicate." } ;
+
 HELP: unsurround
 { $values
     { "newseq" sequence }