---

8 Generic Function convert ¶

The convert generic function provides convenient conversions between many FSet types. It is called with the first argument to-type being a symbol — normally a quoted constant — that specifies the target type of the conversion, and the second argument being the collection to be converted. (This is the opposite order from cl:coerce.) Many methods have additional keyword parameters to further specify details of the conversion.

When to-type is one of the abstract types – set, bag, map etc. – the only guarantee is that convert will return an instance of the requested type. The choices of implementation and organization are up to FSet, and there’s no option to request a specific organization. In contrast, when to-type is one of the concrete types – wb-set, ch-set, wb-map, etc. – the convert method accepts keyword arguments specifying the organization (e.g. compare-fn-name), and guarantees to return a collection of that type and organization; including the case where no organization is specified, in which convert is guaranteed to return a collection of the default organization (the one using fset:compare).

Method summary:

to-type (symbol)	collection type	notes
set	set	0
ch-set	set	15
ch-set	ch-set	0, 15
wb-set	set	0, 15
wb-set	wb-set	0, 15
set	list	2
ch-set	list	15
wb-set	list	15, 18
set	seq	2
ch-set	seq	15
wb-set	seq	15, 18
set	sequence	2, 21
ch-set	sequence	15, 21
wb-set	sequence	15, 18, 21
list	set
vector	set
bag	bag	0
ch-bag	bag	15
ch-bag	ch-bag	0, 15
wb-bag	bag	15
wb-bag	wb-bag	0, 15
bag	set	2
bag	wb-set	1
ch-bag	set	15
ch-bag	ch-set	9, 15
wb-bag	set	15
wb-bag	wb-set	9, 15
set	wb-bag	1
wb-set	wb-bag	15
set	ch-bag	2
ch-set	ch-bag	15
bag	list	2, 3, 4
ch-bag	list	3, 4, 15
wb-bag	list	3, 4, 15, 18
bag	seq	2, 3
ch-bag	seq	3, 15
wb-bag	seq	3, 15, 18
bag	sequence	1, 3, 21
ch-bag	sequence	3, 21
wb-bag	sequence	3, 15, 18, 21
list	bag	3
seq	bag	3
vector	bag	3
alist	bag
map	map	0
ch-map	map	16, 20
wb-map	map	16, 20
ch-map	ch-map	0, 16, 20
wb-map	wb-map	0, 16, 20
map	list	2, 6, 7, 18, 19
ch-map	list	6, 7, 16, 19
wb-map	list	6, 7, 16, 18, 19
map	seq	2, 6, 7, 19
ch-map	seq	6, 7, 16, 19
wb-map	seq	6, 7, 16, 18, 19
map	sequence	2, 6, 7, 19, 21
ch-map	sequence	6, 7, 16, 19, 21
wb-map	sequence	6, 7, 16, 18, 19, 21
map	bag	2, 19
ch-map	bag	16, 19
wb-map	bag	16, 19
map	hash-table	2, 19
ch-map	hash-table	16, 19
wb-map	hash-table	16, 19
set	map	2, 5
list	map	5
alist	map
seq	map	5
vector	map	5
hash-table	map	8
seq	seq	0
wb-seq	wb-seq	0
seq	list	1, 9, 23
wb-seq	list	9, 23
seq	vector	1, 9
wb-seq	vector	9
seq	set	1
wb-seq	set
seq	bag	1, 3, 5
wb-seq	bag	3, 5
seq	map	1, 5, 19
wb-seq	map	5, 19
list	wb-seq
vector	wb-seq
string	wb-seq	14
base-string	wb-seq	14
2-relation	2-relation	0
ch-2-relation	ch-2-relation	0, 16
wb-2-relation	wb-2-relation	0, 16
2-relation	set	6, 2
ch-2-relation	set	6, 16
wb-2-relation	set	6, 16
set	ch-2-relation	2, 5
set	wb-2-relation	1, 5
ch-set	2-relation	5
wb-set	2-relation	5
2-relation	ch-map	2, 10
ch-2-relation	ch-map	2, 10, 16
2-relation	wb-map	1, 10
wb-2-relation	wb-map	10, 16
2-relation	list	2, 6
ch-2-relation	list	6, 16
wb-2-relation	list	6, 16
2-relation	seq	2, 6
ch-2-relation	seq	6, 16
wb-2-relation	seq	6, 16
map	wb-2-relation	1, 11, 19
map	ch-2-relation	2, 11, 19
wb-map	wb-2-relation	11, 16, 19
ch-map	ch-2-relation	11, 16, 19
map-to-sets	ch-2-relation	12
map-to-sets	wb-2-relation	12
list	2-relation	5
tuple	tuple	0
dyn-tuple	dyn-tuple	0
map	tuple	2
ch-map	tuple	16
wb-map	tuple	16
tuple	map	13, 17
dyn-tuple	map	17
list	tuple	5
tuple	list	6, 7, 13
dyn-tuple	list	7
replay-set	replay-set	0
wb-replay-set	replay-set	15
ch-replay-set	replay-set	15
wb-replay-set	wb-replay-set	0, 15
ch-replay-set	ch-replay-set	0, 15
seq	replay-set	1, 22
wb-seq	replay-set	22
set	ch-replay-set	2, 22
ch-set	ch-replay-set	15, 22
set	wb-replay-set	1, 22
wb-set	wb-replay-set	15, 22
replay-set	list	2
ch-replay-set	list	15
wb-replay-set	list	15
replay-set	seq	2
ch-replay-set	seq	15
wb-replay-set	seq	15
replay-set	sequence	2, 21
ch-replay-set	sequence	15, 21
wb-replay-set	sequence	15, 21
list	replay-set
vector	replay-set
replay-map	replay-map	0
wb-replay-map	wb-replay-map	0
ch-replay-map	ch-replay-map	0
map	wb-replay-map	1
map	ch-replay-map	2
wb-map	wb-replay-map
ch-map	ch-replay-map
replay-map	list	2, 6
wb-replay-map	list	6
replay-map	seq	2, 6
wb-replay-map	seq	6
replay-map	sequence	2, 6, 21
wb-replay-map	sequence	6, 21
list	replay-map	5, 24
vector	replay-map	5, 24
seq	replay-map	5, 19, 24
wb-seq	replay-map	5, 19, 24
list	list	0
vector	vector	0
list	sequence	21
vector	sequence	21
string	sequence	21
base-string	sequence	21

