A map is an unordered collection of keys without duplicates, each key having an associated value; with efficient operations to add a key/value pair, remove a key with its value, and to retrieve the value for a key. Adding a key/value pair to a map that already contains it, or removing a key from a map that does not contain it, result in the same map.
Although maps are conceptually unordered, FSet imposes an order for its own purposes. The WB implementation allows you to control this ordering.
Maps have default values that are returned by a lookup on a key that is not in the map;
see Map and Seq Defaults.
The default implementation of maps is currently CHAMP (ch-map). The WB implementation
(wb-map) is also available.
The implementation-specific map constructor functions and macros accept two comparison functions, one for the keys and one for the values. The importance of the former should be obvious, but you might wonder why the latter is needed. FSet uses it in a few ways:
with operation, where the key/value pair being added is already in the
map
range operation, that returns all the values as a set
map-difference and map-difference-2
In most cases, you can just let the value comparison function default to compare.
Occasionally, though, you might need this:
Returns :equal if a and b are equal by eql; otherwise :unequal.
This can be supplied as a value comparison function for a map when the range type is one not handled
by FSet, such as CL hash tables or function objects. It is not recommended for comparing set
or bag values or map keys, as it imposes no ordering, and its associated hash function always
returns 0; if you used it for one of those purposes, FSet would fall back to using lists with linear
search.
The abstract class for FSet functional maps. Subclass of collection.
Returns true iff x is an FSet functional map.
The abstract class for FSet transient maps. Subclass of transient-collection.
Returns true iff x is an FSet transient map.
nil) no-default? ¶Constructor function. Returns an empty map of the default implementation, currently ch-map,
and the default organization. If default is supplied, that will be the map’s default; if no-default? is true, the map will have no default.
Constructor macro. Constructs a map of the default implementation, currently ch-map, and the
default organization, according to the supplied argument subforms. Each argument subform can be a
list of the form (key-expr value-expr), denoting a mapping from the value of
key-expr to the value of value-expr; or a list of the form ($ expression),
in which case the expression must evaluate to a map, denoting all its mappings; or the symbol
:default, followed by a form; or the symbol :no-default. If :default is
supplied, the map’s default is the value of the subsequent form; if
:no-default is supplied, the map has no default; if neither, the map’s default is nil.
As a convenience, if a subform is ($ expression) and the expression evaluates to
nil, it will be treated as an empty map. The result is constructed from the denoted mappings
in left-to-right order; so if a given key is supplied by more than one argument subform, its
associated value will be given by the rightmost such subform.
Functional maps implemented using CHAMP trees. Subclass of map. These print as:
##{| (k0 v0) (k1 v1) ... |}[key-compare-fn;val-compare-fn]/default
Note the double #, which indicates CHAMP, and the vertical bars (“pipes” in Unix-speak)
just inside the braces, which indicate a map. The comparison functions are printed only if they
are not compare. The default is printed only if it is not nil; if the map has no
default, /[no default] is printed.
Returns true iff x is an FSet functional CHAMP map.
nil) no-default? key-compare-fn-name val-compare-fn-name ¶Constructor function. Returns an empty ch-map. If default is supplied, that will be
the map’s default; if no-default? is true, the map will have no
default. key-compare-fn-name and val-compare-fn-name, if supplied, must be symbols
naming the comparison functions to be used for keys and values respectively (these default to
compare). A hash function must have been defined for each comparison function using
define-hash-function.
Constructor macro. Constructs a ch-map according to the supplied argument subforms. See
map, above for the interpretation of subforms.
Constructor macro. Constructs a ch-map with a custom organization according to the supplied
argument subforms. key-compare-fn-name and val-compare-fn-name must be symbols naming
the comparison functions to be used for keys and values respectively (you can use nil as a
synonym of compare). A hash function must have been defined for each comparison function
using define-hash-function.
See map, above for the interpretation of subforms.
Functional maps implemented using WB-trees. Subclass of map. These print as:
#{| (k0 v0) (k1 v1) ... |}[key-compare-fn;val-compare-fn]/default
Note the single #, which indicates WB, and the vertical bars (“pipes” in Unix-speak)
just inside the braces, which indicate a map. The comparison functions are printed only if they are
not compare. The default is printed only if it is not nil; if the map has no
default, /[no default] is printed.
Returns true iff x is an FSet functional WB-tree map.
nil) no-default? key-compare-fn-name val-compare-fn-name ¶Constructor function. Returns an empty wb-map. If default is supplied, that will be
the map’s default; if no-default? is true, the map will have no
default. key-compare-fn-name and val-compare-fn-name, if supplied, must be symbols
naming the comparison functions to be used for keys and values respectively (these default to
compare).
Constructor macro. Constructs a wb-map according to the supplied argument subforms. See
map, above for the interpretation of subforms.
Constructor macro. Constructs a wb-map with a custom organization according to the supplied
argument subforms. key-compare-fn-name and val-compare-fn-name must be symbols naming
the comparison functions to be used for keys and values respectively (you can use nil as a
synonym of compare).
See map, above for the interpretation of subforms.