basis/biassocs/biassocs-docs.factor

   1 IN: biassocs
   2 USING: help.markup help.syntax assocs kernel ;
   3
   4 HELP: biassoc
   5 { $class-description "The class of bidirectional assocs. Bidirectional assoc are implemented by combining two assocs, with one the transpose of the other." } ;
   6
   7 HELP: <biassoc>
   8 { $values { "exemplar" assoc } { "biassoc" biassoc } }
   9 { $description "Creates a new biassoc using a new assoc of the same type as " { $snippet "exemplar" } " for underlying storage." } ;
  10
  11 HELP: <bihash>
  12 { $values { "biassoc" biassoc } }
  13 { $description "Creates a new biassoc using a pair of hashtables for underlying storage." } ;
  14
  15 HELP: set-at-once
  16 { $values { "value" object } { "key" object } { "assoc" assoc } }
  17 { $description "If the assoc does not contain the given key, adds the key/value pair to the assoc, otherwise does nothing." } ;
  18
  19 HELP: >biassoc
  20 { $values { "assoc" assoc } { "biassoc" biassoc } }
  21 { $description "Constructs a new biassoc with the same key/value pairs as the given assoc." } ;
  22
  23 ARTICLE: "biassocs" "Bidirectional assocs"
  24 "A " { $emphasis "bidirectional assoc" } " combines a pair of assocs to form a data structure where both normal assoc operations (eg, " { $link at } "), as well as " { $link "assocs-values" } " (eg, " { $link value-at } ") run in sub-linear time."
  25 $nl
  26 "Bidirectional assocs implement the entire " { $link "assocs-protocol" } " with the exception of " { $link delete-at } ". Duplicate values are allowed, however value lookups with " { $link value-at } " only return the first key that a given value was stored with."
  27 $nl
  28 "The class of biassocs:"
  29 { $subsections
  30     biassoc
  31     biassoc?
  32 }
  33 "Creating new biassocs:"
  34 { $subsections
  35     <biassoc>
  36     <bihash>
  37 }
  38 "Converting existing assocs to biassocs:"
  39 { $subsections >biassoc } ;
  40
  41 ABOUT: "biassocs"