Function combinators

Functions that manipulate and compose other functions.

Function: -partial (fun &rest args)

Return a function that is a partial application of fun to args. args is a list of the first n arguments to pass to fun. The result is a new function which does the same as fun, except that the first n arguments are fixed at the values with which this function was called.

(funcall (-partial #'+ 5))
    ⇒ 5

(funcall (-partial #'- 5) 3)
    ⇒ 2

(funcall (-partial #'+ 5 2) 3)
    ⇒ 10

Function: -rpartial (fn &rest args)

Return a function that is a partial application of fn to args. args is a list of the last n arguments to pass to fn. The result is a new function which does the same as fn, except that the last n arguments are fixed at the values with which this function was called. This is like -partial (see -partial), except the arguments are fixed starting from the right rather than the left.

(funcall (-rpartial #'- 5))
    ⇒ -5

(funcall (-rpartial #'- 5) 8)
    ⇒ 3

(funcall (-rpartial #'- 5 2) 10)
    ⇒ 3

Function: -juxt (&rest fns)

Return a function that is the juxtaposition of fns. The returned function takes a variable number of args, applies each of fns in turn to args, and returns the list of results.

(funcall (-juxt) 1 2)
    ⇒ ()

(funcall (-juxt #'+ #'- #'* #'/) 7 5)
    ⇒ (12 2 35 1)

(mapcar (-juxt #'number-to-string #'1+) '(1 2))
    ⇒ (("1" 2) ("2" 3))

Function: -compose (&rest fns)

Compose fns into a single composite function. Return a function that takes a variable number of args, applies the last function in fns to args, and returns the result of calling each remaining function on the result of the previous function, right-to-left. If no fns are given, return a variadic identity function.

(funcall (-compose #'- #'1+ #'+) 1 2 3)
    ⇒ -7

(funcall (-compose #'identity #'1+) 3)
    ⇒ 4

(mapcar (-compose #'not #'stringp) '(nil ""))
    ⇒ (t nil)

Function: -applify (fn)

Return a function that applies fn to a single list of args. This changes the arity of fn from taking n distinct arguments to taking 1 argument which is a list of n arguments.

(funcall (-applify #'+) nil)
    ⇒ 0

(mapcar (-applify #'+) '((1 1 1) (1 2 3) (5 5 5)))
    ⇒ (3 6 15)

(funcall (-applify #'<) '(3 6))
    ⇒ t

Function: -on (op trans)

Return a function that calls trans on each arg and op on the results. The returned function takes a variable number of arguments, calls the function trans on each one in turn, and then passes those results as the list of arguments to op, in the same order.

For example, the following pairs of expressions are morally equivalent:

(funcall (-on #’+ #’1+) 1 2 3) = (+ (1+ 1) (1+ 2) (1+ 3)) (funcall (-on #’+ #’1+)) = (+)

(-sort (-on #'< #'length) '((1 2 3) (1) (1 2)))
    ⇒ ((1) (1 2) (1 2 3))

(funcall (-on #'min #'string-to-number) "22" "2" "1" "12")
    ⇒ 1

(-min-by (-on #'> #'length) '((1 2 3) (4) (1 2)))
    ⇒ (4)

Function: -flip (fn)

Return a function that calls fn with its arguments reversed. The returned function takes the same number of arguments as fn.

For example, the following two expressions are morally equivalent:

(funcall (-flip #’-) 1 2) = (- 2 1)

See also: -rotate-args (see -rotate-args).

(-sort (-flip #'<) '(4 3 6 1))
    ⇒ (6 4 3 1)

(funcall (-flip #'-) 3 2 1 10)
    ⇒ 4

(funcall (-flip #'1+) 1)
    ⇒ 2

Function: -rotate-args (n fn)

Return a function that calls fn with args rotated n places to the right. The returned function takes the same number of arguments as fn, rotates the list of arguments n places to the right (left if n is negative) just like -rotate (see -rotate), and applies fn to the result.

See also: -flip (see -flip).

(funcall (-rotate-args -1 #'list) 1 2 3 4)
    ⇒ (2 3 4 1)

(funcall (-rotate-args 1 #'-) 1 10 100)
    ⇒ 89

(funcall (-rotate-args 2 #'list) 3 4 5 1 2)
    ⇒ (1 2 3 4 5)

Function: -const (c)

Return a function that returns c ignoring any additional arguments.

In types: a -> b -> a

(funcall (-const 2) 1 3 "foo")
    ⇒ 2

(mapcar (-const 1) '("a" "b" "c" "d"))
    ⇒ (1 1 1 1)

(-sum (mapcar (-const 1) '("a" "b" "c" "d")))
    ⇒ 4

Macro: -cut (&rest params)

Take n-ary function and n arguments and specialize some of them. Arguments denoted by <> will be left unspecialized.

See srfi-26 for detailed description.

(funcall (-cut list 1 <> 3 <> 5) 2 4)
    ⇒ (1 2 3 4 5)

(-map (-cut funcall <> 5) `(1+ 1- ,(lambda (x) (/ 1.0 x))))
    ⇒ (6 4 0.2)

(-map (-cut <> 1 2 3) '(list vector string))
    ⇒ ((1 2 3) [1 2 3] "\1\2\3")

Function: -not (pred)

Return a predicate that negates the result of pred. The returned predicate passes its arguments to pred. If pred returns nil, the result is non-nil; otherwise the result is nil.

See also: -andfn (see -andfn) and -orfn (see -orfn).

(funcall (-not #'numberp) "5")
    ⇒ t

(-sort (-not #'<) '(5 2 1 0 6))
    ⇒ (6 5 2 1 0)

(-filter (-not (-partial #'< 4)) '(1 2 3 4 5 6 7 8))
    ⇒ (1 2 3 4)

Function: -orfn (&rest preds)

Return a predicate that returns the first non-nil result of preds. The returned predicate takes a variable number of arguments, passes them to each predicate in preds in turn until one of them returns non-nil, and returns that non-nil result without calling the remaining preds. If all preds return nil, or if no preds are given, the returned predicate returns nil.

See also: -andfn (see -andfn) and -not (see -not).

(-filter (-orfn #'natnump #'booleanp) '(1 nil "a" -4 b c t))
    ⇒ (1 nil t)

(funcall (-orfn #'symbolp (-cut string-match-p "x" <>)) "axe")
    ⇒ 1

(funcall (-orfn #'= #'+) 1 1)
    ⇒ t

Function: -andfn (&rest preds)

Return a predicate that returns non-nil if all preds do so. The returned predicate p takes a variable number of arguments and passes them to each predicate in preds in turn. If any one of preds returns nil, p also returns nil without calling the remaining preds. If all preds return non-nil, p returns the last such value. If no preds are given, p always returns non-nil.

See also: -orfn (see -orfn) and -not (see -not).

(-filter (-andfn #'numberp (-cut < <> 5)) '(a 1 b 6 c 2))
    ⇒ (1 2)

(mapcar (-andfn #'numberp #'1+) '(a 1 b 6))
    ⇒ (nil 2 nil 7)

(funcall (-andfn #'= #'+) 1 1)
    ⇒ 2

Function: -iteratefn (fn n)

Return a function fn composed n times with itself.

fn is a unary function. If you need to use a function of higher arity, use -applify (see -applify) first to turn it into a unary function.

With n = 0, this acts as identity function.

In types: (a -> a) -> Int -> a -> a.

This function satisfies the following law:

(funcall (-iteratefn fn n) init) = (-last-item (-iterate fn init (1+ n))).

(funcall (-iteratefn (lambda (x) (* x x)) 3) 2)
    ⇒ 256

(funcall (-iteratefn '1+ 3) 1)
    ⇒ 4

(funcall (-iteratefn 'cdr 3) '(1 2 3 4 5))
    ⇒ (4 5)

Function: -fixfn (fn &optional equal-test halt-test)

Return a function that computes the (least) fixpoint of fn.

fn must be a unary function. The returned lambda takes a single argument, x, the initial value for the fixpoint iteration. The iteration halts when either of the following conditions is satisfied:

1. Iteration converges to the fixpoint, with equality being tested using equal-test. If equal-test is not specified, equal is used. For functions over the floating point numbers, it may be necessary to provide an appropriate approximate comparison test.

2. halt-test returns a non-nil value. halt-test defaults to a simple counter that returns t after -fixfn-max-iterations, to guard against infinite iteration. Otherwise, halt-test must be a function that accepts a single argument, the current value of x, and returns non-nil as long as iteration should continue. In this way, a more sophisticated convergence test may be supplied by the caller.

The return value of the lambda is either the fixpoint or, if iteration halted before converging, a cons with car halted and cdr the final output from halt-test.

In types: (a -> a) -> a -> a.

(funcall (-fixfn #'cos #'approx=) 0.7)
    ⇒ 0.7390851332151607

(funcall (-fixfn (lambda (x) (expt (+ x 10) 0.25))) 2.0)
    ⇒ 1.8555845286409378

(funcall (-fixfn #'sin #'approx=) 0.1)
    ⇒ (halted . t)

Function: -prodfn (&rest fns)

Return a function that applies each of fns to each of a list of arguments.

Takes a list of n functions and returns a function that takes a list of length n, applying Ith function to Ith element of the input list. Returns a list of length n.

In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d)

This function satisfies the following laws:

(-compose (-prodfn f g …) (-prodfn f’ g’ …)) = (-prodfn (-compose f f’) (-compose g g’) …)

(-prodfn f g …) = (-juxt (-compose f (-partial #’nth 0)) (-compose g (-partial #’nth 1)) …)

(-compose (-prodfn f g …) (-juxt f’ g’ …)) = (-juxt (-compose f f’) (-compose g g’) …)

(-compose (-partial #’nth n) (-prod f1 f2 …)) = (-compose fn (-partial #’nth n))

(funcall (-prodfn #'1+ #'1- #'number-to-string) '(1 2 3))
    ⇒ (2 1 "3")

(-map (-prodfn #'1- #'1+) '((1 2) (3 4) (5 6)))
    ⇒ ((0 3) (2 5) (4 7))

(apply #'+ (funcall (-prodfn #'length #'string-to-number) '((t) "5")))
    ⇒ 6