map

map Function

Syntax:

map result-type function &rest sequences⁺ → result

Arguments and Values:

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.

Description:

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.

Examples:

(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 

Exceptional Situations:

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.

See Also:

Section 3.6 (Traversal Rules and Side Effects)

map-into

Expanded Reference: map

Mapping a function over a sequence

map applies a function to successive elements of one or more sequences and collects the results into a new sequence of the specified type.

(map 'list #'1+ '(1 2 3 4))
=> (2 3 4 5)
(map 'vector #'char-upcase "hello")
=> #(#\H #\E #\L #\L #\O)

Mapping with nil result type (for side effects only)

When the result type is nil, map calls the function for side effects and returns NIL.

(map nil #'print '(1 2 3))
; 1
; 2
; 3
=> NIL

Mapping over multiple sequences

When multiple sequences are given, the function receives one argument from each sequence. Iteration stops at the shortest sequence.

(map 'list #'+ '(1 2 3) '(10 20 30))
=> (11 22 33)
(map 'list #'list '(a b c) '(1 2 3))
=> ((A 1) (B 2) (C 3))
(map 'list #'+ '(1 2 3 4) '(10 20))
=> (11 22)

Mapping to a string result

(map 'string #'char-upcase "hello world")
=> "HELLO WORLD"
(map 'string (lambda (x) (if (oddp x) #\1 #\0)) '(1 2 3 4))
=> "1010"

Practical example: zipping two lists

(map 'list #'cons '(a b c) '(1 2 3))
=> ((A . 1) (B . 2) (C . 3))