Common Lisp Package: UK.CO.DEOXYBYTE-UTILITIES

The deoxybyte-utilities system provides general purpose utilities. These are for the most part simple, standalone functions and macros. Once a particular function or macro has been written more than once or twice in other systems, it normally gets moved here. Given the fluid nature of the contents of this system, its package's exported symbols are intended primarily for use by other deoxybyte packages.

README:

FUNCTION

Public

ALL-CLASSES (PACKAGE-NAME &OPTIONAL (SUPERCLASS (FIND-CLASS 'STANDARD-OBJECT)))

Returns a list of all classes defined in package PACKAGE-NAME, optionally restricted to those classes that have SUPERCLASS.

ALL-EXTERNAL-CLASSES (PACKAGE-NAME &OPTIONAL (SUPERCLASS (FIND-CLASS T)))

Returns a list of all exported classes defined in package PACKAGE-NAME, optionally restricted to those classes that have SUPERCLASS.

ALL-EXTERNAL-GENERIC-FUNCTIONS (PACKAGE-NAME)

Returns a list of all the external generic functions in package PACKAGE-NAME.

ALL-SLOTS (CLASS)

Returns a sorted list of all slots of CLASS.

ALL-SPECIALIZED-GENERIC-FUNCTIONS (CLASS &OPTIONAL (CEILING (FIND-CLASS 'STANDARD-OBJECT)))

Returns a list of all generic functions specialized on CLASS, up to, but not including, class CEILING. The class CEILING defaults to STANDARD-OBJECT.

ALL-SPECIALIZED-METHODS (CLASS &OPTIONAL (CEILING (FIND-CLASS 'STANDARD-OBJECT)))

Returns a list of all methods specialized on CLASS, up to, but not including, class CEILING. The class CEILING defaults to STANDARD-OBJECT.

ALL-SUPERCLASSES (CLASS &OPTIONAL (CEILING (FIND-CLASS 'STANDARD-OBJECT)))

Returns a list of all superclasses of CLASS, up to, but not including, class CEILING. The class CEILING defaults to STANDARD-OBJECT.

COLLECT (GEN &OPTIONAL (N 1))

Returns a list of up to N values collected from generator function GEN. Uses {defun has-more-p} to test the generator and may return an empty list if no items are available.

COLLECT-KEY-VALUES (KEYWORDS ARG-LIST)

For all keywords in list KEYWORDS, finds the keyword and its value in ARG-LIST, a list containing only keyword and value pairs. Returns two values, a list of matched keywords and a list of their corresponding values.

CONCAT-STRINGS (STRS)

Returns a new simple-string created by concatenating, in the order supplied, the simple-strings contained in the vector STRS.

CONSUME (CON &REST ARGS)

Applies consumer function CON with arguments ARGS.

CONTAINS-CHAR-P (STR CHAR &KEY (TEST #'CHAR=))

Returns T if STR contains CHAR, determined by TEST (defaults to CHAR=) or NIL otherwise.

CONTENT-STRING-P (STR)

Returns T if any of the characters in STR are not whitespace as defined by WHITESPACE-CHAR-P, or NIL otherwise.

CONTROL-CHAR-P (CHAR)

Returns T if CHAR is an ASCII control character (all characters with codes 0-31, inclusive, and the character with code 127), or NIL otherwise.

CURRENT (GEN)

Returns the current value of generator function GEN.

DIRECT-SUBCLASSES (CLASS)

Returns a list of the direct subclasses of CLASS.

DIRECT-SUPERCLASSES (CLASS)

Returns a list of the direct superclasses of CLASS.

DISCARD (GEN &OPTIONAL (N 1))

Discards up to N values collected from generator function GEN. Uses {defun has-more-p} to test the generator and finally returns the number of values actually discarded.

DISCARDING-IF (TEST GEN)

Returns a new generator function that discards values from generator function GEN while they satisfy TEST.

DOTTED-PAIR-P (LIST)

Returns T if LIST is a dotted pair, or NIL otherwise.

EMPTY-STRING-P (STR)

Returns T if STR is a zero-length string or contains only whitespace as defined by WHITESPACE-CHAR-P, or NIL otherwise.

ENDS-WITH-CHAR-P (STR CHAR &KEY (TEST #'CHAR=))

Returns T if STR has CHAR at its last index, determined by TEST (defaults to CHAR=), or NIL otherwise.

ENDS-WITH-STRING-P (STR1 STR2 &KEY (TEST #'STRING=))

Returns T if STR1 ends with STR2, determined by TEST (defaults to STRING=), or NIL otherwise.

EVERY-CHAR-P (STR TEST &REST INDICES)

Applies predicate TEST to characters of string STR indicated by INDICES and returns T if all those characters match TEST.

EXACTLY-N (PREDICATE N FIRST-SEQ &REST MORE-SEQS)

Analagous to the ANSI standard functions EVERY and SOME, except that this function returns T if exactly N tests of PREDICATE are true, or NIL otherwise.

EXACTLY-ONE (PREDICATE FIRST-SEQ &REST MORE-SEQS)

Analagous to the ANSI standard functions EVERY and SOME, except that this function returns T if exactly one test of PREDICATE is true, or NIL otherwise.

FLATTEN (TREE)

Returns a new list containing the members of TREE.

HAS-CHAR-AT-P (STR CHAR INDEX &KEY (TEST #'CHAR=))

Returns T if STR has CHAR at INDEX, determined by TEST (defaults to CHAR=), or NIL otherwise.

HAS-MORE-P (GEN)

Returns T if generator function GEN has more available values, or NIL otherwise.

HAS-SUPERCLASS-P (CLASS SUPERCLASS)

Returns T if CLASS has SUPERCLASS, or NIL otherwise.

INTERSPERSE (LIST OBJ)

Returns a list containing the members of LIST interspersed with OBJ.

IOTA (COUNT &OPTIONAL (START 0) (STEP 1))

Generates a list of COUNT integers from START (defaults to 0) with subsequent integers STEP (defaults to 1) greater than the last, or less, if a negative STEP is given.

KEY-VALUE (KEYWORD ARG-LIST)

Returns the current value of KEYWORD in list ARG-LIST, a list containing only keyword and value pairs.

LINEAR-INTERSECTION (LIST1 LIST2 &KEY KEY TEST)

Returns a list that is the intersection of LIST1 and LIST2, in linear time. See CL:INTERSECTION for the meaning of KEY and TEST.

LINEAR-SET-DIFFERENCE (LIST1 LIST2 &KEY KEY TEST)

Returns a list that is the set difference of LIST1 and LIST2, in linear time. See CL:SET-DIFFERENCE for the meaning of KEY and TEST.

LINEAR-SET-EXCLUSIVE-OR (LIST1 LIST2 &KEY KEY TEST)

Returns a list that is the set exclusive-or of LIST1 and LIST2, in linear time. See CL:SET-EXCLUSIVE-OR for the meaning of KEY and TEST.

LINEAR-SUBSETP (LIST1 LIST2 &KEY KEY TEST)

Returns T if LIST1 is a subset of LIST2, in linear time. See CL:SUBSETP for the meaning of KEY and TEST.

LINEAR-UNION (LIST1 LIST2 &KEY KEY TEST)

Returns a list that is the union of LIST1 and LIST2, in linear time. See CL:UNION for the meaning of KEY and TEST.

MODIFY-KEY-VALUE (KEYWORD ARG-LIST MOD-FN &REST FN-ARGS)

Returns a copy of ARG-LIST where the value corresponding to KEYWORD has been replaced by the result of applying MOD-FN to that value. MOD-FN must be a function that accepts KEYWORDS's value and may accept additional arguments supplied in FN-ARGS.

NEXT (GEN)

Returns the next available value from generator function GEN.

NSPLICE (LIST OBJ N)

Destructively splices atom or list OBJ into LIST at position N.

NUMBER-GENERATOR (&OPTIONAL (START 0) (STEP 1))

Creates a closure of zero arity that returns an integer from START with subsequent integers incrementing by STEP greater than the last, or less, is a negative step is given. Optional: - start (integer): the start value, defaults to 0. - step (integer): the step size, defaults to 1. Returns: - A closure of zero arity.

OCTETS-TO-STRING (OCTETS &OPTIONAL (START 0) (END NIL END-SUPPLIED-P))

Returns a new simple-base-string created from the values in OCTET-VECTOR, a simple-array of (unsigned-byte 8), between indices START and END. The elements of the returned string are the result of calling code-char on the respective elements of OCTET-VECTOR.

PROPER-LIST-P (LIST)

Returns T if LIST is a proper list, or NIL otherwise. A proper list is defined as a list whose terminal cdr is NIL. This function does not test the list for circularity.

QUEUE-APPEND (QUEUE &REST LISTS)

Inserts LISTS of items at the end of QUEUE and returns QUEUE.

QUEUE-CLEAR (QUEUE)

Removes all items from queue, returning two values, the queue and a list of all the items that were in the queue.

QUEUE-DELETE (ITEM QUEUE &KEY KEY (TEST #'EQL))

Deletes the first occurrence of ITEM in QUEUE, if present, returning QUEUE. The TEST and KEY keyword arguments are the same as for CL:DELETE.

QUEUE-DEQUEUE (QUEUE)

Removes one item from the front of QUEUE and returns two values. The first value is the item, or NIL if QUEUE was empty and the second value is T if an item was dequeued, or NIL otherwise.

QUEUE-DEQUEUE-IF (TEST QUEUE &KEY KEY)

Removes items from QUEUE that pass predicate TEST, returning two values, QUEUE and a list of the deleted items. The KEY keyword argument is the same as for C:DELETE-IF.

QUEUE-EMPTY-P (QUEUE)

Returns T if QUEUE is empty, or NIL otherwise.

QUEUE-ENQUEUE (ITEM QUEUE)

Inserts ITEM at the end of QUEUE and returns QUEUE.

QUEUE-FIRST (QUEUE)

Returns the first item in QUEUE, without removing it.

QUEUE-HEAD (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

QUEUE-LAST (QUEUE)

Returns the last item in QUEUE, without removing it.

QUEUE-NTH (N QUEUE)

Returns the Nth item in QUEUE.

REMOVE-KEY-VALUES (KEYWORDS ARG-LIST)

Returns two values, a copy of ARG-LIST, a list containing only keyword and value pairs, with KEYWORDS and their values removed and an alist containing KEYWORDS and their corresponding values.

SLOT-DOCUMENTATION (SLOT CLASS)

Returns the documentation string for SLOT of CLASS.

SPLICE (LIST OBJ N)

Splices atom or (a copy of) list OBJ into a copy of LIST at position N.

STARTS-WITH-CHAR-P (STR CHAR &KEY (TEST #'CHAR=))

Returns T if STR has CHAR at index 0, determined by TEST (defaults to CHAR=), or NIL otherwise.

STARTS-WITH-STRING-P (STR1 STR2 &KEY (TEST #'STRING=))

Returns T if STR1 starts with STR2, determined by TEST (defaults to STRING=), or NIL otherwise.

STR (&REST STRINGS)

Returns the result of concatenating strings STRINGS.

STRING-SPLIT (STR CHAR &KEY (START 0) END REMOVE-EMPTY-SUBSTRINGS)

Returns a list of strings made by splitting simple-string STR at CHAR, between START and END. If REMOVE-EMPTY-SUBSEQS is T, any empty subsequences will be omitted from the returned list.

STRING-SPLIT-INDICES (STR CHAR &KEY (START 0) END)

Returns two values, a list of start indices and a list of end indices into STR between START and END such that if used as start/end arguments to subseq, STR will be split on CHAR. CHAR is compared with elements in STR using TEST, which defaults to EQL.

STRING-TO-OCTETS (STR &OPTIONAL (START 0) (END NIL END-SUPPLIED-P))

Returns a new vector of octets created from the simple-string STR, between indices START and END. The elements of the returned vector are the result of calling char-code on the respective characters of STR.

TXT (&REST STRINGS)

Returns the result of concatenating STRINGS, separated by spaces.

VECTOR-POSITIONS

Returns a list of indices into VECTOR between START and END where ELT is present according to TEST (which defaults to EQL).

VECTOR-SPLIT (ELT VECTOR &KEY (START 0) END (TEST #'EQL) REMOVE-EMPTY-SUBSEQS DISPLACE-TO-VECTOR)

Returns a list of vectors made by splitting VECTOR at ELT, between START and END. ELT is compared with elements in VECTOR using TEST, which defaults to EQL. If REMOVE-EMPTY-SUBSEQS is T, any empty subsequences will be omitted from the returned list. If DISPLACE-TO-VECTOR id T, the returned subsequences will be displaced to the actual subsequences within VECTOR and will therefore share structure with VECTOR.

VECTOR-SPLIT-INDICES

Returns two values, a list of start indices and a list of end indices into VECTOR between START and END such that if used as start/end arguments to subseq, VECTOR will be split on ELT. ELT is compared with elements in VECTOR using TEST, which defaults to EQL.

WHITESPACE-CHAR-P (CHAR)

Returns T if CHAR is one of the currently bound set of whitespace characters (defaults to #Space #Tab #Return #Linefeed and #FormFeed), or NIL otherwise.

WHITESPACE-STRING-P (STR)

Returns T if all the characters in STR are whitespace as defined by WHITESPACE-CHAR-P, or NIL otherwise.

Undocumented

LINEAR-SET-EQUAL (LIST1 LIST2 &KEY KEY TEST)

MAKE-QUEUE (&KEY ((HEAD DUM0) NIL) ((TAIL DUM1) NIL))

SETFQUEUE-HEAD (NEW-VALUE INSTANCE)

QUEUE-P (OBJECT)

STRING-POSITIONS (STR CHAR &KEY (START 0) END)

Private

ALL-SLOT-DEFINITIONS (CLASS)

Returns a list of all slot definitions of CLASS.

CANONICAL-FN-ARGS (LAMBDA-LIST FN-ARGS)

Returns a canonical version of FN-ARGS corresponding to LAMBDA-LIST.

QUEUE-LENGTH (QUEUE)

Returns the length of QUEUE.

QUEUE-POSITION (ITEM QUEUE &KEY KEY (TEST #'EQL))

Returns the zero-based index of ITEM in QUEUE, or NIL if ITEM is not present. The TEST and KEY keyword arguments are the same as for CL:POSITION.

QUEUE-TAIL (INSTANCE)

@arg[extid]{A @class{extid}} @return[sytemid]{puri:uri or nil} Returns the System ID part of this External ID.

QUOTEDP (FORM)

Returns T if FORM is quoted.

Undocumented

COPY-QUEUE (INSTANCE)

MAKE-CONDITIONAL (ACCEPTORS)

SETFQUEUE-TAIL (NEW-VALUE INSTANCE)

MACRO

Public

ASSOCDR (KEY ALIST &REST ARGS)

Returns the cdr of the cons cell returned by calling (assoc KEY ALIST ARGS).

ASSOCPOP (KEY ALIST &REST ARGS)

Pops a value from the cdr of the cons returned from ALIST by calling assoc with KEY and ARGS.

ASSOCPUSH (KEY ALIST VAL &REST ARGS)

Pushes VAL onto the cdr of the cons returned from ALIST by calling assoc with KEY and ARGS.

CHECK-ARGUMENTS (TEST-FORM ARGUMENTS &OPTIONAL ERROR-MESSAGE &REST MESSAGE-ARGUMENTS)

Checks the validity of ARGUMENTS. If TEST-FORM returns false an {define-condition invalid-argument-error} is raised. The default error message may be refined with an additional ERROR-MESSAGE. Arguments: - test-form (form): A form to be evaluated. If the form returns NIL, an error is raised. - arguments (list symbols): A list of symbols to which argument values are bound. Optional: - error-message (string): An error message string. Rest: - message-arguments (forms): Forms that evaluate to arguments for the error message.

COPY-VECTOR (SOURCE SOURCE-START SOURCE-END DEST DEST-START &OPTIONAL KEY)

Copies elements SOURCE indices SOURCE-START and SOURCE-END to DEST, inserting them into DEST at DEST-START onwards. If the function KEY is supplied, it is applied to each element of SOURCE prior to its insertion into DEST.

DEFGENERATOR (MORE-FORM NEXT-FORM &OPTIONAL CURRENT-FORM)

Returns a generator function that may be passed to any of the generator utility functions {defun has-more-p} , {defun next} and {defun current} . Arguments: - more-form (form): A form that returns T if the generator can supply more values, or NIL otherwise. Used by {defun has-more-p } . - next-form (form): A form that returns the next value of the generator. Used by {defun next} . Optional: - current-form (form): A form that returns the current value of the generator. Used by {defun current} . Returns: - A form that evaluates to an anonymous function.

DEFINE-CATEGORICAL-BINNER (VALUE &REST CATEGORIES)

Creates a closure that accepts a single fixnum argument. The argument value is assigned to the appropriate bin and that bin's total is incremented. The closure returns two values, the bins as an array of fixnums and the total number of times values did not fall into any category. Note that the return values are cumulative across calls because the counters are closed over. Arguments: - value (symbol): a symbol to which values are bound on the subsequent category forms. Rest: - categories (forms): test forms, one for each bin, that evaluate to a generalized boolean. These forms are evaulated in the order given in to assign values to bins. For example, counting numbers into four bins of odd/positive, odd/negative, even/positive and even/negative. ;;; (define-categorical-binner x ;;; (and (oddp x) (plusp x)) ;;; (and (oddp x) (minusp x)) ;;; (and (evenp x) (plusp x)) ;;; (and (evenp x) (minusp x))) Returns: - A closure accepting a numeric value.

DEFSM ((&REST STATES))

Defines a finite state machine over STATES. Arguments: - states (list): A list of forms describing the state transitions. See {defun defsmfun} . For example: ;;; (let* ((seq (make-dna "atggtgcct")) ;;; (i 0) ;;; (len (length-of seq)) ;;; (codons ()) ;;; (codon ())) ;;; (defsm ((base0 ((< i len) base1 ;;; (setf codon (list (element-of seq i))) ;;; (incf i)) ;;; (t nil ;;; (reverse codons))) ;;; (base1 ((< i len) base2 ;;; (push (element-of seq i) codon) ;;; (incf i)) ;;; (t nil ;;; (reverse codons))) ;;; (base2 ((< i len) base0 ;;; (push (element-of seq i) codon) ;;; (push (reverse codon) codons) ;;; (incf i)) ;;; (t nil ;;; (reverse codons)))))

DEFSMFUN (NAME ARGS BINDINGS (&REST STATES))

Returns a function that encapsulates a finite state machine over STATES. Arguments: - name (symbol): The name of the function. - args (lambda list): The function lambda list. - bindings (list): A list of parallel bindings (as for LET). Rest: - states (list): A list of forms describing the state transitions. Each state form consists of a symbol that denotes a current state and a series of conditional forms that act indicate potential states that may be reached from the current state. The tests are evaluated in turn as in a COND form. (current-state (test1 next-state1 &rest actions) (test2 next-state2 &rest actions) (t nil)) When a test returns T, the machine moves to the next state once the current state's action forms are evaluated. A next state of NIL indicates termination, at which point the function returns the result of evaluating the last action form. For example, the following definition returns a function that partitions a DNA sequence into base triples (codons). ;;; (defsmfun codon-iterator (seq &key (start 0)) ;;; ((i start) ;;; (len (length-of seq)) ;;; (codons ()) ;;; (codon ())) ;;; ((base0 ((< i len) base1 ;;; (setf codon (list (element-of seq i))) ;;; (incf i)) ;;; (t nil ;;; (reverse codons))) ;;; (base1 ((< i len) base2 ;;; (push (element-of seq i) codon) ;;; (incf i)) ;;; (t nil ;;; (reverse codons))) ;;; (base2 ((< i len) base0 ;;; (push (element-of seq i) codon) ;;; (push (reverse codon) codons) ;;; (incf i)) ;;; (t nil ;;; (reverse codons))))) Returns: - A function.

FUNCALL-IF-FN (FUNCTION ARG)

If FUNCTION is not null, funcalls FUNCTION on ARG, otherwise returns ARG.

RASSOCAR (VAL ALIST &REST ARGS)

Returns the car of the cons cell returned by calling (rassoc KEY ALIST ARGS).

RPLASSOC (KEY ALIST VAL &REST ARGS)

Performs destructive replacement with VAL (using RPLACD) of the cdr of the cons returned when calling assoc on ALIST with KEY and ARGS.

WITH-NUMERIC-SELECTOR ((NAME NUM-BINS &KEY (START 0) (END (+ START NUM-BINS)) (OUT-OF-BOUNDS ERROR)) &BODY BODY)

Defines a local function NAME that accepts a single fixnum argument and returns an integer between 0 and NUM-BINS, indicating in which of NUM-BINS sequential, equal-sized bins that value belongs. Arguments: - name (symbol): the local function name. - num-bins (integer): the number of bins into which values are to be assigned. Key: - start (number): the lower bound of the range of values to be binned, defaults to 0. - end (number): the upper bound of the range of values to be binned. - oob-error (boolean): if T the function will throw an INVALID-ARGUMENT-ERROR when passed values less than START or greater than END, otherwise the function will return NIL.

Undocumented

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

GENERIC-FUNCTION

Public

MESSAGE-OF (CONDITION)

Returns the condition message string.

Private

Undocumented

ARGUMENTS-OF (CONDITION)

FEATURE-OF (CONDITION)

FORMAT-ARGUMENTS-OF (CONDITION)

FORMAT-CONTROL-OF (CONDITION)

IN-FAVOUR-OF (CONDITION)

PARAMETERS-OF (CONDITION)

TEXT-OF (CONDITION)

VARIABLE

Private

*WHITESPACE-CHARS*

Whitespace characters.

CLASS

Public

QUEUE

A FIFO queue. For consistency, all functions that operate on a QUEUE carry the QUEUE- prefix, even though this results in tautology for some functions, such as QUEUE-ENQUEUE/QUEUE-DEQUEUE. This is a standard way of making a linked-list queue; the QUEUE structure contains pointers to both the head and tail of a single list.

CONDITION

Public

DEPRECATION-WARNING

A warning that is raised when a deprecated feature is used.

INVALID-ARGUMENT-ERROR

An error that is raised when an invalid argument is passed to a function.

INVALID-OPERATION-ERROR

An error that is raised when an invalid operation is attempted.

MISSING-ARGUMENT-ERROR

An error that is raised when a required argument is not passed to a function.

Undocumented

FORMATTED-CONDITION

SIMPLE-TEXT-CONDITION