# FUNCTION

# Public

# A/AN-NUMBER (N)

Given a non-negative integer that will be expressed as a cardinal
or ordinal number in English--either by FORMAT-ORDINAL or the ~R or
~:R format directives--returns either "a" or "an", whichever is
appropriate to precede the number.

# ADJACENT-PAIRS (SEQUENCE)

For each two adjacent pairs of elements in the given SEQUENCE,
return them as a list.
If SEQUENCE has less than 2 elements, returns the empty list.
Otherwise, returns (1- (LENGTH SEQUENCE)) pairs.

# ALIST->PLIST (ALIST &KEY (KEY #'IDENTITY) (TEST #'EQL))

Converts the given association list to a fresh property list.
KEY and TEST are applied to the CARs of the entries of ALIST for
uniqueness-checking; see ITERATE-ALIST.

# ALL (SEQUENCE &KEY (KEY #'IDENTITY))

Returns the logical-and of all the generalized booleans in the
given sequence.

# ANY (SEQUENCE &KEY (KEY #'IDENTITY))

Returns the logical-or of all the generalized booleans in the given
sequence.

# ASSOC* (ITEM ALIST &KEY (KEY #'IDENTITY) (TEST #'EQL) (DEFAULT 'NIL))

Like ASSOC, but returns the CDR of the matching entry, or DEFAULT
if there was no match. (ASSOC* ...) is a SETF-able place.
e.g.
(defparameter *test-alist* '())
=> *TEST-ALIST*
(assoc* 'a *test-alist*)
=> NIL
(push 1 (assoc* 'a *test-alist*))
=> (1)
(push 2 (assoc* 'a *test-alist*))
=> (2 1)
(assoc* 'a *test-alist*)
=> (2 1)
*test-alist*
=> ((A 2 1))
(setf (assoc* 'b *test-alist*) 'notalist)
=> NOTALIST
(setf (assoc* 'a *test-alist*) 'notalist)
=> NOTALIST
(assoc* 'a *test-alist*)
=> NOTALIST
*test-alist*
=> ((B . NOTALIST) (A . NOTALIST))

# BEST (SET PREDICATE &KEY (KEY #'IDENTITY) ALLOW-EMPTY)

Finds the best element in the given SET of elements (a SEQUENCE).
The given PREDICATE function of two arguments must return whether the
first "applicable value" represents a better item than the item
represented by the second applicable value.
Elements are their own applicable value unless KEY is supplied.
When ALLOW-EMPTY, SET may be empty, in which case NIL is returned.
Otherwise, an error is signalled.
This is more efficient than sorting and taking the first item from the
result, and it is more general than MIN and MAX.

# CIRCULAR-LIST (LIST)

Returns a fresh circular list that cycles through the contents of
LIST indefinitely. If LIST is empty, the result will be empty (and
hence not actually circular). LIST must be a proper list; if LIST is
circular, this function may not return.

# CLEAR-TRACES!

Because we can't tell whether code being traced with WITH-TRACE is
still active in the system, or it's been redefined to something else
with a new trace-ID, *expr-traces-by-id* always grows. It grows only
when WITH-TRACE is macroexpanded, so you should not normally need this
function.

# COERCE-BOOLEAN (B)

Normalizes the given generalized boolean to a boolean--that is,
non-NIL maps to T, and NIL maps to NIL.

# COMBINE-ELEMENTS (SEQUENCE PREDICATE COMBINATION-FN)

Conditionally combines the elements of sequence to form a new list.
When two adjacent elements each individually pass the predicate, the
combination-fn is called on both of them, in the order that they
appear in the sequence, to form a new replacement item. That
replacement item is subject to further combination.

# COMPOSE (&REST FUNCTIONS)

Returns the composition of a sequence of functions (designated by
FUNCTIONS), yielding a new function. The new function passes all its
arguments to the last given function. Each other given function gets
called, from last to first, with the values of the call of its
successive function. The new function returns all the values returned
by the first given function.
For single-argument functions a and b, and single-value functions b
and c:
(FUNCALL (COMPOSE a b c) x y z) == (a (b (c x y z)))
For any function f:
(COMPOSE f) == f
For any values x, y, and z:
COMPOSE == VALUES
(FUNCALL (COMPOSE)) => ; no value
(FUNCALL (COMPOSE) x) => x
(FUNCALL (COMPOSE) x y z) => x y z

# COMPOSE-1V (&REST FUNCTIONS)

Like COMPOSE, but restricted to (and optimized for) functions that
accept only one argument. The resulting function accepts only one
argument, and only the primary return value of each of the latter
given functions is given to their preceding functions. The resulting
function returns all the values returned by the first given function.
For single-argument functions a and b, and single-value functions b
and c:
(FUNCALL (COMPOSE-1V a b c) x) == (a (b (c x)))
For any function f of one argument:
(COMPOSE f) == f
For any value x:
COMPOSE == IDENTITY
(FUNCALL (COMPOSE) x) => x

# COND-REPLACE (SEQUENCE1 TEST-SEQUENCE NEW-SEQUENCE &KEY (TEST 'EQL) (KEY 'IDENTITY) (SEQUENCE1-START 0) SEQUENCE1-END (TEST-SEQUENCE-START 0) TEST-SEQUENCE-END (NEW-SEQUENCE-START 0) NEW-SEQUENCE-END)

Tests whether SEQUENCE1 is equal to TEST-SEQUENCE according to TEST
and KEY. When they are equal, destructively replaces SEQUENCE1 with
the contents of NEW-SEQUENCE, and returns the modified SEQUENCE1 and T.
Otherwise, returns SEQUENCE1 (unmodified) and NIL.
If SEQUENCE1 and TEST-SEQUENCE match, and if the lengths of
TEST-SEQUENCE and NEW-SEQUENCE differ, SEQUENCE1 will be resized
accordingly.
When SEQUENCE1 is a vector and doesn't need to be adjusted to a
different size, or is actually adjustable, or has a fill pointer which
either needs to be decreased or needs to be increased within the
dimensions of the vector, then the resulting sequence is guaranteed to
be identical to SEQUENCE1. Otherwise, the resulting sequence may
differ from SEQUENCE1 and should replace it.
SEQUENCE1, TEST-SEQUENCE, and NEW-SEQUENCE are bounded by
SEQUENCE1-START and SEQUENCE1-END, by TEST-SEQUENCE-START and
TEST-SEQUENCE-END, and by NEW-SEQUENCE-START and NEW-SEQUENCE-END,
respectively.
Only guaranteed to be efficient on vectors.

# CURRY-LEFT (FUNCTION &REST LEFT-ARGS)

Partially applies each of LEFT-ARGS to FUNCTION, yielding a new
function of the rest of the arguments accepted by FUNCTION.
(CURRY-LEFT f) == f ; Equivalent, but not identical.
(FUNCALL (CURRY-LEFT f a)) == (FUNCALL f a)
(FUNCALL (CURRY-LEFT f a b c) d e f) == (FUNCALL f a b c d e f)

# CURRY-RIGHT (FUNCTION &REST RIGHT-ARGS)

Partially applies each of RIGHT-ARGS as the last arguments to
function, in left-to-right order, yielding a new function of the
rest of the arguments accepted by FUNCTION.
(CURRY-RIGHT f) == f ; Equivalent, but not identical.
(FUNCALL (CURRY-RIGHT f a)) == (FUNCALL f a)
(FUNCALL (CURRY-RIGHT f a b)) == (FUNCALL f a b)
(FUNCALL (CURRY-RIGHT f d e f) a b c) == (FUNCALL f a b c d e f)

# DECODE-TIME-DURATION (DURATION &KEY SUBSECOND-DIGITS (ROUNDING 'TRUNCATE))

Breaks down a duration of time (as a non-negative REAL number of seconds),
returning days, hours, minutes, seconds, and subseconds.
The days, hours, and minutes values will be integers, while the
seconds value may be fractional (the same type as DURATION) if
DURATION is fractional and SUBSECOND-DIGITS is NIL; otherwise, the
seconds value will be an integer.
When SUBSECOND-DIGITS is NIL, the subseconds value will be NIL and the
seconds value will be of the same type as DURATION. Otherwise,
SUBSECOND-DIGITS must be a non-negative integer that indicates to how
many decimal places subsecond precision will be kept, and the
subseconds value will be the true amount of subseconds (in [0,1),
rounded according to ROUNDING and SUBSECOND-DIGITS, and expressed as a
non-negative integer below (EXPT 10 SUBSECOND-DIGITS).
ROUNDING is a symbol that controls how subseconds values are rounded,
and may be FLOOR, CEILING, ROUND, or TRUNCATE.
Days in which no leap seconds occur are assumed. (That is, the
returned number of days assumes 24 hours in one day, which does not
hold true on leap seconds days.)

# DUPLICATES-P (SEQUENCE &KEY (TEST #'EQL) (START 0) END (KEY #'IDENTITY))

Returns whether there are duplicates in the given sequence.

# EMPTY? (SEQ)

Returns a generalized boolean indicating whether SEQ (a SEQUENCE)
is empty.

# ENGLISH-LIST-FORMAT-CONTROL (&OPTIONAL (ELEMENT-FORMAT ~A) (RELATION and))

Creates a format control to format its operands as a list in
English. Expects at least one operand.
Each operand will be formatted with ELEMENT-FORMAT, a format control
that consumes one argument. ELEMENT-FORMAT defaults to "~A".
RELATION is a string which describes the relation between each
element, such as "and" (the default for RELATION) or "or."

# ENSURE-TYPE (VALUE TYPESPEC &OPTIONAL STRING)

A functional variant of CHECK-TYPE. When VALUE is of the type
specified by TYPESPEC, returns VALUE. Otherwise, signals a
correctable error of type TYPE-ERROR. In this case, this function
will return only if the STORE-VALUE restart is invoked with a new
value that matches TYPESPEC; the new value will be returned. If
STORE-VALUE is invoked with a new value that doesn't match TYPESPEC,
the process continues by raising another TYPE-ERROR.
As with CHECK-TYPE, "STRING should be an English description of the
type, starting with an indefinite article ('a' or 'an')."

# EQUIVALENT-HASH-TABLE-TEST (TEST)

Given a designator of a test function (one that returns a
generalized boolean indicating whether its two arguments are equal),
tries to find an alternative function that can be used as a hash-table
test, returning two values: a semantically-equivalent function of two
arguments, and a generalized boolean indicating whether the returned
function is a valid hash-table test function.
The returned function will behave the same as the given designated
function whenever it is given arguments which would be valid for the
original function. If the returned function is given invalid
arguments, it might not signal an error in situations that the
original function would have.

# FIND-DUPLICATES (SEQUENCE &KEY (TEST #'EQL) (KEY #'IDENTITY))

Returns all duplicates in SEQUENCE, according to the TEST and KEY.
Each item that appears anywhere else in the sequence is counted.
If TEST is a standard Common Lisp function that only applies to
certain types (such as numbers, strings, or characters), a substitute
test may be used in order to enable fast linear-time duplicate search
with a hash-table. In this case, if any element of SEQUENCE is not
appropriate for TEST, and TEST would normally signal an error, the
result of this function is undefined.

# FORMAT-ORDINAL (N)

Formats n to a short-hand ordinal: 1st, 2nd, etc.

# FORMAT-TIME-DURATION (SECONDS &KEY (SUBSECOND-DIGITS 0) (ROUNDING 'TRUNCATE))

Breaks down the given number of seconds into day, hour, minute, and
seconds components, formatting it as a string. The number of seconds
may be negative.
FRAC-DIGITS is the number of digits to show after the decimal point of
the seconds component (with the decimal point elided if 0). ROUNDING
is a symbol that controls how subsecond precision is handled: it may
be either FLOOR, CEILING, ROUND, or TRUNCATE.

# FRACTIONAL (INPUT DENOMINATORS)

Finds the closest approximation of INPUT of the form (+ I (/ N D)),
where I is an integer with the same sign as INPUT, N is a numerator of
the same sign as INPUT, and D is a denominator from the non-empty list
of positive integers DENOMINATORS. Returns the values I, N, and D.
For example, with DENOMINATORS equal to (2 3 4), here are
some results from example values of INPUT:
0.5 => 0 1 2
3.667 => 3 2 3
365.2425 => 365 1 4
It is conventional to express U.S. customary units with fractions,
rather than decimal numbers. You can use FRACTIONAL to do this:
(defun format-inches (stream inches)
(multiple-value-bind (i n d)
(jpl-util:fractional inches '(2 4 8 16))
;; If you're really clever, I'm sure you can squeeze this into
;; one big FORMAT control.
;; Explicitly print minus sign, rather than use the sign of i,
;; in-case i is zero but n is negative.
(when (minusp inches)
(princ #- stream))
(princ (abs i) stream)
(unless (zerop n)
(format stream " ~D/~D" (abs n) d))
(princ " in" stream))
(values))
(format-inches t -0.07) => -0 1/16 in
(format-inches t 3.882) => 3 7/8 in
(format-inches t 11.997) => 12 in

# GET-REASONABLE-REAL-TIME

Returns the current real time in seconds, possibly with sub-second
precision. Not guaranteed to be CL universal time.

# GET-REASONABLE-RUN-TIME

Returns the current CPU time in seconds, possibly with sub-second
precision. Not guaranteed to be CL universal time.

# GROUP-BY-N (LIST N)

Groups elements in the given LIST into lists that are N elements in
length. The number of elements in list must be a multiple of N.

# INSERT-AT (LIST N ITEM)

Returns a new list with the given ITEM inserted into the LIST at position N.

# INTEGER->TWOS-COMPLEMENT (N &OPTIONAL SIZE-MULTIPLE)

Returns the representation of N in two's complement, as a
bit-array. If SIZE-MULTIPLE is given, the length of the result will
be a multiple of SIZE-MULTIPLE.

# INTEGER-DIGIT-COUNT (N &OPTIONAL (RADIX 10))

Returns the number of digits required to represent the given
non-negative integer in RADIX.
(integer-digit-count N RADIX) == (length (integer-digits N RADIX))

# INTEGER-DIGITS (INT &OPTIONAL (RADIX 10))

Expresses the given non-negative integer as a fresh list of digits
in the given radix. The list of digits is ordered most-significant
first. When INT is 0, a list with just 0 is returned.

# ITERATE-ALIST (VISIT ALIST &KEY (KEY #'IDENTITY) (TEST #'EQL))

Iterates the entries of given association list, calling VISIT with
the CAR and CDR of each entry. To match the semantics of ASSOC, only
the first entry that matches (according to TEST) any given CAR (after
applying KEY) is visited.

# ITERATE-PLIST (VISIT PLIST)

Iterates the properties of the given property list, calling VISIT
with the indicator and value of each property. As Common Lisp
property list semantics prescribe, only the first property that
matches any given property indicator is visited.

# MAP-ADJACENT-PAIRS (RESULT-TYPE FUNCTION SEQUENCE)

Applies FUNCTION to every adjacent pair of elements in SEQUENCE (in
sequence). Returns NIL if RESULT-TYPE is NIL, otherwise returns a
sequence of the values obtained by each call of FUNCTION. The type of
SEQUENCE is as in MAP.
If SEQUENCE has less than 2 elements, FUNCTION is never called.
Otherwise, it is called (1- (LENGTH SEQUENCE)) times.
The consequence of FUNCTION modifying SEQUENCE is undefined.

# MEAN (SEQUENCE)

Returns the arithmetic mean of SEQUENCE. Each element of SEQUENCE
must be a number.

# MERGE-ALISTS (ALISTS &KEY (TEST #'EQL TEST-P) (TEST-NOT NIL TEST-NOT-P) (MERGE #'APPEND) (FROM-END T) (INITIAL-VALUE NIL INITIAL-VALUE-P))

Merges the given list of association lists.
All unique keys are collected and represented in the returned alist.
For each key, the associated value will be the reduction of all of the
values (in sequence) for that key found in the input alists. Values
are reduced using REDUCE with the function MERGE (defaulting to
#'APPEND), the list of collected values matching a key, and the values
of FROM-END (defaulting to T) and INITIAL-VALUE (unspecified by
default).
The order of the keys in the resulting alist is undefined.

# NTH-ARG (N)

Returns a function which returns its Nth argument. Useful when
composing a function with a function that returns multiple values.

# PACKAGE< (PACKAGE1 PACKAGE2)

Returns a boolean indicating whether PACKAGE1 is lesser than
PACKAGE2 (each are either PACKAGEs or NIL) according to the order
specified below.
The order of packages is: NIL, then any PACKAGE with no name, then the
KEYWORD package, then the sequence of all other packages ordered by
STRING< on their names.

# PARSE-PROGN (BODY &KEY (ALLOW-DOCSTRING-P T))

Given an implicit progn that may begin with an optional
documentation string and any number of declarations (in any order),
returns three values: the documentation string (or NIL if there isn't
any), a list of DECLARE expressions, and the rest of the list after
the initial docstring and declarations. DECLARE expressions and a
documentation string are only recognized within the initial segment;
documentation strings may appear there only once.

# PARSE-SEQUENCE-TYPE (TYPE)

Given a type specifier which is a subtype of SEQUENCE, returns the
primary sequence type (LIST or VECTOR), the element type, and the
sequence length (or * for unbounded length).
If either of the latter two parameters cannot be determined, the least
restricting value is used: T for element type, and * for length.

# PARSE-VECTOR-TYPE (TYPE)

Given a type specifier which is a recognizable subtype of VECTOR,
returns the element type and the sequence length (or * for unbounded
length).
If either of these parameters cannot be determined, the least
restricting value is used: T for element type, and * for length.

# PARTITION-LIST (LIST &KEY (TEST #'EQL) (KEY #'IDENTITY))

Partitions LIST into a list of sublists according to whether
adjacent elements pass the test. Adjacent elements which pass the
test are placed into the same sublist.
Two adjacent elements A and B (in that order) pass the test when
applying TEST to the key of A and the key of B results in a true
generalized boolean value. The key of an element is produced by
applying KEY to the element.
The result is a list of sublists. Every adjacent pair of elements A
and B in a resulting sublist pass the test:
(... (... A B ...) ...) (funcall TEST A* B*) returns true
Every pair of elements A and B, where A ends a resulting sublist and B
begins the subsequent sublist, do not pass the test:
(... (... A) (B ...) ...) (funcall TEST A* B*) returns false
The first element of the first resulting sublist is the first element
of LIST. The last element of the last resulting sublist is the last
element of LIST. If LIST is empty, then the resulting list of
sublists is also empty.
The returned list of sublists, as well as each of its sublists, is
freshly-allocated.
For set partitioning, see PARTITION-SET.

# PARTITION-SET (SET &KEY (TEST #'EQL) (KEY #'IDENTITY) ORDERED-P)

Groups elements in SET (a list) according to whether they are equal
according to TEST. The result is a set of sets, represented as a
fresh list of fresh lists: each contained set contains a member of
SET, and every member of each such set will be equal to every other
member of that same set (according to TEST).
When ORDERED-P is true, the order of the returned list of sets is the
order in which the first element of each set is seen in SET.
Furthermore, the order of each element in each returned set is the
order in which that element was seen in SET. Preserving the order
with ORDERED-P incurs a small constant-factor speed penalty.
TEST must be consistent. For any elements x y and z in SET, when x
and y are equal according to TEST, and y and z are equal according to
TEST, x and z must also be equal according to TEST.
The result of applying KEY each element is used for TEST.
For pairwise partitioning, see PARTITION-LIST.

# PLIST->ALIST (PLIST)

Converts the given property list to a fresh asssociation list.

# PROPER-LIST? (X)

Returns a generalized boolean indicating whether the given
object (of any actual type) is a proper list. When it is, the true
value returned is the length of the list.
The differences between this and LIST-LENGTH are that this function
will accept objects of any type, and this function will return false
for dotted lists.

# READ-NEW-VALUE

Prompts the user on *QUERY-IO* for a value. The value is expressed
by the user as a single form, which is evaluated. The first resulting
value, or NIL if there was no value, is returned as a list of one
element.
Intended for :INTERACTIVE options to RESTART-CASE clauses.

# REMOVE-DUPLICATE-PROPERTIES (PLIST)

Removes properties from the given property list that are
superceded by properties with the same indicator occurring earlier in
the property list.

# SET-EQUAL (LIST1 LIST2 &KEY KEY (TEST #'EQL))

Returns a generalized boolean indicating whether LIST1 and LIST2,
when taken as unordered sets, contain exactly the same set of
items (according to TEST). Duplicates either in LIST1 or in LIST2 are
ignored.
KEY, when not NIL, is a function of one argument, an element from
either LIST1 or LIST2. KEY is used to produce an object
representative of the input element, to pass to TEST. If KEY is NIL,
the elements from LIST1 and LIST2 are used directly (as if KEY is
#'IDENTITY).
TEST is a function of two arguments, the KEY of an element from LIST1
and the KEY of an element from LIST2 (or vice versa), which returns a
generalized boolean indicating whether the two objects should be
considered to be the same.

# SHUFFLE! (SEQUENCE)

Shuffles the given sequence in-place.

# SPLIT-LIST! (POS LIST)

Destructively splits LIST into two parts: the part before position
POS and the part after it. Returns the two resulting parts.
POS must be at least 0 and no greater than the length of LIST.

# STANDARD-DEVIATION (SEQUENCE)

Returns the standard deviation of SEQUENCE. Each element of
SEQUENCE must be a number.

# SUBSEQ* (SEQUENCE START &OPTIONAL END)

Like subseq, but shares structure with the input sequence (where
possible).

# SUBSEQ-DISPLACE (VECTOR START &OPTIONAL END)

Like subseq, but for vectors, returning a displaced vector which
shares structure with the given vector.

# SYMBOL< (SYMBOL1 SYMBOL2)

Returns a boolean indicating whether SYMBOL1 is lesser than SYMBOL2
(each are symbols) according to the order specified below.
A symbol is considered as the pair of its home package (or NIL if the
symbol is "apparently uninterned") and its name. The two symbols
are compared as their two pairs.
When the package of SYMBOL1 is less than that of SYMBOL2, SYMBOL1 is
considered less than SYMBOL2, regardless of the symbol names--and
vice-versa.
When the packages of SYMBOL1 and SYMBOL2 are considered equal, SYMBOL1
is less than SYMBOL2 iff the name of SYMBOL1 is STRING< that of
SYMBOL2.
Packages are compared with PACKAGE<.

# TEST-ORDER-PRED (PREDICATE ELEMENTS)

Tests PREDICATE, an order predicate, with the given sequence of
elements. Signals an error if an inconsistency is found. Otherwise,
returns a vector of the items sorted in ascending order.
An order predicate is a function of two arguments which returns a
generalized boolean indicating whether the first argument is less than
the second. It's the kind of function you would give to SORT.

# TWOS-COMPLEMENT->INTEGER (BIT-VECTOR)

Returns the integer represented in two's complement within
BIT-VECTOR.

# UNIQUE-PAIRS (LIST &OPTIONAL PREDICATE)

Returns the set of each possible ordered pair of elements in LIST.
Each ordered pair is represented as a list. The returned set is
represented as a list.
When PREDICATE is given and not NIL, it must be function. PREDICATE
is applied to each pair of elements to filter them from the result
set; pairs for which PREDICATE returns false are omitted.

# VECTOR-DELETE (VECTOR INDEX &OPTIONAL (NIL-P T))

Destructively removes the element specified at INDEX from VECTOR in
constant time. VECTOR must have a fill pointer; it is updated. INDEX
must be less than the length of VECTOR (according to its fill
pointer).
When NIL-P is true or not given, elements made to be
unreferenced (outside the active region denoted by the fill-pointer)
are overwritten with NIL, to prevent holding onto potentially big
objects, which would keep them from garbage collection indefinitely.
When NIL-P is false, the set of elements within VECTOR will remain the
same--only reordering and fill-pointer manipulation will occur.
Generally, NIL-P should be false only when VECTOR shares structure
with another vector (via displacement) or its fill-pointer will later
be artificially manipulated in order to recover deleted objects.
The order of elements within VECTOR should be mostly insignificant,
such as when VECTOR represents a set of objects, because elements are
reordered. Specifically, the last element of VECTOR and the element
at INDEX are swapped. Therefore, after returning, the positions of
the element at INDEX and the element just past the fill-pointer may be
different (with the exception that the element just past the
fill-pointer will be NIL when NIL-P is true); other elements will
retain their position. (This apparent implementation detail is
explicitly specified to allow for specific algorithms and bookkeeping
that depends on the indices of VECTOR.)

# VECTOR-DELETE-RANGE (VECTOR &KEY (START 0) END)

Destructively removes a subsequence of elements, specified by START
and END, from VECTOR, in time linear proportional to the length of the
subsequence. VECTOR must have a fill pointer; it is updated. START
and END must be bounding indices with the length of VECTOR (according
to its fill pointer).
The order of elements within VECTOR may be changed starting with START
and up to the end of the VECTOR. Therefore, this function is best
used for situations where a vector is considered to be a set, and the
order of its elements doesn't matter.

# WITH-EXTENT-HOOKS% (ENTER-FN RETURN-FN NON-LOCAL-EXIT-FN MAIN-FN)

Function-based variant of WITH-EXTENT-HOOKS; see its documentation.
ENTER-FN must be a function of no arguments. RETURN-FN must be a
function that can accept one argument for each value returned by
MAIN-FN. NON-LOCAL-EXIT-FN must be a function of no arguments.
MAIN-FN must be a function of no arguments.

# ZIP* (LISTS &KEY (PAD NIL PAD-P))

Combines the elements of each list of LISTS, returning a fresh list
where the element at position n is a fresh list of corresponding
elements from the input lists, each at position n. To put it another
way, if you think of the input lists as a matrix, this returns the
transpose of the matrix.
If PAD is specified and the lengths of the input lists are not equal,
then the lists will be implicitly padded with PAD at the end, as if
all the lists were of the same length as the longest list.

# Undocumented

# ALIST->HASH-TABLE (ALIST &KEY (TEST #'EQL))

# CHECK-BOUNDING-INDICES (START-REQ END-REQ START-ACTUAL END-ACTUAL LENGTH &KEY (SEQUENCE-DESC sequence))

# DELETE-NTH! (N LIST)

# DESIGNATED-CLASS (CLASS-DESIGNATOR)

# DESIGNATED-FUNCTION (EXTENDED-DESIGNATOR)

# EOF-P (STREAM)

# HASH-TABLE->ALIST (HT)

# LIST-TRACES (&KEY (STREAM T STREAM-SPEC-P) PACKAGES)

# MAP-LINES (FUNC STREAM)

# NSORT (SEQUENCE PREDICATE &KEY (KEY NIL KEY-SPEC-P))

# NSTABLE-SORT (SEQUENCE PREDICATE &KEY (KEY NIL KEY-SPEC-P))

# READ-LINES (STREAM)

# REMOVE-ORDERED-DUPLICATES (SEQUENCE SORT-PREDICATE &KEY (TEST #'EQL) (START 0) (END NIL) (KEY #'IDENTITY KEY-SPEC-P) (SORT-KEY #'IDENTITY SORT-KEY-SPEC-P) (COMPARISON-KEY #'IDENTITY COMPARISON-KEY-SPEC-P))

# SHUFFLE (SEQUENCE)

# SORT (SEQUENCE PREDICATE &KEY (KEY NIL KEY-SPEC-P))

# SQUARE (X)

# STABLE-SORT (SEQUENCE PREDICATE &KEY (KEY NIL KEY-SPEC-P))

# STRING-BEGIN-EQUAL (STRING SUBSTRING &KEY (START1 0) END1 (START2 0) END2)

# STRING-BEGIN= (STRING SUBSTRING &KEY (START1 0) END1 (START2 0) END2)

# STRING-END-EQUAL (STRING SUBSTRING &KEY (START1 0) END1 (START2 0) END2)

# STRING-END= (STRING SUBSTRING &KEY (START1 0) END1 (START2 0) END2)

# ZIP (&REST LISTS)

# Private

# Undocumented

# EXPR-TRACE-EXPRESSION-FORMAT (EXPR-TRACE)

# FIND-DUPLICATES-IN-LIST (LIST TEST KEY)

# FIND-DUPLICATES-IN-VECTOR (VECTOR TEST KEY)

# FIND-DUPLICATES-WITH-HASH-TABLE (SEQUENCE TEST KEY)

# LIST-EXTRACT!-HELPER (LIST PREDICATE MAPPING-P)

# OPTION-CLAUSE-LIST->PLIST (CLAUSES)

# REGISTER-TRACE (EXPRESSION &OPTIONAL ID)

# SWAPPED-APPEND (L2 L1)

# SWAPPED-NCONC (L2 L1)

# TEST-VECTOR-DELETE (VECTOR SUB-START SUB-END EXPECTED)

# TEST-VECTOR-DELETE-FUNCTIONS (&KEY (COUNT 1000) (LENGTH 10))

# TEST-VECTOR-DELETE-RANGE (VECTOR SUB-START SUB-END EXPECTED)

# VECTOR-EQUAL (V1 V2)

# VERBOSELY% (FUNCTION CONTROL-STRING &REST FORMAT-ARGUMENTS)

# WITH-VERBOSITY% (FUNCTION &OPTIONAL (VERBOSE *VERBOSE*))

# MACRO

# Public

# 1OR (&REST FORMS)

Returns true if and only if exactly one of the given forms returns
true. The single true value returned by one of the forms is returned.
Each form is evaluated at most once, and the forms are evaluated in an
unspecified order. If no forms are given, NIL is returned.

# ACCUMULATE-TO-DYNAMIC-VECTOR ((SET-ELEMENT-TYPE ACCUMULATE) &BODY BODY)

Evaluates BODY, accumulating elements to a fresh vector, resulting
in the vector (which will be adjustable and have a fill-pointer). The
number of elements to be accumulated does not have to be determined
before accumulation begins. The order of the elements of the
resulting vector is the order in which they are accumulated.
The symbols given by SET-ELEMENT-TYPE and ACCUMULATE name
lexically-defined macros:
(SET-ELEMENT-TYPE &optional ELEMENT-TYPE)
Must be evaluated once, before ACCUMULATE is evaluated for the
first time.
ELEMENT-TYPE (evaluated) specifies the array element type of the
resulting vector. The default is T. The result of accumulating
an element not of type ELEMENT-TYPE is undefined.
(ACCUMULATE ELEMENT)
Accumulates ELEMENT (evaluated) to the vector. ACCUMULATE may be
evaluated any number of times.

# ACCUMULATE-TO-HASH-TABLE ((SET-TEST/SIZE ACCUMULATE) &BODY BODY)

Evaluates BODY, accumulating key and value pairs to a fresh
hash-table, resulting in the hash-table.
The symbols given by SET-TEST/SIZE and ACCUMULATE name
lexically-defined macros:
(SET-TEST/SIZE TEST &optional SIZE)
Must be evaluated once, before ACCUMULATE is evaluated for the
first time.
TEST (evaluated) must be a designator for one of the test
functions acceptable to MAKE-HASH-TABLE.
If SIZE is specified and non-NIL, it is evaluated to produce a
non-negative integer which specifies the expected number of unique
entries to accumulate. The actual number of entries may vary, but
accumulation may be slower or use more memory than if the size had
been correctly predicted.
(ACCUMULATE KEY VALUE)
Accumulates an entry of KEY and VALUE (both evaluated) to the
hash-table, replacing any previous entry with the same KEY.
ACCUMULATE may be evaluated any number of times.

# ACCUMULATE-TO-LIST ((ACCUMULATE) &BODY BODY)

Evaluates BODY, accumulating elements to a fresh list, resulting in
the list. The order of the elements of the resulting list is the
order in which they are accumulated.
The symbol given by ACCUMULATE names a lexically-defined macro:
(ACCUMULATE ELEMENT)
Accumulates ELEMENT (evaluated) to the list. ACCUMULATE may be
evaluated any number of times.

# ACCUMULATE-TO-VECTOR ((SET-SIZE/ELEMENT-TYPE ACCUMULATE) &BODY BODY)

Evaluates BODY, accumulating elements to a fresh vector, resulting
in the vector. The number of elements to be accumulated must be
determined before accumulation begins. The order of the elements of
the resulting vector is the order in which they are accumulated.
The symbols given by SET-SIZE/ELEMENT-TYPE and ACCUMULATE name
lexically-defined macros:
(SET-SIZE/ELEMENT-TYPE SIZE &optional ELEMENT-TYPE)
Must be evaluated once, before ACCUMULATE is evaluated for the
first time.
SIZE (evaluated) specifies the length of the resulting vector.
ELEMENT-TYPE (evaluated) specifies the array element type of the
resulting vector. The default is T. The result of accumulating
an element not of type ELEMENT-TYPE is undefined.
(ACCUMULATE ELEMENT)
Accumulates ELEMENT (evaluated) to the vector.
ACCUMULATE must never be evaluated more times than the size of the
vector. At the time BODY returns normally, ACCUMULATE must have
been called exactly the number of times as the size of the vector.
ACCUMULATE may be evaluated fewer times when BODY makes a
non-local exit.

# CHECK-TYPE* (EXPRESSION TYPESPEC &OPTIONAL STRING)

Like CHECK-TYPE, with two differences: this tests any expression,
not just a place. If an error is signalled, it won't be correctable.

# COMPOSITE-LESSER? (&BODY CLAUSES)

Returns a generalized boolean indicating whether one thing is less
than another thing according to the rules defined by CLAUSES.
Each thing (neither of which is explicitly expressed as an argument)
should conceptually be deconstructable to an equal number of
comparable parts. Each part of both things is compared in parallel,
beginning with the first part of the things, followed by the next part
of the things, and so on. One thing is less than another thing when
it has a part which is less than the other thing's corresponding part,
and all part pairs prior to the differing part pair compare as equal.
Each clause represents a part to test. A clause is of the form:
(TEST OBJ1 OBJ2)
OBJ1 and OBJ2 are expressions which produce parts of the first and
second thing, respectively. TEST is evaluated to produce a function
of two arguments, which is applied to the two objects (in both orders)
to determine which one is lesser than the other, if any.
Additionally, the final clause may take the form:
(:OTHERWISE &body OTHERWISE-BODY)
When this is so, and no differences are found by testing each pair of
parts, then the result--rather than NIL--is the evaluation of
OTHERWISE-BODY as an implicit progn. This facilitates the comparison
of two things which have a variable number of parts; OTHERWISE-BODY
would test the tails of the parts which occur after the parts tested
for with ordinary clauses.
TEST, OBJ1, and OBJ2 for any given clause, and OTHERWISE-BODY, will be
evaluated at most once, but evaluation (and hence calling the function
expressed by TEST) may be short-circuited if testing an earlier part
proves that later part comparisons are irrelevant.

# CSUBTYPECASE (KEY-PLACE &BODY CLAUSES)

As with SUBTYPECASE, but signals a correctable error of type
SUBTYPE-ERROR if no clause matches. The STORE-VALUE restart can be
used to correct the error. No otherwise clause is allowed. Analogous
to CTYPECASE.

# DEFCLASS* (CLASS-NAME (&REST SUPERCLASS-NAMES) (&REST SLOT-SPECIFIERS) &REST CLASS-OPTIONS)

Defines a class just like DEFCLASS does, but adds reasonable
default options to each slot.
:INITARG is defined, with the slot name as a keyword.
:INITFORM is defined, with an ERROR form that signals a SIMPLE-ERROR
with a generic message, "Must supply [INITARG]."
A reader, writer, or accessor is defined, with the same name as the
slot. By default, a reader is defined; you may override the selection
with the special slot option JPL-UTIL:ACCESSOR-TYPE, with a value
of :READER, :WRITER, or :ACCESSOR. The name of the reader, writer, or
accessor may be overridden with the special slot option
JPL-UTIL:ACCESSOR-NAME. If either value of JPL-UTIL:ACCESSOR-TYPE or
JPL-UTIL:ACCESSOR-NAME are NIL, then no reader, writer, or accessor is
defined.
Any default slot option may be overridden by explicitly specifying a
value for that slot option. For example, if you don't like the
default value for :INITFORM, you may specify :INITFORM NIL.
Default slot option may be omitted by giving the special slot option
JPL-UTIL:OMIT-OPTIONS with a list of default slot option indicators to
suppress. For example, if you don't want an :INITFORM option, you may
specify JPL-UTIL:OMIT-OPTIONS (:INITFORM).

# DEFVAR-UNBOUND (NAME &OPTIONAL DOC-STRING)

Convenience macro to declare unbound special variables with a
documentation string.

# DOSEQ ((VAR SEQUENCE-FORM &OPTIONAL (RESULT-FORM NIL)) &BODY BODY)

Iterates over the elements of the sequence produced by evaluating
SEQUENCE-FORM similarly to DOLIST.
BODY may be included in the expansion more than once, for
specialization on the different types of sequences without the
overhead of function calls.

# ESUBTYPECASE (KEY-FORM &BODY CLAUSES)

As with SUBTYPECASE, but signals SUBTYPE-ERROR if no clause
matches. No otherwise clause is allowed. Analogous to ETYPECASE.

# LAMBDA* (ARGS &BODY BODY)

Creates a function. Takes an extended, rather than an ordinary, lambda list.

# LESSER? ((VALUE1 VALUE2 LEAST-POSSIBLE-VALUE) &BODY BODY)

Evaluates to whether VALUE1 is less than VALUE2 when there is the
possibility that either are EQ to LEAST-POSSIBLE-VALUE. One value is
always less than the other when it is EQ to LEAST-POSSIBLE-VALUE and
the other is not. If the answer cannot be determined by comparing
VALUE1 and VALUE2 with LEAST-POSSIBLE-VALUE, then BODY is evaluated.
VALUE1, VALUE2, and LEAST-POSSIBLE-VALUE may or may not be evaluated,
and in any order. BODY is evaluated only when neither values are EQ
to LEAST-POSSIBLE-VALUE.

# LIST-EXTRACT! (LIST PREDICATE &KEY MAPPING-P)

Returns those items in list that pass the predicate, removing them
destructively from the input. When mapping-p is true, returns the
result of the predicate function for each element, rather than the
elements themselves.

# OPTION-CLAUSE-BIND (LAMBDA-LIST EXPRESSION &BODY BODY)

Evaluates EXPRESSION to produce a list of "option clauses," then
evaluates BODY with the variables of LAMBDA-LIST bound to the values
of the option clauses.
An option clause is a cons of the form (NAME . VALUE), where each NAME
is unique. A list of option clauses looks a lot like an association
list, with the difference being that no value is allowed to be the
NAME of more than one option clause.
Although the term "option clause" is not used in the Common Lisp
HyperSpec, the syntax of some Common Lisp macros call for expressing
options in this style. DEFCLASS and DEFGENERIC are among these
macros.
LAMBDA-LIST is just like a sequence of variable specifications in the
&KEY section of a destructuring lambda list. Each member of
LAMBDA-LIST designates one value of NAME to match from the list of
option clauses, and must take one of the following forms:
VAR
If the keyword name appears as the name of an option clause, VAR
is bound to the value of that option clause. Otherwise, VAR is
bound to NIL.
The keyword name is a keyword with the same name as VAR.
VAR must be a symbol which is not a lambda list keyword.
({VAR | (KEYWORD-NAME VAR)} [INIT-FORM [SUPPLIED-P-PARAMETER]])
If the keyword name appears as the name of an option clause, VAR
is bound to the value of that option clause. Otherwise, if
INIT-FORM is supplied, VAR is bound to the result of evaluating
INIT-FORM. Otherwise, VAR is bound to NIL.
SUPPLIED-P-PARAMETER, when supplied, is bound to a boolean value
indicating whether a matching option clause was found. When the
bound value is true, INIT-FORM will not have been evaluated. When
the value is false, INIT-FORM (if supplied) will have been
evaluated.
When KEYWORD-NAME is supplied, it is used as the keyword name;
otherwise, a keyword with the same name as VAR is used.
When supplied, VAR and SUPPLIED-P-PARAMETER must be symbols,
INIT-FORM must be a form, and KEYWORD-NAME may be any value.
For example:
(option-clause-bind (foo bar) '((:foo 1 2) (:bar 3)) . BODY) ==
(destructuring-bind (&key foo bar) '(:foo (1 2) :bar (3)) . BODY)
Due to the constraint that NAMEs must be unique, note that:
(option-clause-bind VARS EXPRESSION . BODY) NOT==
(destructuring-bind (&key . VARS) (alist->plist EXPRESSION) . BODY)

# PUSH-APPEND (LIST PLACE)

Prepends the contents of LIST onto the list stored in PLACE. The
resulting list is stored in PLACE and then returned.

# PUSH-NCONC (LIST PLACE)

Destructively prepends the contents of LIST onto the list stored in
PLACE. The resulting list is stored in PLACE and then returned.

# SUBTYPECASE (KEY-FORM &BODY CLAUSES)

Evaluates the code associated with the first clause which lists a
type which KEY-FORM (which is evaluated) a recognizable subtype of.
If there is no match, NIL is returned. SUBTYPECASE is to SUBTYPEP as
TYPECASE is to TYPEP.
The syntax of clauses, including the syntax of an optional trailing
otherwise-clause, is the same as in TYPECASE.

# WITH-ACCESSORS* ((&REST ACCESSORS) INSTANCE-FORM &BODY BODY)

Like WITH-ACCESSORS, except that instead of giving (VARIABLE-NAME
ACCESSOR-NAME) for each accessor, you may give VARIABLE-NAME, in which
case ACCESSOR-NAME is derived from it.

# WITH-EXTENT-HOOKS ((ENTER RETURN NON-LOCAL-EXIT) &BODY BODY)

Evaluates BODY, and evaluates the given forms upon certain
situations relating to the dynamic extent of the evaluation of BODY.
ENTER must be a form. Just before dynamic extent enters BODY, ENTER
is evaluated. The return values of ENTER are discarded.
RETURN must be a list of the form (LAMBDA-LIST &BODY RETURN-BODY), or
NIL. If BODY returns and RETURN is not NIL, RETURN-BODY (an implicit
progn) is evaluated with the variables of LAMBDA-LIST (an ordinary
lambda list) bound to the return values of BODY. The return values of
RETURN-BODY are discarded. The return values of BODY are returned by
WITH-EXTENT-HOOKS.
NON-LOCAL-EXIT must be a form. If dynamic extent leaves BODY due to a
non-local exit (including due to a signalled condition),
NON-LOCAL-EXIT is evaluated. The return values of NON-LOCAL-EXIT are
discarded.

# WITH-GENSYMS ((&REST NAMES) &BODY BODY)

Evaluates BODY with each variable name of NAMES bound to a unique,
fresh, uninterned symbol.

# WITH-LIST-ITERATOR ((NEXT SIZE EXHAUSTED? LIST-FORM) &BODY BODY)

Evaluates BODY with an iterator on a list.
LIST-FORM is evaluated once to produce the list to iterate upon. The
resulting list is never modified (unless from within BODY--the
consequences of which are undefined).
The symbols given by NEXT, SIZE, and EXHAUSTED? name lexically-defined
macros:
(NEXT)
Yields the next successive element of the list. The consequences
of evaluating (NEXT) more times than the length of the list is
undefined.
(SIZE)
Evaluates to the length of the list. The list is only traversed
for only the first evaluation; the length is memoized.
(EXHAUSTED?)
Evaluates to a generalized boolean indicating whether the list has
been exhausted by evaluations of (NEXT).

# WITH-RANGE-ITERATOR ((NEXT SIZE EXHAUSTED? LOWER-FORM UPPER-FORM) &BODY BODY)

Evaluates BODY with an iterator on a range of integers.
LOWER-FORM and UPPER-FORM are evaluated once to produce the range of
integers, [LOWER,UPPER), to iterate upon.
The symbols given by NEXT, SIZE, and EXHAUSTED? name lexically-defined
macros:
(NEXT)
Yields the next successive element of the range. The consequences
of evaluating (NEXT) more times than the length of the range is
undefined.
(SIZE)
Evaluates to the length of the range.
(EXHAUSTED?)
Evaluates to a generalized boolean indicating whether the range
has been exhausted by evaluations of (NEXT).

# WITH-SAFE-ALLOC ((VAR ALLOC FREE) &REST BODY)

Binds VAR to NIL, then sets it to the result of evaluating ALLOC.
Upon exit of dynamic extent, as long as the value of VAR is not NIL
(such as by a condition signalled by evaluating ALLOC), FREE is
evaluated.

# WITH-SEQUENCE-ITERATOR ((NEXT SIZE EXHAUSTED? SEQUENCE-FORM) &BODY BODY)

Evaluates BODY with an iterator on a SEQUENCE.
SEQUENCE-FORM is evaluated once to produce the sequence to iterate
upon. The resulting sequence is never modified (unless from within
BODY--the consequences of which are undefined). If the sequence is a
vector with a fill-pointer, the fill-pointer is respected.
The symbols given by NEXT, SIZE, and EXHAUSTED? name lexically-defined
macros:
(NEXT)
Yields the next successive element of the sequence. The
consequences of evaluating (NEXT) more times than the length of
the sequence is undefined.
(SIZE)
Evaluates to the length of the sequence.
(EXHAUSTED?)
Evaluates to a generalized boolean indicating whether the sequence
has been exhausted by evaluations of (NEXT).

# WITH-TRACE ((&OPTIONAL ID) &BODY BODY)

Like TRACE, but for the given body of code. Specify an ID (a
number or symbol) to avoid the conceptually-same code from clogging up
the output of LIST-TRACES as this code gets redefined several times.

# WITH-VECTOR-ITERATOR ((NEXT SIZE EXHAUSTED? VECTOR-FORM) &BODY BODY)

Evaluates BODY with an iterator on a vector.
VECTOR-FORM is evaluated once to produce the vector to iterate upon.
The resulting vector is never modified (unless from within BODY--the
consequences of which are undefined). If the vector has a
fill-pointer, it is respected.
The symbols given by NEXT, SIZE, and EXHAUSTED? name lexically-defined
macros:
(NEXT)
Yields the next successive element of the vector. The
consequences of evaluating (NEXT) more times than the length of
the vector is undefined.
(SIZE)
Evaluates to the length of the vector.
(EXHAUSTED?)
Evaluates to a generalized boolean indicating whether the vector
has been exhausted by evaluations of (NEXT).

# XOR (&REST FORMS)

Returns the logical exclusive-or of the generalized boolean value
of each form: true if and only if there are an even number of forms
that return true. Each form is evaluated once, and the forms are
evaluated in an unspecified order. If no forms are given, NIL is
returned.

# Undocumented

# VERBOSELY ((CONTROL-STRING &REST FORMAT-ARGUMENTS) &BODY BODY)

# WITH-VERBOSITY ((&OPTIONAL (VERBOSE NIL VERBOSE-P)) &BODY BODY)

# Private

# HANDLER-CASE/NO-UNWIND (FORM &REST CLAUSES)

Like HANDLER-CASE, but does not unwind the stack before executing
an error-handling clause.

# Undocumented

# PUSH-APPEND% (PLACE LIST &ENVIRONMENT ENV)

# PUSH-NCONC% (PLACE LIST &ENVIRONMENT ENV)

# GENERIC-FUNCTION

# Public

# COPY-OBJECT (OBJ)

Recursively copies an object. The output is
guaranteed to not share structure with the input. Patterns of shared
structure may not be replicated in the output. If the input has
reference cycles, this function may not return or signal a
condition.

# Undocumented

# SUBTYPE-ERROR-EXPECTED-SUPERTYPE (CONDITION)

# SUBTYPE-ERROR-TYPE (CONDITION)

# SLOT-ACCESSOR

# Private

# Undocumented

# EXPRESSION (OBJECT)

# SETFEXPRESSION (NEW-VALUE OBJECT)

# HOME-PACKAGE (OBJECT)

# ID (OBJECT)

# VARIABLE

# Public

# *VERBOSE*

Whether to be verbose when evaluating forms expressed in VERBOSELY.

# Private

# *VERBOSITY-DEPTH*

The number of containing WITH-VERBOSITY forms that specify
verbosity to be enabled.

# Undocumented

# *EXPR-TRACES-BY-EXPR*

# *EXPR-TRACES-BY-ID*

# CLASS

# Private

# Undocumented

# EXPR-TRACE

# CONDITION

# Public

# SUBTYPE-ERROR

TYPE is not a subtype of EXPECTED-SUPERTYPE.