From 853da3a116e6dbe47380a5eef7be71f226825b99 Mon Sep 17 00:00:00 2001 From: Doug Coleman Date: Fri, 5 Sep 2008 15:52:13 -0500 Subject: [PATCH] document all assoc words --- core/assocs/assocs-docs.factor | 124 +++++++++++++++++++++++++++++++-- core/assocs/assocs.factor | 2 +- 2 files changed, 119 insertions(+), 7 deletions(-) diff --git a/core/assocs/assocs-docs.factor b/core/assocs/assocs-docs.factor index 67bd860732..f969b208eb 100755 --- a/core/assocs/assocs-docs.factor +++ b/core/assocs/assocs-docs.factor @@ -1,7 +1,7 @@ -! Copyright (C) 2007 Daniel Ehrenberg and Slava Pestov +! Copyright (C) 2007 Daniel Ehrenberg, Slava Pestov, and Doug Coleman ! See http://factorcode.org/license.txt for BSD license. USING: help.markup help.syntax kernel sequences -sequences.private namespaces math ; +sequences.private namespaces math quotations ; IN: assocs ARTICLE: "alists" "Association lists" @@ -81,6 +81,7 @@ ARTICLE: "assocs-sets" "Set-theoretic operations on assocs" { $subsection remove-all } { $subsection substitute } { $subsection substitute-here } +{ $subsection extract-keys } { $see-also key? assoc-contains? assoc-all? "sets" } ; ARTICLE: "assocs-mutation" "Storing keys and values in assocs" @@ -89,7 +90,18 @@ ARTICLE: "assocs-mutation" "Storing keys and values in assocs" { $subsection rename-at } { $subsection change-at } { $subsection at+ } -{ $see-also set-at delete-at clear-assoc } ; +{ $see-also set-at delete-at clear-assoc push-at } ; + +ARTICLE: "assocs-conversions" "Associative mapping conversions" +"Converting to other assocs:" +{ $subsection assoc-clone-like } +"Combining a sequence of assocs into a single assoc:" +{ $subsection assoc-combine } +"Creating an assoc from key/value sequences:" +{ $subsection zip } +"Creating key/value sequences from an assoc:" +{ $subsection unzip } +; ARTICLE: "assocs-combinators" "Associative mapping combinators" "The following combinators can be used on any associative mapping." @@ -104,10 +116,14 @@ $nl { $subsection assoc-filter } { $subsection assoc-contains? } { $subsection assoc-all? } -"Three additional combinators:" +"Additional combinators:" { $subsection cache } { $subsection map>assoc } -{ $subsection assoc>map } ; +{ $subsection assoc>map } +{ $subsection assoc-map-as } +{ $subsection search-alist } +"Utility word:" +{ $subsection assoc-pusher } ; ARTICLE: "assocs" "Associative mapping operations" "An " { $emphasis "associative mapping" } ", abbreviated " { $emphasis "assoc" } ", is a collection of key/value pairs which provides efficient lookup and storage indexed by key." @@ -121,7 +137,8 @@ $nl { $subsection "assocs-values" } { $subsection "assocs-mutation" } { $subsection "assocs-combinators" } -{ $subsection "assocs-sets" } ; +{ $subsection "assocs-sets" } +{ $subsection "assocs-conversions" } ; ABOUT: "assocs" @@ -204,6 +221,8 @@ HELP: assoc-map } } ; +{ assoc-map assoc-map-as } related-words + HELP: assoc-push-if { $values { "accum" "a resizable mutable sequence" } { "quot" "a quotation with stack effect " { $snippet "( key value -- ? )" } } { "key" object } { "value" object } } { $description "If the quotation yields true when applied to the key/value pair, adds the key/value pair at the end of " { $snippet "accum" } "." } ; @@ -334,3 +353,96 @@ HELP: >alist { $values { "assoc" assoc } { "newassoc" "an array of key/value pairs" } } { $contract "Converts an associative structure into an association list." } { $notes "The " { $link assoc } " mixin has a default implementation for this generic word which constructs the association list by iterating over the assoc with " { $link assoc-find } "." } ; + +HELP: assoc-clone-like +{ $values + { "assoc" assoc } { "exemplar" assoc } + { "newassoc" assoc } } +{ $description "Outputs a newly-allocated assoc with the same elements as " { $snippet "assoc" } "." } +{ $examples { $example "USING: prettyprint assocs hashtables ;" "H{ { 1 2 } { 3 4 } } { } assoc-clone-like ." "{ { 1 2 } { 3 4 } }" } } ; + +HELP: assoc-combine +{ $values + { "seq" "a sequence of assocs" } + { "union" assoc } } +{ $description "Takes the union of all of the " { $snippet "assocs" } " in " { $snippet "seq" } "." } +{ $examples { $example "USING: prettyprint assocs ;" "{ H{ { 1 2 } } H{ { 3 4 } } } assoc-combine ." "H{ { 1 2 } { 3 4 } }" } } ; + +HELP: assoc-map-as +{ $values + { "assoc" assoc } { "quot" quotation } { "exemplar" assoc } + { "newassoc" assoc } } +{ $description "Applies the quotation to each entry in the input assoc and collects the results in a new assoc of the stame type as the exemplar." } +{ $examples { $example "USING: prettyprint assocs hashtables math ;" " H{ { 1 2 } { 3 4 } } [ sq ] { } assoc-map-as ." "{ { 1 4 } { 3 16 } }" } } ; + +HELP: assoc-pusher +{ $values + { "quot" "a predicate quotation" } + { "quot'" quotation } { "accum" assoc } } +{ $description "Creates a new " { $snippet "assoc" } " to accumulate the key/value pairs which return true for a predicate. Returns a new quotation which accepts a pair of object to be tested and stored in the accumulator if the test yields true. The accumulator is left on the stack for convenience." } +{ $example "! Find only the pairs that sum to 5:" "USING: prettyprint assocs math kernel ;" + "{ { 1 2 } { 2 3 } { 3 4 } } [ + 5 = ] assoc-pusher [ assoc-each ] dip ." + "V{ { 2 3 } }" +} +{ $notes "Used to implement the " { $link assoc-filter } " word." } ; + + +HELP: extract-keys +{ $values + { "seq" sequence } { "assoc" assoc } + { "subassoc" assoc } } +{ $description "Outputs an new " { $snippet "assoc" } " with key/value pairs whose keys match the elements in the input " { $snippet "seq" } "." } +{ $examples + { $example "USING: prettyprint assocs ;" + "{ 1 3 } { { 1 10 } { 2 20 } { 3 30 } } extract-keys ." + "{ { 1 10 } { 3 30 } }" + } +} ; + +HELP: push-at +{ $values + { "value" object } { "key" object } { "assoc" assoc } } +{ $description "Pushes the " { $snippet "value" } " onto a " { $snippet "vector" } " stored at the " { $snippet "key" } " in the " { $snippet "assoc" } ". If the " { $snippet "key" } " does not yet exist, creates a new " { $snippet "vector" } " at that " { $snippet "key" } " and pushes the " { $snippet "value" } "." } +{ $examples { $example "USING: prettyprint assocs kernel ;" +"H{ { \"cats\" V{ \"Mittens\" } } } \"Mew\" \"cats\" pick push-at ." +"H{ { \"cats\" V{ \"Mittens\" \"Mew\" } } }" +} } ; + +HELP: search-alist +{ $values + { "key" object } { "alist" "an array of key/value pairs" } + { "pair/f" "a key/value pair" } { "i/f" integer } } +{ $description "Performs an in-order traversal of a " { $snippet "alist" } " and stops when the key is matched or the end of the " { $snippet "alist" } " has been reached. If there is no match, both outputs are " { $link f } "." } +{ $examples { $example "USING: prettyprint assocs kernel ;" + "3 { { 1 2 } { 3 4 } } search-alist [ . ] bi@" + "{ 3 4 }\n1" + } { $example "USING: prettyprint assocs kernel ;" + "6 { { 1 2 } { 3 4 } } search-alist [ . ] bi@" + "f\nf" + } +} ; + +HELP: unzip +{ $values + { "assoc" assoc } + { "keys" sequence } { "values" sequence } } +{ $description "Outputs an array of keys and an array of values of the input " { $snippet "assoc" } "." } +{ $examples + { $example "USING: prettyprint assocs kernel ;" + "{ { 1 4 } { 2 5 } { 3 6 } } unzip [ . ] bi@" + "{ 1 2 3 }\n{ 4 5 6 }" + } +} ; + +HELP: zip +{ $values + { "keys" sequence } { "values" sequence } + { "alist" "an array of key/value pairs" } } +{ $description "Combines two sequences pairwise into a single sequence of key/value pairs." } +{ $examples + { $example "" "USING: prettyprint assocs ;" + "{ 1 2 3 } { 4 5 6 } zip ." + "{ { 1 4 } { 2 5 } { 3 6 } }" + } +} ; +{ unzip zip } related-words diff --git a/core/assocs/assocs.factor b/core/assocs/assocs.factor index 7415bd0eb2..9b8065e6c4 100755 --- a/core/assocs/assocs.factor +++ b/core/assocs/assocs.factor @@ -164,7 +164,7 @@ M: assoc value-at* swap [ = nip ] curry assoc-find nip ; : unzip ( assoc -- keys values ) dup assoc-empty? [ drop { } { } ] [ >alist flip first2 ] if ; -: search-alist ( key alist -- pair i ) +: search-alist ( key alist -- pair/f i/f ) [ first = ] with find swap ; inline M: sequence at*