core/dequeues/dequeues-docs.factor

   1 IN: dequeues
   2 USING: help.markup help.syntax kernel ;
   3
   4 ARTICLE: "dequeues" "Dequeues"
   5 "A dequeue is a data structure with constant-time insertion and removal of elements at both ends. Dequeue operations are defined in the " { $vocab-link "dequeues" } " vocabulary."
   6 $nl
   7 "Dequeues must be instances of a mixin class:"
   8 { $subsection dequeue }
   9 "Dequeues must implement a protocol."
  10 $nl
  11 "Querying the dequeue:"
  12 { $subsection peek-front }
  13 { $subsection peek-back }
  14 { $subsection dequeue-length }
  15 { $subsection dequeue-member? }
  16 "Adding and removing elements:"
  17 { $subsection push-front* }
  18 { $subsection push-back* }
  19 { $subsection pop-front* }
  20 { $subsection pop-back* }
  21 { $subsection clear-dequeue }
  22 "Working with node objects output by " { $link push-front* } " and " { $link push-back* } ":"
  23 { $subsection delete-node }
  24 { $subsection node-value }
  25 "Utility operations built in terms of the above:"
  26 { $subsection dequeue-empty? }
  27 { $subsection push-front }
  28 { $subsection push-all-front }
  29 { $subsection push-back }
  30 { $subsection push-all-back }
  31 { $subsection pop-front }
  32 { $subsection pop-back }
  33 { $subsection slurp-dequeue }
  34 "When using a dequeue as a queue, the convention is to queue elements with " { $link push-front } " and dequeue them with " { $link pop-back } "." ;
  35
  36 ABOUT: "dequeues"
  37
  38 HELP: dequeue-empty?
  39 { $values { "dequeue" { $link dequeue } } { "?" "a boolean" } }
  40 { $description "Returns true if a dequeue is empty." }
  41 { $notes "This operation is O(1)." } ;
  42
  43 HELP: push-front
  44 { $values { "obj" object } { "dequeue" dequeue } }
  45 { $description "Push the object onto the front of the dequeue." }
  46 { $notes "This operation is O(1)." } ;
  47
  48 HELP: push-front*
  49 { $values { "obj" object } { "dequeue" dequeue } { "node" "a node" } }
  50 { $description "Push the object onto the front of the dequeue and return the newly created node." }
  51 { $notes "This operation is O(1)." } ;
  52
  53 HELP: push-back
  54 { $values { "obj" object } { "dequeue" dequeue } }
  55 { $description "Push the object onto the back of the dequeue." }
  56 { $notes "This operation is O(1)." } ;
  57
  58 HELP: push-back*
  59 { $values { "obj" object } { "dequeue" dequeue } { "node" "a node" } }
  60 { $description "Push the object onto the back of the dequeue and return the newly created node." }
  61 { $notes "This operation is O(1)." } ;
  62
  63 HELP: peek-front
  64 { $values { "dequeue" dequeue } { "obj" object } }
  65 { $description "Returns the object at the front of the dequeue." } ;
  66
  67 HELP: pop-front
  68 { $values { "dequeue" dequeue } { "obj" object } }
  69 { $description "Pop the object off the front of the dequeue and return the object." }
  70 { $notes "This operation is O(1)." } ;
  71
  72 HELP: pop-front*
  73 { $values { "dequeue" dequeue } }
  74 { $description "Pop the object off the front of the dequeue." }
  75 { $notes "This operation is O(1)." } ;
  76
  77 HELP: peek-back
  78 { $values { "dequeue" dequeue } { "obj" object } }
  79 { $description "Returns the object at the back of the dequeue." } ;
  80
  81 HELP: pop-back
  82 { $values { "dequeue" dequeue } { "obj" object } }
  83 { $description "Pop the object off the back of the dequeue and return the object." }
  84 { $notes "This operation is O(1)." } ;
  85
  86 HELP: pop-back*
  87 { $values { "dequeue" dequeue } }
  88 { $description "Pop the object off the back of the dequeue." }
  89 { $notes "This operation is O(1)." } ;