# FUNCTION

# Public

# $ (&REST FUNCTIONS)

Returns the composition of FUNCTIONS. Note that FUNCTIONS must
be composable in the order specified.
For example,
INCF-CL> (funcall ($ (lambda (x) (* x x))
(lambda (x) (+ x 2)))
2)
16
INCF-CL> (funcall ($ #'values #'floor #'sqrt (lambda (x) (expt x 2))) -2)
2

# DOCTEST (SYMBOL &KEY (STREAM *STANDARD-OUTPUT*))

If SYMBOL corresponds to a function, then its documentation string
is tested and the results are printed to STREAM. If SYMBOL refers to
a package, then all the functions corresponding to the external
symbols in the package are tested.
DOCTEST returns T if the tests succeed, NIL otherwise.

# FIXED-POINT (FUNCTION INITIAL-VALUE &KEY (TEST #'EQL) MAX-STEPS)

Returns the fixed point of FUNCTION starting with INITIAL-VALUE.
The keyword argument TEST determines when a fixed point has been
reached. Use MAX-STEPS to stop after a certain (positive) number of
iterations.
For example, the square root of 2 using Newton's method can be
computed as:
INCF-CL> (fixed-point (lambda (x)
(float (- x (/ (- (expt x 2) 2) (* 2 x)))))
1)
1.4142135
INCF-CL> (sqrt 2)
1.4142135

# FLIP (F)

Applied to a binary function F, returns the same function with the
order of the arguments reversed.

# LIST-ALL-SYMBOLS (PACKAGE)

Returns a list containing all the symbols in PACKAGE.

# LIST-EXTERNAL-SYMBOLS (PACKAGE)

Returns a list containing all the exported symbols in PACKAGE.

# NEST-LIST (FUNCTION INITIAL-VALUES &KEY TEST TEST-NOT N (M 1) MAX)

Returns a list of the results of applying FUNCTION successively to
INITIAL-VALUES and continuing until applying TEST (respectively
TEST-NOT) to the result is non NIL.
If M is specified, then NEST-LIST supplies the M most recent results
as arguments for TEST (respectivelly TEST-NOT) at each step.
If MAX is specified then FUNCTION is applied at most MAX times.

# REPLICATE (N X)

Returns a list contaning N times the value X

# STRING-JOIN (LIST &OPTIONAL (SEP ))

Returns a string joining each string in LIST by SEP. If SEP is not
specified, the default separator is a space.

# UNFOLD (PREDICATE TRANSFORMER INCREMENTOR INITIAL-VALUE &OPTIONAL (TAIL-GEN (CONSTANTLY NIL)))

Returns a list built following the pattern:
transformer(initial-value), transformer(incrementor(initial-value)), ...
Examples:
1. List of squares: 1^2, ..., 10^2
INCF-CL> (unfold (lambda (x) (> x 10)) (lambda (x) (expt x 2)) #'1+ 1)
(1 4 9 16 25 36 49 64 81 100)
2. Append (3 4 5) onto (1 2)
INCF-CL> (unfold #'null #'first #'rest (list 1 2) (lambda (x)
(declare (ignore x))
(list 3 4 5)))
(1 2 3 4 5)
See also:
http://srfi.schemers.org/srfi-1/srfi-1.html#unfold

# UNFOLD-RIGHT (PREDICATE TRANSFORMER INCREMENTOR INITIAL-VALUE &OPTIONAL (TAIL NIL))

Returns a list built following the pattern:
... transformer(incrementor(initial-value)), transformer(initial-value)
Examples:
1. List of squares: 1^2, ..., 10^2
INCF-CL> (unfold-right #'zerop (lambda (x) (* x x)) #'1- 10)
(1 4 9 16 25 36 49 64 81 100)
2. Reverse a proper list:
INCF-CL> (unfold-right #'null #'first #'rest (list 1 2 3 4 5))
(5 4 3 2 1)
See also:
http://srfi.schemers.org/srfi-1/srfi-1.html#unfold-right

# UNZIP (ALIST)

Applied to the association list ALIST, returns two lists (as
VALUES) containing the keys and values of each element in ALIST
respectively. This function is the inverse of PAIRLIS.

# Undocumented

# NEST (FUNCTION INITIAL-VALUES &KEY TEST TEST-NOT N (M 1) MAX)

# RANGE (A B &OPTIONAL C)

# Private

# CANONICALIZE-TEST (TEST TEST-NOT)

Returns a validated test function for those functions that use TEST
and TEST-NOT keyword arguments.

# TEST-DOCSTRING (DOCUMENTATION)

Returns T if the first doctest found in DOCUMENTATION passes,
signals DOCTEST-FAILURE otherwise.

# TEST-FUNCTION (PACKAGE FUNCTION STREAM)

Returns T if every test in FUNCTION's docstring passes, NIL
otherwise.

# Undocumented

# %NEST-LIST (FUNCTION INITIAL-VALUES TEST N M MAX)

# APPLY-KEY (KEY ELEMENT)

# ENSURE-AND-COPY-LIST (X)

# FIRST-WITH (KEY LIST)

# SCAN-LEFT* (FUNCTION LIST KEY INITIAL-VALUE IVP)

# SCAN-RIGHT* (FUNCTION LIST KEY INITIAL-VALUE IVP)

# TRANSLATE-COMPREHENSION (COLLECTION-FORM QUANTIFIERS)

# TRANSLATE-FILTER (COLLECTION-FORM FILTER-FORM QUANTIFIERS)

# TRANSLATE-GENERATOR (COLLECTION-FORM VARIABLE COLLECTION QUANTIFIERS)

# TRANSLATE-GENERATOR-OR-FILTER (COLLECTION-FORM QUANTIFIERS)

# MACRO

# Public

# DOHASH ((KEY VALUE HASH-TABLE &OPTIONAL (RESULT-FORM NIL)) &BODY BODY)

DOHASH iterates over the keys and values of HASH-TABLE. It returns
NIL or the result of evaluating RESULT-FORM if it was specified.

# LC (COLLECTION-FORM &REST QUANTIFIERS)

Assembles a multiset containing the results of evaluating
COLLECTION-FORM and subject to QUANTIFIERS.

# SIGNALS-P (CONDITION &BODY BODY)

Returns T if evaluating BODY results in CONDITION being signalled,
NIL otherwise.

# WHILE (PREDICATE-FORM &BODY BODY)

Executes BODY while PREDICATE-FORM is non NIL.

# GENERIC-FUNCTION

# Public

# BREAK* (PREDICATE LIST &KEY KEY)

Given a PREDICATE and a LIST, breaks LIST into two
lists (returned as VALUES) at the point where PREDICATE is first
satisfied. If PREDICATE is never satisfied then the first returned
value is the entire LIST and the second element is NIL.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# CYCLE (LIST)

Returns a circular list containing the elements in
LIST (which should be a proper list).

# DROP (N LIST)

Applied to N (a non-negative integer) and LIST,
returns the list with the specified number of elements removed from
the front of LIST. If LIST has less than N elements then it returns
NIL.

# DROP-WHILE (PREDICATE LIST &KEY KEY)

Applied to PREDICATE and LIST, removes elements
from the front of LIST while PREDICATE is satisfied.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# GROUP (LIST &KEY KEY TEST TEST-NOT (TEST #'EQL))

Returns a list of lists where every item in each
sublist satisfies TEST and the concatenation of the result is equal to
LIST.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.
For example,
INCF-CL> (mapcar (lambda (x) (concatenate 'string x))
(group (coerce "Mississippi" 'list)))
("M" "i" "ss" "i" "ss" "i" "pp" "i")

# INSERT (X LIST &KEY KEY TEST TEST-NOT (TEST #'<))

Inserts X before the first element in LIST which is
greater than X. The order relation can be specified by either one of
the keyword arguments TEST and TEST-NOT.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# INTERSPERSE (ELEMENT LIST)

Returns a list where ELEMENT is interspersed
between the elements of SEQUENCE.
For example,
INCF-CL> (intersperse 'x (replicate 3 'z))
(Z X Z X Z)

# NCYCLE (LIST)

Destructive version of CYCLE. Again, keep in mind
that LIST must be a proper list.

# NINTERSPERSE (ELEMENT LIST)

Destructive version of INTERSPERSE.

# PARTITION (PREDICATE LIST &KEY KEY)

Applied to PREDICATE and LIST, returns two values: a list
containing all the elements from LIST that satisfy PREDICATE, and its
complementary list.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# SCAN* (FUNCTION LIST &KEY KEY FROM-END INITIAL-VALUE (INITIAL-VALUE NIL IVP))

SCAN* is similar to REDUCE, but returns a list of
successive reduced values:
(scan* f (list x1 x2 ...) :initial-value z)
==> (z (funcall f z x1) (funcall f (funcall f z x1) x2) ...)
(scan* f (list x1 x2 ...))
==> (x1 (funcall f x1 x2) (funcall f (funcall f x1 x2) x2) ...)
(scan* f (list x1 ... x_n-1 x_n) :initial-value z :from-end t)
==> (... (funcall f x_n-1 (funcall f x_n z)) (funcall f x_n z) z)
(scan* f (list x1 ... x_n-1 x_n) :from-end t)
==> (... (funcall f x_n-1 (funcall f x_n-1 x_n)) (funcall f x_n-1 x_n) x_n)
Examples:
INCF-CL> (scan* #'/ (list 4 2 4) :initial-value 64)
(64 16 8 2)
INCF-CL> (scan* #'max (range 1 7) :initial-value 5)
(5 5 5 5 5 5 6 7)
INCF-CL> (scan* (lambda (x y) (+ (* 2 x) y)) (list 1 2 3) :initial-value 4)
(4 9 20 43)
INCF-CL> (scan* #'+ (list 1 2 3 4))
(1 3 6 10)
INCF-CL> (scan* #'+ (list 1 2 3 4) :initial-value 5 :from-end t)
(15 14 12 9 5)
INCF-CL> (scan* #'+ (list 1 2 3 4) :from-end t)
(10 9 7 4)

# SPAN (PREDICATE LIST &KEY KEY)

Splits LIST into two lists (returned as VALUES)
such that elements in the first list are taken from the head of LIST
while PREDICATE is satisfied, and elements in the second list are the
remaining elements from LIST once PREDICATE is not satisfied.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# SPLIT-AT (N LIST)

Given a non-negative integer N and LIST, splits
LIST into two lists (returned as VALUES) at the position corresponding
to the given integer. If N is greater than the length of LIST, it
returns the entire list first and the empty list second in VALUES.

# TAKE (N LIST)

Applied to the integer N and LIST, returns the specified number of
elements from the front of LIST. If LIST has less than N elements,
TAKE returns the entire LIST.

# TAKE-WHILE (PREDICATE LIST &KEY KEY)

Applied to PREDICATE and LIST, returns a list
containing elements from the front of LIST while PREDICATE is
satisfied.
KEY is a designator for a function of one argument, or NIL. If KEY
is supplied, it is applied once to each element of LIST before it is
passed to PREDICATE. If it is not supplied or is NIL, the element of
LIST itself is used.

# UNSCAN (FUNCTION LIST &KEY INITIAL-VALUE)

Semi-inverse of SCAN*.
INCF-CL> (equal (unscan (flip #'-) (scan* #'+ '(1 2 3)) :initial-value 0)
'(1 2 3))
T

# Private

# Undocumented

# ACTUAL-VALUES (CONDITION)

# EXPECTED-VALUES (CONDITION)

# SEXPR (CONDITION)

# VARIABLE

# Public

# *DOCTEST-SHOW-PROGRESS*

Determines if a dot will be displayed for each passed test.