! 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>
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." } ;
-ARTICLE: "circular" "circular"
+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"