Doc updates

core/assocs/assocs-docs.factor

@@ -57,13 +57,19 @@ ARTICLE: "assocs-lookup" "Lookup and querying of assocs"
 "Utility operations built up from the " { $link "assocs-protocol" } ":"
 { $subsection key? }
 { $subsection at }
-{ $subsection value-at }
 { $subsection assoc-empty? }
 { $subsection keys }
 { $subsection values }
 { $subsection assoc-stack }
 { $see-also at* assoc-size } ;
 
+ARTICLE: "assocs-values" "Transposed assoc operations"
+"Most assoc words take a key and find the corresponding value. The following words take a value and find the corresponding key:"
+{ $subsection value-at }
+{ $subsection value-at* }
+{ $subsection value? }
+"With most assoc implementations, these words runs in linear time, proportional to the number of entries in the assoc. For fast value lookups, use " { $vocab-link "biassocs" } "." ;
+
 ARTICLE: "assocs-sets" "Set-theoretic operations on assocs"
 "It is often useful to use the keys of an associative mapping as a set, exploiting the constant or logarithmic lookup time of most implementations (" { $link "alists" } " being a notable exception)."
 { $subsection assoc-subset? }
@@ -111,6 +117,7 @@ $nl
 { $subsection "assocs-protocol" }
 "A large set of utility words work on any object whose class implements the associative mapping protocol."
 { $subsection "assocs-lookup" }
+{ $subsection "assocs-values" }
 { $subsection "assocs-mutation" }
 { $subsection "assocs-combinators" }
 { $subsection "assocs-sets" } ;
@@ -231,10 +238,17 @@ HELP: assoc-stack
 { $description "Searches for the key in successive elements of the sequence, starting from the end. If an assoc containing the key is found, the associated value is output. If no assoc contains the key, outputs " { $link f } "." }
 { $notes "This word is used to implement abstractions such as nested scopes; if the sequence is a stack represented by a vector, then the most recently pushed assoc -- the innermost scope -- will be searched first." } ;
 
+HELP: value-at*
+{ $values { "value" "an object" } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } { "?" "a boolean" } }
+{ $description "Looks up the key associated with a value. The boolean flag can decide beteen the case of a missing key, and a key of " { $link f } "." } ;
+
 HELP: value-at
 { $values { "value" "an object" } { "assoc" assoc } { "key/f" "the key associated to the value, or " { $link f } } }
-{ $description "Looks up the key associated with a value. No distinction is made between a missing key and a key set to " { $link f } "." }
+{ $description "Looks up the key associated with a value. No distinction is made between a missing key and a key set to " { $link f } "." } ;
-{ $notes "This word runs in linear time, proportional to the number of entries in the assoc." } ;
+
+HELP: value?
+{ $values { "value" "an object" } { "assoc" assoc } { "?" "a boolean" } }
+{ $description "Tests if an assoc contains at least one key with the given value." } ;
 
 HELP: delete-at*
 { $values { "key" "a key" } { "assoc" assoc } { "old" "the previous value or " { $link f } } { "?" "a boolean" } }

core/grouping/grouping-docs.factor

@@ -2,10 +2,14 @@ USING: help.markup help.syntax sequences strings ;
 IN: grouping
 
 ARTICLE: "grouping" "Groups and clumps"
+"Splitting a sequence into disjoint, fixed-length subsequences:"
+{ $subsection group }
 "A virtual sequence for splitting a sequence into disjoint, fixed-length subsequences:"
 { $subsection groups }
 { $subsection <groups> }
 { $subsection <sliced-groups> }
+"Splitting a sequence into overlapping, fixed-length subsequences:"
+{ $subsection clump }
 "A virtual sequence for splitting a sequence into overlapping, fixed-length subsequences:"
 { $subsection clumps }
 { $subsection <clumps> }

extra/biassocs/authors.txt

@@ -0,0 +1 @@
+Slava Pestov

extra/biassocs/biassocs-docs.factor

@@ -0,0 +1,28 @@
+IN: biassocs
+USING: help.markup help.syntax assocs kernel ;
+
+HELP: biassoc
+{ $class-description "The class of bidirectional assocs. Bidirectional assoc are implemented by combining two assocs, with one the transpose of the other." } ;
+
+HELP: <biassoc>
+{ $values { "exemplar" assoc } { "biassoc" biassoc } }
+{ $description "Creates a new biassoc using a new assoc of the same type as " { $snippet "exemplar" } " for underlying storage." } ;
+
+HELP: <bihash>
+{ $values { "biassoc" biassoc } }
+{ $description "Creates a new biassoc using a pair of hashtables for underlying storage." } ;
+
+HELP: once-at
+{ $values { "value" object } { "key" object } { "assoc" assoc } }
+{ $description "If the assoc does not contain the given key, adds the key/value pair to the assoc, otherwise does nothing." } ;
+
+ARTICLE: "biassocs" "Bidirectional assocs"
+"A " { $emphasis "bidirectional assoc" } " combines a pair of assocs to form a data structure where both normal assoc opeartions (eg, " { $link at } "), as well as " { $link "assocs-values" } " (eg, " { $link value-at } ") run in sub-linear time."
+$nl
+"Bidirectional assocs implement the entire assoc 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."
+{ $subsection biassoc }
+{ $subsection biassoc? }
+{ $subsection <biassoc> }
+{ $subsection <bihash> } ;
+
+ABOUT: "biassocs"

extra/biassocs/biassocs.factor

@@ -8,7 +8,7 @@ TUPLE: biassoc from to ;
 : <biassoc> ( exemplar -- biassoc )
     [ clone ] [ clone ] bi biassoc boa ;
 
-: <bihash> ( -- bihashtable )
+: <bihash> ( -- biassoc )
     H{ } <biassoc> ;
 
 M: biassoc assoc-size from>> assoc-size ;

extra/biassocs/summary.txt

@@ -0,0 +1 @@
+Bidirectional assocs

extra/biassocs/tags.txt

@@ -0,0 +1 @@
+collections

extra/bitfields/tags.txt

@@ -1,2 +1 @@
-collections
 extensions

extra/lists/tags.txt

@@ -1,3 +1 @@
-cons
+collections
-lists
-sequences