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 c7af57c1feba64ada3bd3fd04d596eb12b5540e4..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,26 +32,55 @@ 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." } ;
 
+HELP: rotate-circular
+{ $values
+    { "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:"
-{ $subsection <circular> }
-{ $subsection <circular-string> }
-{ $subsection <growing-circular> }
+{ $subsections
+    <circular>
+    <circular-string>
+    <growing-circular>
+}
 "Changing the start index:"
-{ $subsection change-circular-start }
+{ $subsections
+    change-circular-start
+    rotate-circular
+}
 "Pushing new elements:"
-{ $subsection push-circular }
-{ $subsection push-growing-circular } ;
+{ $subsections
+    circular-push
+    growing-circular-push
+}
+"Iterating over a circular until a stop condition:"
+{ $subsections circular-while circular-loop } ;
 
 ABOUT: "circular"