Notes:

0. Identity conversion, provided for convenience. (If the method also accepts an organization, then it performs the identity conversion only if the organization of the argument matches that requested.)
1. Constructs the WB-tree implementation of its type (wb-set etc.).
2. Constructs the CHAMP implementation of its type (ch-set etc.).
3. Has keyword parameter pairs?. If true, treats the input elements as pairs (represented as conses) of a value and a count (multiplicity).
4. Has keyword parameter from-type. If it’s the symbol alist, treats the input elements as pairs (as conses) of a value and a count. Deprecated; use pairs?.
5. Has keyword parameter pair-fn, defaulting to #'cons, which specifies the function used to combine each key/value pair.
6. Has keyword parameters key-fn and value-fn, used to extract a key/value pair from each input element. Defaults are #'car and #'cdr.
7. If a key occurs more than once in the input, the result will have the value associated with the last occurrence.
8. All keyword arguments are forwarded to make-hash-table.
9. Optimized O(n) algorithm.
10. Has keyword parameter from-type. If it’s the symbol map-to-sets, the range elements must all be sets, and the result pairs each domain element with each element of the corresponding range set. Otherwise, the result pairs each domain element with the corresponding range element directly.
11. The relation must be a function (must have only one range value per domain value). See Method conflicts (2-relation).
12. Returns a map mapping each domain value to the set of corresponding range values. The default of the result is the empty set.
13. Constructs a dyn-tuple.
14. Always returns a string (or base-string, if specified). Signals a non-char-seq-error if the seq contains a non-character. Signals a type-error if a base-string is specified and it encounters a non-base character.
15. Has keyword parameter compare-fn-name. If nonnull, must be a symbol, the name of the comparison function to be used. The returned set will be converted, if necessary, to use the specified function, or to use compare if one is not specified.
16. Has keyword parameters key-compare-fn-name band val-compare-fn-name. If nonnull, these must be symbols, the names of the key and value comparison functions, respectively, to be used. The returned map will be converted, if necessary, to use the specified functions, or to use compare for those not specified.
17. Has keyword parameter autokey?. if true, then any keys of the map that are not instances of tuple-key are automatically converted to such instances using get-tuple-key.
18. Has keyword parameter input-sorted?. If true, uses an algorithm optimized for the case where the input is sorted: it runs in O(n) time and is much faster, but is substantially slower than the default algorithm if the input is completely unsorted. “Sorted” here means that the input is in the same order as the collection being built. The algorithm’s correctness doesn’t depend on the sorting, only its performance; so it’s okay if a few elements are out of order.
19. Has keyword parameter default, which specifies the default of the result; if not supplied, the default is nil. Also has keyword parameter no-default? to specify no default.
20. Has keyword parameter default, which specifies the default of the result; if not supplied, the default is the same as that of the argument. Also has keyword parameter no-default? to specify no default.
21. sequence here refers to a CL sequence – either a list or a vector, unless the implementation has more sequence subtypes. FSet’s seq is not a subtype of sequence.
22. O(1), provided the implementation and organization, if applicable, are unchanged.
23. Has keyword parameter reverse?, which if true, reverses the order.
24. Has keyword parameter keys-only?; if true, converts the key sequence to the target type, omitting the values and ignoring pair-fn. If it’s true and to-type is seq or wb-seq, the conversion is O(1).