map result-type function &rest sequences^+ ⇒ result
| result-type | a sequence type specifier, or nil. |
| function | a function designator. function must take as many arguments as there are sequences. |
| sequence | a proper sequence. |
| result | if result-type is a type specifier other than nil, then a sequence of the type it denotes; otherwise (if the result-type is nil), nil. |
Applies function to successive sets of arguments in which
one argument is obtained from each sequence.
The function is called first on all the elements with index 0,
then on all those with index 1, and so on.
The result-type specifies the type of the resulting sequence.
map returns nil if result-type is nil.
Otherwise, map returns
a sequence such that element j is the result
of applying function to element j of each of the
sequences. The result sequence
is as long as the shortest of the
sequences.
The consequences are undefined if the result of applying function
to the successive elements of the sequences cannot
be contained in a sequence of the type given by result-type.
If the result-type is a subtype of list, the result will be a list.
If the result-type is a subtype of vector,
then if the implementation can determine the element type specified
for the result-type, the element type of the resulting array
is the result of upgrading that element type; or, if the
implementation can determine that the element type is unspecified (or *),
the element type of the resulting array is t;
otherwise, an error is signaled.
(map 'string #'(lambda (x y)
(char "01234567890ABCDEF" (mod (+ x y) 16)))
'(1 2 3 4)
'(10 9 8 7)) ⇒ "AAAA"
(setq seq '("lower" "UPPER" "" "123")) ⇒ ("lower" "UPPER" "" "123")
(map nil #'nstring-upcase seq) ⇒ NIL
seq ⇒ ("LOWER" "UPPER" "" "123")
(map 'list #'- '(1 2 3 4)) ⇒ (-1 -2 -3 -4)
(map 'string
#'(lambda (x) (if (oddp x) #\1 #\0))
'(1 2 3 4)) ⇒ "1010"
(map '(vector * 4) #'cons "abc" "de") should signal an error
An error of type type-error must be signaled if the result-type is not a recognizable subtype of list, not a recognizable subtype of vector, and not nil.
Should be prepared to signal an error of type type-error if any sequence is not a proper sequence.
An error of type type-error should be signaled if result-type specifies the number of elements and the minimum length of the sequences is different from that number.