factor: trim using lists

[factor.git] / basis / circular / circular-docs.factor

diff --git a/basis/circular/circular-docs.factor b/basis/circular/circular-docs.factor
index 8abadfadd2230f54f41bb8921f50d0fbbe70de96..259001ef0a75e05a5b7e9a096bf365c4933bb974 100644 (file)
--- a/basis/circular/circular-docs.factor
+++ b/basis/circular/circular-docs.factor
@@ -1,7 +1,6 @@
 ! Copyright (C) 2008 Doug Coleman.
 ! See http://factorcode.org/license.txt for BSD license.
-USING: help.markup help.syntax io.streams.string sequences
-math kernel ;
+USING: help.markup help.syntax sequences math kernel quotations ;
 IN: circular
 
 HELP: <circular-string>
@@ -33,12 +32,12 @@ HELP: circular
 HELP: growing-circular
 { $description "A circular sequence that is growable." } ;
 
-HELP: push-circular
+HELP: circular-push
 { $values
      { "elt" object } { "circular" circular } }
 { $description "Pushes an element to a " { $link circular } " object." } ;
 
-HELP: push-growing-circular
+HELP: growing-circular-push
 { $values
      { "elt" object } { "circular" circular } }
 { $description "Pushes an element onto a " { $link growing-circular } " object." } ;
@@ -48,6 +47,21 @@ HELP: rotate-circular
     { "circular" circular } }
 { $description "Advances the start index of a circular object by one." } ;
 
+HELP: circular-while
+{ $values
+    { "circular" circular }
+    { "quot" quotation }
+}
+{ $description "Calls " { $snippet "quot" } " on each element of the sequence until each call yields " { $link f } " in succession." } ;
+
+HELP: circular-loop
+{ $values
+    { "circular" circular }
+    { "quot" quotation }
+}
+{ $description "Calls " { $snippet "quot" } " on each element of the sequence until one call yields " { $link f } "." }
+{ $notes "This rotates the " { $link circular } " object after each call, so the next element to be applied will always be the first element." } ;
+
 ARTICLE: "circular" "Circular sequences"
 "The " { $vocab-link "circular" } " vocabulary implements the " { $link "sequence-protocol" } " to allow an arbitrary start index and wrap-around indexing." $nl
 "Creating a new circular object:"
@@ -63,8 +77,10 @@ ARTICLE: "circular" "Circular sequences"
 }
 "Pushing new elements:"
 { $subsections
-    push-circular
-    push-growing-circular
-} ;
+    circular-push
+    growing-circular-push
+}
+"Iterating over a circular until a stop condition:"
+{ $subsections circular-while circular-loop } ;
 
 ABOUT: "circular"