Next: Alteration of Series Up: Series Functions Previous: Conditional and Other
Common Lisp the Language, 2nd Edition
Next: Alteration of Series
Up: Series Functions
Previous: Conditional and
Other
Collectors produce non-series outputs based on series inputs. They
either create a summary value based on some formula (the sum, for
example) or collect the elements of a series in an aggregate data
structure (such as a list).
[Function]
collect-firstitems&optional (defaultnil)
collect-lastitems&optional (defaultnil)
collect-nthnitems&optional (defaultnil)
Given a series items, these functions return the first
element, the last element, and the nth element, respectively.
If items has no elements (or no nth element),
default is returned. If default is not specified, then
nil is used for default.
(collect-first #Z() 'z) => z
(collect-last #Z(a b c)) => c
(collect-nth 1 #Z(a b c)) => b[Function]
collect-lengthitems
collect-length returns the number of elements in a
series.
(collect-length #Z(a b c)) => 3[Function]
collect-sumnumbers&optional (type'number)
collect-sum returns the sum of the elements in a series
of numbers. The type is a type specifier that indicates the
type of sum to be created. If type is not specified, then
number is used for the type. If there are no
elements in the input, a zero (of the appropriate type) is returned.
(collect-sum #Z(1.1 1.2 1.3)) => 3.6
(collect-sum #Z() 'complex) => #C(0 0)[Function]
collect-maxnumbers
collect-minnumbers
Given a series of non-complex numbers, these functions compute the
maximum element and the minimum element, respectively. If there are no
elements in the input, nil is returned.
(collect-max #Z(2 1 4 3)) => 4
(collect-min #Z(1.2 1.1 1.4 1.3)) => 1.1
(collect-min #Z()) => nil[Function]
collect-andbools
collect-and returns the and of the elements
in a series. As with the macro and, nil is
returned if any element of bools is nil.
Otherwise, the last element of bools is returned. The value
t is returned if there are no elements in
bools.
(collect-and #Z(a b c)) => c
(collect-and #Z(a nil c)) => nil[Function]
collect-orbools
collect-or returns the or of the elements
in a series. As with the macro or, nil is
returned if every element of bools is nil.
Otherwise, the first non-null element of bools is returned. The
value nil is returned if there are no elements in
bools.
(collect-or #Z(nil b c)) => b
(collect-or #Z()) => nil[Function]
collectitems
collecttypeitems
collect returns a sequence containing the elements of
the series items. The type is a type specifier
indicating the type of sequence to be created. It must be either a
proper subtype of sequence or the symbol bag.
If type is omitted, it defaults to list. (This
function exhibits an argument pattern that is unusual for Common Lisp:
an ``optional’’ argument preceding a required argument. This pattern
cannot be expressed in the usual manner with &optional.
It is indicated above by two definition lines, showing the two possible
argument patterns.)
If the type is bag, a list is created with the
elements in whatever order can be most efficiently obtained. Otherwise,
the order of the elements in the sequence is the same as the order in
items. If type specifies a length (that is, of a
vector) this length must be greater than or equal to the length of
items.
The nth element of items is placed in the
nth slot of the sequence produced. Any unneeded slots are left
in their initial state. Collecting is significantly more efficient if it
can be determined at compile time whether type is a subtype of
list or vector and for vectors what the length
of the vector is.
(collect #Z(a b c)) => (a b c)
(collect 'bag #Z(a b c)) => (c a b) or (b a c) or ...
(collect '(vector integer 3) #Z(1 2 3)) => #(1 2 3)[Function]
collect-appendsequences
collect-appendtypesequences
Given a series of sequences, collect-append returns a
new sequence by concatenating these sequences together in order. The
type is a type specifier indicating the type of sequence
created and must be a proper subtype of sequence. If
type is omitted, it defaults to list. (This
function exhibits an argument pattern that is unusual for Common Lisp:
an ``optional’’ argument preceding a required argument. This pattern
cannot be expressed in the usual manner with &optional.
It is indicated above by two definition lines, showing the two possible
argument patterns.)
It must be possible for every element of every sequence in the input series to be an element of a sequence of type type. The result does not share any structure with the sequences in the input.
(collect-append #Z((a b) nil (c d))) => (a b c d)
(collect-append 'string #Z("a " "big " "cat")) => "a big cat"[Function]
collect-nconclists
collect-nconc nconcs the elements of the series
lists together in order and returns the result. This is the
same as collect-append except that the input must be a
series of lists, the output is always a list, the concatenation is done
rapidly by destructively modifying the input elements, and therefore the
output shares all of its structure with the input elements.
[Function]
collect-alistkeysvalues
collect-plistkeysvalues
collect-hashkeysvalues&key :test :size :rehash-size :rehash-threshold
Given a series of keys and a series of corresponding values, these
functions return an association list, a property list, and a hash table,
respectively. Following the order of the input, each keys
-values pair is entered into the output
so that it overrides all earlier associations. If one of the input
series is longer than the other, the extra elements are ignored. The
keyword arguments of collect-hash specify attributes of the
hash table produced and have the same meanings as the arguments to
make-hash-table.
(collect-alist #Z(a b c) #Z(1 2)) => ((b . 2) (a . 1))
(collect-plist #Z(a b c) #Z(1 2)) => (b 2 a 1)
(collect-hash #Z() #Z(1 2) :test #'eq) => an empty hash table[Function]
collect-filefile-nameitems&optional (printer#'print)
This creates a file named file-name and writes the elements
of the series items into it using the function
printer. Printer must accept two inputs: an object and
an output stream. (For instance, printer can be
print, prin1, princ,
pprint, write-char, write-string,
or write-line.) If omitted, printer defaults to
print. The value t is returned. The file is
correctly closed, even if an abort occurs.
[Function]
collect-fntypeinitfunction&restseries-inputs
The higher-order function collect-fn supports the
general concept of collecting. It is identical to
collecting-fn except that it returns only the last element
of each series computed. If there are no elements in these series, the
values returned by init are passed on directly as the output of
collect-fn.
(collect-fn 'integer #'(lambda () 0) #'+ #Z(1 2 3)) => 6
(collect-fn 'integer #'(lambda () 0) #'+ #Z()) => 0
(collect-fn 'integer #'(lambda () 1) #'* #Z(1 2 3 4 5)) => 120
Next: Alteration of Series
Up: Series Functions
Previous: Conditional and
Other
AI.Repository@cs.cmu.edu