Maps

Functions in this category take a transforming function, which is then applied sequentially to each or selected elements of the input list. The results are collected in order and returned as a new list.

Function: -map (fn list)

Apply fn to each item in list and return the list of results.

This function’s anaphoric counterpart is --map.

(-map (lambda (num) (* num num)) '(1 2 3 4))
    ⇒ (1 4 9 16)

(-map #'1+ '(1 2 3 4))
    ⇒ (2 3 4 5)

(--map (* it it) '(1 2 3 4))
    ⇒ (1 4 9 16)

Function: -map-when (pred rep list)

Use pred to conditionally apply rep to each item in list. Return a copy of list where the items for which pred returns nil are unchanged, and the rest are mapped through the rep function.

Alias: -replace-where

See also: -update-at (see -update-at)

(-map-when 'even? 'square '(1 2 3 4))
    ⇒ (1 4 3 16)

(--map-when (> it 2) (* it it) '(1 2 3 4))
    ⇒ (1 2 9 16)

(--map-when (= it 2) 17 '(1 2 3 4))
    ⇒ (1 17 3 4)

Function: -map-first (pred rep list)

Use pred to determine the first item in list to call rep on. Return a copy of list where the first item for which pred returns non-nil is replaced with the result of calling rep on that item.

See also: -map-when (see -map-when), -replace-first (see -replace-first)

(-map-first 'even? 'square '(1 2 3 4))
    ⇒ (1 4 3 4)

(--map-first (> it 2) (* it it) '(1 2 3 4))
    ⇒ (1 2 9 4)

(--map-first (= it 2) 17 '(1 2 3 2))
    ⇒ (1 17 3 2)

Function: -map-last (pred rep list)

Use pred to determine the last item in list to call rep on. Return a copy of list where the last item for which pred returns non-nil is replaced with the result of calling rep on that item.

See also: -map-when (see -map-when), -replace-last (see -replace-last)

(-map-last 'even? 'square '(1 2 3 4))
    ⇒ (1 2 3 16)

(--map-last (> it 2) (* it it) '(1 2 3 4))
    ⇒ (1 2 3 16)

(--map-last (= it 2) 17 '(1 2 3 2))
    ⇒ (1 2 3 17)

Function: -map-indexed (fn list)

Apply fn to each index and item in list and return the list of results. This is like -map (see -map), but fn takes two arguments: the index of the current element within list, and the element itself.

This function’s anaphoric counterpart is --map-indexed.

For a side-effecting variant, see also -each-indexed (see -each-indexed).

(-map-indexed (lambda (index item) (- item index)) '(1 2 3 4))
    ⇒ (1 1 1 1)

(--map-indexed (- it it-index) '(1 2 3 4))
    ⇒ (1 1 1 1)

(-map-indexed #'* '(1 2 3 4))
    ⇒ (0 2 6 12)

Function: -annotate (fn list)

Pair each item in list with the result of passing it to fn.

Return an alist of (result . item), where each item is the corresponding element of list, and result is the value obtained by calling fn on item.

This function’s anaphoric counterpart is --annotate.

(-annotate #'1+ '(1 2 3))
    ⇒ ((2 . 1) (3 . 2) (4 . 3))

(-annotate #'length '((f o o) (bar baz)))
    ⇒ ((3 f o o) (2 bar baz))

(--annotate (> it 1) '(0 1 2 3))
    ⇒ ((nil . 0) (nil . 1) (t . 2) (t . 3))

Function: -splice (pred fun list)

Splice lists generated by fun in place of items satisfying pred in list.

Call pred on each element of list. Whenever the result of pred is nil, leave that it as-is. Otherwise, call fun on the same it that satisfied pred. The result should be a (possibly empty) list of items to splice in place of it in list.

This can be useful as an alternative to the ,@ construct in a ` structure, in case you need to splice several lists at marked positions (for example with keywords).

This function’s anaphoric counterpart is --splice.

See also: -splice-list (see -splice-list), -insert-at (see -insert-at).

(-splice #'numberp (lambda (n) (list n n)) '(a 1 b 2))
    ⇒ (a 1 1 b 2 2)

(--splice t (list it it) '(1 2 3 4))
    ⇒ (1 1 2 2 3 3 4 4)

(--splice (eq it :magic) '((magical) (code)) '((foo) :magic (bar)))
    ⇒ ((foo) (magical) (code) (bar))

Function: -splice-list (pred new-list list)

Splice new-list in place of elements matching pred in list.

See also: -splice (see -splice), -insert-at (see -insert-at)

(-splice-list 'keywordp '(a b c) '(1 :foo 2))
    ⇒ (1 a b c 2)

(-splice-list 'keywordp nil '(1 :foo 2))
    ⇒ (1 2)

(--splice-list (keywordp it) '(a b c) '(1 :foo 2))
    ⇒ (1 a b c 2)

Function: -mapcat (fn list)

Return the concatenation of the result of mapping fn over list. Thus function fn should return a list.

(-mapcat 'list '(1 2 3))
    ⇒ (1 2 3)

(-mapcat (lambda (item) (list 0 item)) '(1 2 3))
    ⇒ (0 1 0 2 0 3)

(--mapcat (list 0 it) '(1 2 3))
    ⇒ (0 1 0 2 0 3)

Function: -copy (list)

Create a shallow copy of list. The elements of list are not copied; they are shared with the original.

(-copy '(1 2 3))
    ⇒ (1 2 3)

(let ((a '(1 2 3))) (eq a (-copy a)))
    ⇒ nil