diff --git a/core/assocs/assocs-docs.factor b/core/assocs/assocs-docs.factor index 0e1042391c..51293955d5 100755 --- a/core/assocs/assocs-docs.factor +++ b/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 } "." } -{ $notes "This word runs in linear time, proportional to the number of entries in the assoc." } ; +{ $description "Looks up the key associated with a value. No distinction is made between a missing key and a key set to " { $link f } "." } ; + +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" } } diff --git a/core/grouping/grouping-docs.factor b/core/grouping/grouping-docs.factor index f7a37691a6..3b3a98eabd 100644 --- a/core/grouping/grouping-docs.factor +++ b/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 } { $subsection } +"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 } diff --git a/extra/biassocs/authors.txt b/extra/biassocs/authors.txt new file mode 100644 index 0000000000..1901f27a24 --- /dev/null +++ b/extra/biassocs/authors.txt @@ -0,0 +1 @@ +Slava Pestov diff --git a/extra/biassocs/biassocs-docs.factor b/extra/biassocs/biassocs-docs.factor new file mode 100644 index 0000000000..1fde3d05b3 --- /dev/null +++ b/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: +{ $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: +{ $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 } +{ $subsection } ; + +ABOUT: "biassocs" diff --git a/extra/biassocs/biassocs.factor b/extra/biassocs/biassocs.factor index 9f12d04fc4..cd1e57f6ec 100644 --- a/extra/biassocs/biassocs.factor +++ b/extra/biassocs/biassocs.factor @@ -8,7 +8,7 @@ TUPLE: biassoc from to ; : ( exemplar -- biassoc ) [ clone ] [ clone ] bi biassoc boa ; -: ( -- bihashtable ) +: ( -- biassoc ) H{ } ; M: biassoc assoc-size from>> assoc-size ; diff --git a/extra/biassocs/summary.txt b/extra/biassocs/summary.txt new file mode 100644 index 0000000000..84c5b15afc --- /dev/null +++ b/extra/biassocs/summary.txt @@ -0,0 +1 @@ +Bidirectional assocs diff --git a/extra/biassocs/tags.txt b/extra/biassocs/tags.txt new file mode 100644 index 0000000000..42d711b32b --- /dev/null +++ b/extra/biassocs/tags.txt @@ -0,0 +1 @@ +collections diff --git a/extra/bitfields/tags.txt b/extra/bitfields/tags.txt index 9ffc038dbd..f4274299b1 100644 --- a/extra/bitfields/tags.txt +++ b/extra/bitfields/tags.txt @@ -1,2 +1 @@ -collections extensions diff --git a/extra/lists/tags.txt b/extra/lists/tags.txt index e44334b2b5..42d711b32b 100644 --- a/extra/lists/tags.txt +++ b/extra/lists/tags.txt @@ -1,3 +1 @@ -cons -lists -sequences +collections