Common Lisp Package: JPL-UTIL

README:

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.