91 lines
4.2 KiB
Plaintext
91 lines
4.2 KiB
Plaintext
! Copyright (C) 2007 Daniel Ehrenberg
|
|
! See http://factorcode.org/license.txt for BSD license.
|
|
USING: assocs sequences help kernel ;
|
|
|
|
ARTICLE: "assocs" "Associative mappings"
|
|
"An associative mapping (abbreviated assoc) is a collection of key/value pairs which provides efficient lookup and storage. Keys are compared for equality."
|
|
$nl
|
|
"Assoc utility words work on any object whose class implements the associative mapping protocol. Words used for manipulating assocs are in the " { $vocab-link "assocs" } " vocabulary."
|
|
{ $subsection "assocs-protocol" }
|
|
{ $subsection "assocs-lookup" }
|
|
{ $subsection "assocs-mutation" }
|
|
{ $subsection "assocs-combinators" }
|
|
{ $subsection "assocs-sets" }
|
|
"Factor provides two implementations of associative mappings in its core, varying in efficiency and use cases."
|
|
{ $subsection "hashtables" }
|
|
{ $subsection "assocs-alists" } ;
|
|
|
|
ARTICLE: "assocs-alists" "Association lists"
|
|
"Certain sequences of sequences of two or more elements can be treated as an " { $emphasis "association list" } ", abbreviated alist. An alist is a type of associative mapping (see " { $link "assocs" } ") and the associative mapping protocol has been implemented on them."
|
|
$nl
|
|
"Association lists come up from time to time; for example, the " { $link cond } " combinator takes an association list of quotations as input. You can perform lookups and take association lists apart using the same words as with any other assoc."
|
|
$nl
|
|
"An association list is slower to search than a hashtable for a large set of associations. The main advantage of an association list is that the elements are ordered; also sometimes it is more convenient to construct an association list with sequence words than to construct a hashtable with assoc words. Much of the time, hashtables are more appropriate. See " { $link "hashtables" } "."
|
|
$nl
|
|
"Note that " { $snippet f } " is an empty sequence and a valid empty association list. Other sequence types which can be used as alists include arrays and vectors."
|
|
$nl
|
|
"A possible literal syntax for alists is"
|
|
{ $code "V{" " { key1 value1 }" " { key2 value2 }" "}" }
|
|
"Alists form a class:"
|
|
{ $subsection alist }
|
|
{ $subsection alist? }
|
|
"To make an assoc into an alist that is an array, use"
|
|
{ $subsection >alist }
|
|
"To make a vector alist, use"
|
|
{ $subsection >valist }
|
|
{ $see-also unpair } ;
|
|
|
|
ARTICLE: "assocs-protocol" "Associative mapping protocol"
|
|
"All associative mappings should implement the following words in order to conform to the assoc protocol. Users can expect all assocs to implement these."
|
|
{ $subsection at* }
|
|
{ $subsection set-at }
|
|
{ $subsection new-assoc }
|
|
{ $subsection assoc-find }
|
|
{ $subsection delete-at }
|
|
{ $subsection clear-assoc }
|
|
{ $subsection assoc-size }
|
|
{ $subsection assoc-like } ;
|
|
|
|
ARTICLE: "assocs-lookup" "Lookup and querying"
|
|
"Below are operations useful for examining the contents of assocs."
|
|
{ $subsection at }
|
|
{ $subsection value-at }
|
|
{ $subsection assoc-empty? }
|
|
{ $subsection assoc-stack }
|
|
{ $subsection key? }
|
|
{ $subsection values }
|
|
{ $subsection keys }
|
|
{ $see-also at* assoc-size } ;
|
|
|
|
ARTICLE: "assocs-sets" "Set-theoretic operations"
|
|
"It is often useful to use the keys of an associative mapping as a set, exploiting the constant or O(log n) lookup time of most implementations, " { $link "assocs-alists" } " being a notable exception. The below words take advantage of this property."
|
|
{ $subsection subassoc? }
|
|
{ $subsection intersect }
|
|
{ $subsection update }
|
|
{ $subsection union }
|
|
{ $subsection remove-all } ;
|
|
|
|
ARTICLE: "assocs-mutation" "Storing keys and values"
|
|
{ $subsection delete-at* }
|
|
{ $subsection at+ }
|
|
{ $see-also set-at delete-at clear-assoc } ;
|
|
|
|
ARTICLE: "assocs-combinators" "Associative mapping combinators"
|
|
"The following combinators can be used on any associative mapping."
|
|
$nl
|
|
"The standard functional programming idioms are as follows."
|
|
{ $subsection assoc-each }
|
|
{ $subsection assoc-map }
|
|
{ $subsection assoc-subset }
|
|
{ $subsection assoc-all? }
|
|
"The curried forms of the above also exist."
|
|
{ $subsection assoc-each-with }
|
|
{ $subsection assoc-map-with }
|
|
{ $subsection assoc-subset-with }
|
|
{ $subsection assoc-all-with? }
|
|
"Three additional combinators are"
|
|
{ $subsection cache }
|
|
{ $subsection map>assoc }
|
|
{ $subsection assoc>map }
|
|
{ $see-also assoc-find } ;
|