basis/dlists/dlists-docs.factor

   1 USING: help.markup help.syntax kernel quotations
   2 deques search-deques hashtables ;
   3 IN: dlists
   4
   5 ARTICLE: "dlists" "Double-linked lists"
   6 "A double-linked list is the canonical implementation of a " { $link deque } "."
   7 $nl
   8 "Double-linked lists form a class:"
   9 { $subsection dlist }
  10 { $subsection dlist? }
  11 "Constructing a double-linked list:"
  12 { $subsection <dlist> }
  13 "Double-linked lists support all the operations of the deque protocol (" { $link "deques" } ") as well as the following."
  14 $nl
  15 "Iterating over elements:"
  16 { $subsection dlist-each }
  17 { $subsection dlist-find }
  18 { $subsection dlist-any? }
  19 "Deleting a node matching a predicate:"
  20 { $subsection delete-node-if* }
  21 { $subsection delete-node-if }
  22 "Search deque implementation:"
  23 { $subsection <hashed-dlist> } ;
  24
  25 ABOUT: "dlists"
  26
  27 HELP: <dlist>
  28 { $values { "list" dlist } }
  29 { $description "Creates a new double-linked list." } ;
  30
  31 HELP: <hashed-dlist>
  32 { $values { "search-deque" search-deque } }
  33 { $description "Creates a new " { $link search-deque } " backed by a " { $link dlist } ", with a " { $link hashtable } " for fast membership tests." } ;
  34
  35 HELP: dlist-find
  36 { $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" "a boolean" } }
  37 { $description "Applies the quotation to each element of the " { $link dlist } " in turn, until it outputs a true value or the end of the " { $link dlist } " is reached.  Outputs either the object it found or " { $link f } ", and a boolean which is true if an object is found." }
  38 { $notes "Returns a boolean to allow dlists to store " { $link f } "."
  39     $nl
  40     "This operation is O(n)."
  41 } ;
  42
  43 HELP: dlist-any?
  44 { $values { "dlist" { $link dlist } } { "quot" quotation } { "?" "a boolean" } }
  45 { $description "Just like " { $link dlist-find } " except it doesn't return the object." }
  46 { $notes "This operation is O(n)." } ;
  47
  48 HELP: delete-node-if*
  49 { $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } { "?" "a boolean" } }
  50 { $description "Calls " { $link dlist-find } " on the " { $link dlist } " and deletes the node returned, if any.  Returns the value of the deleted node and a boolean to allow the deleted value to distinguished from " { $link f } ", for nothing deleted." }
  51 { $notes "This operation is O(n)." } ;
  52
  53 HELP: delete-node-if
  54 { $values { "dlist" { $link dlist } } { "quot" quotation } { "obj/f" "an object or " { $link f } } }
  55 { $description "Like " { $link delete-node-if* } " but cannot distinguish from deleting a node whose value is " { $link f } " or not deleting an element." }
  56 { $notes "This operation is O(n)." } ;
  57
  58 HELP: dlist-each
  59 { $values { "dlist" { $link dlist } } { "quot" quotation } }
  60 { $description "Iterate a " { $link dlist } ", calling quot on each element." } ;