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