Common Lisp Package: CL-UTILITIES

README:

FUNCTION

Public

COLLECT (THING)

Collect THING in the context established by the COLLECTING macro

COMPOSE (&REST FUNCTIONS)

Compose FUNCTIONS right-associatively, returning a function

COPY-ARRAY (ARRAY &KEY (UNDISPLACE NIL))

Shallow copies the contents of any array into another array with equivalent properties. If array is displaced, then this function will normally create another displaced array with similar properties, unless UNDISPLACE is non-NIL, in which case the contents of the array will be copied into a completely new, not displaced, array.

EXPT-MOD (N EXPONENT MODULUS)

As (mod (expt n exponent) modulus), but more efficient.

EXTREMUM (SEQUENCE PREDICATE &KEY (KEY #'IDENTITY) (START 0) END)

Returns the element of SEQUENCE that would appear first if the sequence were ordered according to SORT using PREDICATE and KEY using an unstable sorting algorithm. See http://www.cliki.net/EXTREMUM for the full specification.

EXTREMUM-FASTKEY (SEQUENCE PREDICATE &KEY (KEY #'IDENTITY) (START 0) END)

EXTREMUM implemented so that it calls KEY less. This is only faster if the KEY function is so slow that calling it less often would be a significant improvement; ordinarily it's slower.

N-MOST-EXTREME (N SEQUENCE PREDICATE &KEY (KEY #'IDENTITY) (START 0) END)

Returns a list of the N elements of SEQUENCE that would appear first if the sequence were ordered according to SORT using PREDICATE and KEY with a stable sorting algorithm. If there are less than N elements in the relevant part of the sequence, this will return all the elements it can and signal the warning N-MOST-EXTREME-NOT-ENOUGH-ELEMENTS

ROTATE-BYTE (COUNT BYTESPEC INTEGER)

Rotates a field of bits within INTEGER; specifically, returns an integer that contains the bits of INTEGER rotated COUNT times leftwards within the byte specified by BYTESPEC, and elsewhere contains the bits of INTEGER. See http://www.cliki.net/ROTATE-BYTE

SPLIT-SEQUENCE (DELIMITER SEQ &KEY (COUNT NIL) (REMOVE-EMPTY-SUBSEQS NIL) (FROM-END NIL) (START 0) (END NIL) (TEST NIL TEST-SUPPLIED) (TEST-NOT NIL TEST-NOT-SUPPLIED) (KEY NIL KEY-SUPPLIED))

Return a list of subsequences in seq delimited by delimiter. If :remove-empty-subseqs is NIL, empty subsequences will be included in the result; otherwise they will be discarded. All other keywords work analogously to those for CL:SUBSTITUTE. In particular, the behaviour of :from-end is possibly different from other versions of this function; :from-end values of NIL and T are equivalent unless :count is supplied. The second return value is an index suitable as an argument to CL:SUBSEQ into the sequence indicating where processing stopped.

SPLIT-SEQUENCE-IF (PREDICATE SEQ &KEY (COUNT NIL) (REMOVE-EMPTY-SUBSEQS NIL) (FROM-END NIL) (START 0) (END NIL) (KEY NIL KEY-SUPPLIED))

Return a list of subsequences in seq delimited by items satisfying predicate. If :remove-empty-subseqs is NIL, empty subsequences will be included in the result; otherwise they will be discarded. All other keywords work analogously to those for CL:SUBSTITUTE-IF. In particular, the behaviour of :from-end is possibly different from other versions of this function; :from-end values of NIL and T are equivalent unless :count is supplied. The second return value is an index suitable as an argument to CL:SUBSEQ into the sequence indicating where processing stopped.

SPLIT-SEQUENCE-IF-NOT (PREDICATE SEQ &KEY (COUNT NIL) (REMOVE-EMPTY-SUBSEQS NIL) (FROM-END NIL) (START 0) (END NIL) (KEY NIL KEY-SUPPLIED))

Return a list of subsequences in seq delimited by items satisfying (CL:COMPLEMENT predicate). If :remove-empty-subseqs is NIL, empty subsequences will be included in the result; otherwise they will be discarded. All other keywords work analogously to those for CL:SUBSTITUTE-IF-NOT. In particular, the behaviour of :from-end is possibly different from other versions of this function; :from-end values of NIL and T are equivalent unless :count is supplied. The second return value is an index suitable as an argument to CL:SUBSEQ into the sequence indicating where processing stopped.

Undocumented

EXTREMA (SEQUENCE PREDICATE &KEY (KEY #'IDENTITY) (START 0) END)

PARTITION (&REST ARGS)

PARTITION-IF (&REST ARGS)

PARTITION-IF-NOT (&REST ARGS)

READ-DELIMITED (SEQUENCE STREAM &KEY (START 0) END (DELIMITER ) (TEST #'EQL) (KEY #'IDENTITY))

Private

%CHECK-ONCE-ONLY-NAMES (NAMES)

Check that all of the NAMES are symbols. If not, raise an error.

%MAKE-ARRAY-WITH-SAME-PROPERTIES (ARRAY UNDISPLACE)

Make an array with the same properties (size, adjustability, etc.) as another array, optionally undisplacing the array.

%READ-DELIMITED-BOUNDS-CHECK (SEQUENCE START END)

Check to make sure START and END are in bounds when calling READ-DELIMITED with SEQUENCE

%READ-DELIMITED-BOUNDS-CHECK-END (SEQUENCE START END)

Check to make sure END is in bounds when calling READ-DELIMITED with SEQUENCE

%READ-DELIMITED-BOUNDS-CHECK-ORDER (SEQUENCE START END)

Check the order of START and END bounds, and return them in the correct order.

%READ-DELIMITED-BOUNDS-CHECK-START (SEQUENCE START END)

Check to make sure START is in bounds when calling READ-DELIMITED with SEQUENCE

%WITH-COLLECTORS-CHECK-COLLECTORS (COLLECTORS)

Check that all of the COLLECTORS are symbols. If not, raise an error.

%WITH-COLLECTORS-GENSYMS-ALIST (COLLECTORS)

Return an alist mapping the symbols in COLLECTORS to gensyms

%WITH-UNIQUE-NAMES-BINDING-PARTS (BINDING)

Return (values var prefix) from a WITH-UNIQUE-NAMES binding form. If PREFIX is not given in the binding, NIL is returned to indicate that the default should be used.

COMPARATOR (TEST &OPTIONAL (KEY #'IDENTITY))

Comparison operator: auxilliary function used by EXTREMUM

ZERO-LENGTH-P (SEQUENCE)

Is the length of SEQUENCE equal to zero?

MACRO

Public

COLLECTING (&BODY BODY)

Collect things into a list forwards. Within the body of this macro, the COLLECT function will collect its argument into the list returned by COLLECTING.

WITH-COLLECTORS ((&REST COLLECTORS) &BODY BODY)

Collect some things into lists forwards. The names in COLLECTORS are defined as local functions which each collect into a separate list. Returns as many values as there are collectors, in the order they were given.

WITH-GENSYMS ((&REST BINDINGS) &BODY BODY)

Synonym for WITH-UNIQUE-NAMES, but BINDINGS should only consist of atoms; lists are not supported. If you try to give list bindings, a LIST-BINDING-NOT-SUPPORTED warning will be signalled, but it will work the same way as WITH-UNIQUE-NAMES. Don't do it, though.

WITH-UNIQUE-NAMES ((&REST BINDINGS) &BODY BODY)

Executes a series of forms with each var bound to a fresh, uninterned symbol. See http://www.cliki.net/WITH-UNIQUE-NAMES

Undocumented

ONCE-ONLY (NAMES &BODY BODY)

Private

Undocumented

WITH-CHECK-LENGTH ((SEQUENCE START END) &BODY BODY)

GENERIC-FUNCTION

Public

Undocumented

LIST-BINDING-NOT-SUPPORTED-BINDING (CONDITION)

N-MOST-EXTREME-NOT-ENOUGH-ELEMENTS-N (CONDITION)

N-MOST-EXTREME-NOT-ENOUGH-ELEMENTS-SUBSEQUENCE (CONDITION)

READ-DELIMITED-BOUNDS-ERROR-END (CONDITION)

READ-DELIMITED-BOUNDS-ERROR-SEQUENCE (CONDITION)

READ-DELIMITED-BOUNDS-ERROR-START (CONDITION)

CONDITION

Public

LIST-BINDING-NOT-SUPPORTED

List bindings aren't supported by WITH-GENSYMS, and if you want to use them you should use WITH-UNIQUE-NAMES instead. That said, they will work; they'll just signal this warning to complain about it.

N-MOST-EXTREME-NOT-ENOUGH-ELEMENTS

There are not enough elements in the sequence given to N-MOST-EXTREME to return the N most extreme elements.

NO-EXTREMUM

Raised when EXTREMUM is called on an empty sequence, since there is no morally smallest element

READ-DELIMITED-BOUNDS-ERROR

There's a problem with the indices START and END for SEQUENCE. See CLHS SUBSEQ-OUT-OF-BOUNDS:IS-AN-ERROR issue.