document all assoc words
parent
b9932828f0
commit
853da3a116
|
@ -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
|
||||
|
|
|
@ -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*
|
||||
|
|
Loading…
Reference in New Issue