basis/circular/circular-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax io.streams.string sequences
   4 math kernel quotations ;
   5 IN: circular
   6
   7 HELP: <circular-string>
   8 { $values
   9      { "n" integer }
  10      { "circular" circular } }
  11 { $description "Creates a new circular string object. A circular string is a string object that can be accessed out of bounds and the index will wrap around to the start of the string." } ;
  12
  13 HELP: <circular>
  14 { $values
  15      { "seq" sequence }
  16      { "circular" circular } }
  17 { $description "Creates a new " { $link circular } " object that wraps an existing sequence. By default, the index is set to zero." } ;
  18
  19 HELP: <growing-circular>
  20 { $values
  21      { "capacity" integer }
  22      { "growing-circular" growing-circular } }
  23 { $description "Creates a new growing-circular object." } ;
  24
  25 HELP: change-circular-start
  26 { $values
  27      { "n" integer } { "circular" circular } }
  28 { $description "Changes the start index of a circular object." } ;
  29
  30 HELP: circular
  31 { $description "A tuple class that stores a sequence and its start index." } ;
  32
  33 HELP: growing-circular
  34 { $description "A circular sequence that is growable." } ;
  35
  36 HELP: circular-push
  37 { $values
  38      { "elt" object } { "circular" circular } }
  39 { $description "Pushes an element to a " { $link circular } " object." } ;
  40
  41 HELP: growing-circular-push
  42 { $values
  43      { "elt" object } { "circular" circular } }
  44 { $description "Pushes an element onto a " { $link growing-circular } " object." } ;
  45
  46 HELP: rotate-circular
  47 { $values
  48     { "circular" circular } }
  49 { $description "Advances the start index of a circular object by one." } ;
  50
  51 HELP: circular-while
  52 { $values
  53     { "circular" circular }
  54     { "quot" quotation }
  55 }
  56 { $description "Calls " { $snippet "quot" } " on each element of the sequence until each call yields " { $link f } " in succession." } ;
  57
  58 HELP: circular-loop
  59 { $values
  60     { "circular" circular }
  61     { "quot" quotation }
  62 }
  63 { $description "Calls " { $snippet "quot" } " on each element of the sequence until one call yields " { $link f } "." }
  64 { $notes "This rotates the " { $link circular } " object after each call, so the next element to be applied will always be the first element." } ;
  65
  66 ARTICLE: "circular" "Circular sequences"
  67 "The " { $vocab-link "circular" } " vocabulary implements the " { $link "sequence-protocol" } " to allow an arbitrary start index and wrap-around indexing." $nl
  68 "Creating a new circular object:"
  69 { $subsections
  70     <circular>
  71     <circular-string>
  72     <growing-circular>
  73 }
  74 "Changing the start index:"
  75 { $subsections
  76     change-circular-start
  77     rotate-circular
  78 }
  79 "Pushing new elements:"
  80 { $subsections
  81     circular-push
  82     growing-circular-push
  83 }
  84 "Iterating over a circular until a stop condition:"
  85 { $subsections circular-while circular-loop } ;
  86
  87 ABOUT: "circular"