This chapter documents the FSet 2 API. All symbols should be accessed via package fset2.
All FSet classes are structure classes. Each has a predicate, whose name is that of the class
followed by a question mark, e.g., set?.
Most FSet abstract types have two implementations (with a possibility of more in the future). There are generic constructor functions and macros, which do not specify an implementation, and do not accept custom comparison or hashing functions; they are recommended for situations in which these details are unimportant. Implementation-specific constructors are also provided that do accept these customizations.
In most cases, operations that require a single collection take it as the first argument. (CL is
itself inconsistent about this; the collection is more commonly the second argument
(e.g. member, assoc), but then there’s aref and elt.) The exceptions
are the higher-order operators image (or map-image), filter, and reduce,
which all take the function to call first, to be consistent with one another and with CL’s
mapcar, remove-if-not, and reduce respectively; and most of the shadowed CL
sequence operations — find etc. (obviously, I
couldn’t change the argument orders of these, if the shadowed versions are to be compatible).
The methods as listed here do not correspond exactly to the ones in the FSet code. In many cases
what I’ve given as one method here is actually two or more, because there are subclasses which have
distinct methods in the code that I’ve treated as one method here. Also, I’ve omitted trailing
t specializers, since they don’t affect method selection, and &key on methods that
don’t actually have any keyword parameters, even though other methods on the same generic function
do.
There is sometimes confusion over the meaning of arb, which returns an
arbitrary element of a set or bag, or an arbitrary pair of a map or binary relation. “Arbitrary”
doesn’t mean “randomly selected”; it simply means that the sole postcondition is that the returned
value is in the collection — FSet may pick any convenient element or pair. In particular,
arb on a given collection instance will always return the same thing; by itself, it doesn’t
iterate — although you can use less to remove the returned element/pair from the
collection, creating a new collection instance on which arb will necessarily return something
different.
This chapter uses the notation [a .. b) for an integer interval inclusive of a and exclusive of b. It also uses “iff” as an abbreviation for “if and only if”.
The root class of the FSet functional collections hierarchy.
Returns true iff x is an FSet functional collection.
Returns true iff x is an FSet transient collection.