7.1 Package FL.UTILITIES

This package contains generally useful utility functions. Several of those functions were taken from (Graham 1996), the SANS function was contributed to the comp.lang.lisp newsgroup by Erik Naggum.

Function: ADD-HOOK FUNCTION-NAME HOOK-NAME HOOK-FUNCTION

Add a hook with name hook-name to the hooks for function-name.

Function: ARRAY-FOR-EACH FUNC &REST ARRAYS

Calls func on all element tuples of the array arguments.

Function: BLACKBOARD &REST ITEMS

Make the property list supplied in items into a blackboard. Copies items to make sure that no literal list is modified.

Class: BLACKBOARD

A blackboard where data items can be put and extracted using the function GETBB.

Direct slots:

• ITEMS: A property list of items on the blackboard.

Function: BOX OBJECT

Boxes an object.

Function: CALL-HOOKS FUNCTION-NAME OBJECT &REST ARGS

Call all hooks defined for function-name on object and returns object.

Function: CHECK-PROPERTIES PLACE PROPERTIES

Checks if all of the properties are in the property list place.

Function: COMMON-LISP-SPEED &KEY (MEMORY-WEIGHT 0.5)

Returns the speed which should be characteristic for the setting determined by memory-weight. If this argument is 0.0 it means that all operations should be inside cache memory whereas 1.0 means that the operation are restricted by memory bandwidth available.

Function: COMPOSE &REST FUNCTIONS

Returns the composition of functions.

Function: COMPOSE-2 F G

Composes two function objects f and g.

Function: CONCEPT-DOCUMENTATION DOCSTRING

Documents a certain concept.

Function: CONSTANT-VECTOR DIM VALUE

Returns a uniform constant vector of which all elements are value.

Function: COPY-HASH-TABLE HASH-TABLE

Copy hash-table.

Function: COPY-SLOTS OBJ1 OBJ2 SLOTS

Initializes the slots named in slots from obj2 to obj1. Returns obj1.

Function: CURRY FUNC &REST ARGS

Supplies args to func from the left.

Function: DEQUEUE QUEUE

Pops an object from queue. Returns as second value T if the queue was empty.

Function: DEQUEUE-ALL QUEUE

Clears queue and returns content as a list.

Function: DISPLAY-HT HASH-TABLE

Display hash-table in the form key1 -> value1 ...

Function: DLL-FRONT-INSERT OBJ DLL &OPTIONAL INSERT-ITEM-P

Inserts obj in dll. It returns the newly created dll-item.

Function: DLL-REAR-INSERT OBJ DLL &OPTIONAL INSERT-ITEM-P

Inserts obj in dll. It returns the newly created dll-item.

Macro: DOHASH (LOOPING-VAR HASH-TABLE) &BODY BODY

Loops through hash-table. If looping-var is an atom key, loop through the keys; if it is a list of the form (value) loop through the values; if it is a list of the form (key value) loop through key and value.

Macro: DOTUPLE (INDEX LIMITS &OPTIONAL RESULT) &BODY BODY

Loops through each tuple below limits.

Function: EMPTYP QUEUE

Tests if queue is empty.

Function: ENQUEUE OBJECT QUEUE

Puts object into the queue.

Function: EVALUATE F X

Generic evaluation of functions on an argument. Numbers and arrays are treated as constants. Special evaluation is defined for multivariate polynomials on vectors and for <function> objects.

Function: FACTORIAL N

Compute the factorial of n. n can also be a list of numbers in which case the product of the factorials of the components is computed.

Function: FILE-DOCUMENTATION DOCSTRING

If the manual is sorted by file, the string handed to this function describes the use of the respective file.

Function: FILTER ITEM SEQ &REST REST &KEY TEST TEST-NOT &ALLOW-OTHER-KEYS

The positive REMOVE - i.e. like REMOVE with :test instead of :test-not.

Function: FILTER-IF &REST ARGS

The positive version of REMOVE-IF-NOT.

Function: FIND-LEAF ATOM TREE &KEY (KEY (FUNCTION IDENTITY)) (TEST (FUNCTION EQL))

Finds atom in tree.

Function: FIND-LEAF-IF TEST TREE &KEY (KEY (FUNCTION IDENTITY))

Finds a leaf in tree where test returns true.

Function: FIND-SUBTREE-IF TEST TREE &KEY (KEY (FUNCTION IDENTITY))

Finds a leaf in tree where test returns true.

Function: FIRST-ONLY LIST

Checks if list is a singleton and returns its first element.

Function: FIXNUM-VEC &REST ELEMENTS

Returns a FIXNUM-VEC constructed from the parameters.

Type: FIXNUM-VEC

Vector with elements of type fixnum.

Function: FLATTEN TREE

Flatten a tree. Example:

  (flatten '((1 2) (3) ((4))))  ⇒  (1 2 3 4)

Function: FOR-EACH FUNC COLLECTION

Applies func to each element of collection.

Function: FOR-EACH-TUPLE FUNC LIMITS

Calls func on each tuple greater or equal to (0 ... 0) and below dims.

Function: GET-PROPERTY OBJECT PROPERTY

Gets property for object. Returns NIL also if property is not available.

Function: GETA ALIST KEY

An analog to GETF for association lists.

Setf Expander: GETA

An analog to (SETF GETF) for association lists.

Function: GETBB BLACKBOARD KEY &OPTIONAL DEFAULT

Get the item for key from blackboard. If there is no such key return default.

Function: GROUP-BY CHARACTERISTIC SEQ &KEY (TEST (QUOTE EQL))

Groups elements in the sequence seq according to characteristic which is a function of one argument. Example:

  (group-by #'second '((1 2) (2 2) (3 4) (4 4)))

Function: HASH-TABLE-KEYS HASH-TABLE

Collect the keys of hash-table into a list.

Function: HASH-TABLE-VALUES HASH-TABLE

Collect the values of hash-table into a list.

Function: IDENTITY-PERMUTATION-P PERM

Checks if the permutation is the identity.

Function: ITERATOR X

Returns an iterator for x.

Function: ITERATOR-NEXT VEC ITERATOR

Returns an incremented iterator.

Function: K->L-SUBSETS SET K L

Returns all subsets of set with length between k and l. Example:

  (k->l-subsets '(1 2 3) 1 2) ⇒
  ((1) (2) (3) (1 2) (1 3) (2 3))

Function: K-SUBSETS SET K

Returns all subsets of set with length k. Example:

  (k-subsets '(1 2 3) 2)
  ⇒ ((1 2) (1 3) (2 3))

Function: LIST->QUEUE LIST

Transforms list to a queue.

Macro: LOOP+ ITEMS &BODY BODY

Iterates body over items. Example:

  (let ((x (make-array 10))
	(y (make-list 10 :initial-element 1)))
    (loop+ ((xc x) (yc y) i) doing
       (setf xc (+ i yc))
       finally (return x)))

Function: MAKE-ANALOG OBJ

Generate an analogous but empty data structure.

Function: MAKE-FIXNUM-VEC DIM &OPTIONAL (INIT 0)

Construct a FIXNUM-VEC of size dim initialized by init.

Function: MAP-HASH-TABLE FUNC HASH-TABLE

Call func given in the first argument on each key of hash-table. func must return the new key and the new value as two values. Those pairs are stored in a new hash-table.

Function: MAP-LIST-IN-HASH-TABLE FUNC LIST &OPTIONAL (TYPE (QUOTE EQL))

Maps the elements of list in a hash-table identified by identifier. func is evaluated on each element and produces two values which are used as key and value for the hash-table.

Function: MAP-PRODUCT FUNC LIST &REST REST-LISTS

Applies func to a product of lists. Example:

  (map-product #'cons '(2 3) '(1 4))
  ⇒ ((2 . 1) (2 . 4) (3 . 1) (3 . 4))

Function: MAP-TREE FUNC TREE &OPTIONAL DEPTH

Maps tree using func. Example:

  (map-tree #'1+ '((1 (2)))) ⇒ ((2 (3)))

Macro: MAPF VAR FUNC

Replaces the value of the variable var by setting it to its map with func.

Function: MAPPEND FUNC &REST LISTS

Map func over lists while appending the results.

Function: MAPPER-COLLECT MAPPER &REST REST-ARGS

Collects the arguments with which a mapping construct calls a given function. E.g.

  (mapper-collect #'mapc '(3 4 5)) ⇒ (3 4 5)

Function: MAPPER-COUNT MAPPER &REST REST-ARGS

Counts the arguments with which a mapping construct calls a given function. E.g.

  (mapper-sum #'mapc '(3 4 5)) ⇒ 3

Function: MAPPER-EVERY TEST MAPPER &REST REST-ARGS

Tests if the test is fulfilled for every argument on which the mapper is called:

  (mapper-every #'plusp #'mapc '(3 4 5)) ⇒ T

Function: MAPPER-SELECT-FIRST MAPPER &REST REST-ARGS

Select the arguments with which a mapping construct calls a given function. E.g.

  (mapper-select-first #'mapc '(3 4 5) '(7 8 9)) ⇒ 3,7

Function: MAPPER-SOME TEST MAPPER &REST REST-ARGS

Tests if the test is fulfilled for some argument on which the mapper is called:

  (mapper-some #'plusp #'mapc '(-3 4 5)) ⇒ T

Function: MAPPER-SUM MAPPER &REST REST-ARGS

Sums the arguments with which a mapping construct calls a given function. E.g.

 (mapper-sum #'mapc '(3 4 5)) ⇒ 12

Function: MAXIMALLY-CONNECTED CONNECTED DISCONNECTED &KEY (TEST (FUNCTION EQL)) (COMBINE (FUNCTION ADJOIN))

Finds a maximally connected set by taking the union of the elements in connected with the sets of disconnected-sets. Returns the maximally connected sets and the remaining disconnected ones. Example:

  (maximally-connected '(1 2) '((3 4) (2 3) (5 6))
                       :test #'intersection :combine #'union)
  ⇒ (1 2 3 4), ((5 6))

Function: MEASURE-TIME FN &OPTIONAL (COUNT 1) REAL-P

Measures the time in seconds needed by count-times executing fn.

Function: MEMOIZE-1 FUNC &KEY (TEST (QUOTE EQL))

Memoizes the function func which should be a non-recursive function of one argument.

Macro: MEMOIZE-EXPR FUNC+ARGS &OPTIONAL TABLE

Memoize expr for its arguments in the table table which should be nil or a hash-table with equal/equalp test.

Function: MEMOIZE-SYMBOL FUNSYM &KEY (TEST (QUOTE EQUAL))

Memoizes multi-argument functions named by the symbol funsym.

Function: MKLIST OBJ

Wraps obj in a list, if it is not already a list.

Function: N-PARTITIONS-OF-K N K

Returns a list of all ordered partitions of k into n natural numbers. Example:

  (n-partitions-of-k 2 3)
   ⇒ ((0 3) (1 2) (2 1) (3 0))

Function: NONEMPTY-SUBSETS SET

Returns a list of all nonempty subsets of set.

Function: ON-LEAVES FUNC TREE

Executes func on the leaves of tree.

Function: ON-SUBTREES FUNC TREE

Calls func on every subtree of tree.

Function: PARTIAL-SUMS SEQ

Returns a sequence of the same type as seq consisting of its partial sums.

Function: PERMUTATION-INVERSE PERM-VEC

Returns the inverse of the permutation given by perm-vec.

Function: PERMUTATION-P PERM

Checks if perm is a possible permutation vector. A permutation pi is characterized by a vector containing the indices from 0,..., length(perm)-1 in some order.

Function: PERMUTATION-SIGNUM PERM

Returns the sign of perm.

Function: PERMUTE PERM INDEX

Functional version of permute-into.

Function: PERMUTE-INTO PERM V RESULT

A permutation perm acts on the vector v by permuting it according to result[i] = v[perm[i]].

Type: POSITIVE-FIXNUM

Positive fixnum tpye.

Function: POSITIVE-N-PARTITIONS-OF-K N K

Returns a list of all positive ordered partitions of k into n natural numbers. Example:

  (positive-n-partitions-of-k 2 3)
  ⇒ ((1 2) (2 1))

Function: POSITIVE-PARTITIONS-OF-K K

Returns a list of all positive ordered partitions of k. Example:

  (positive-partitions-of-k 3) ⇒ ((1 2) (2 1))

Class: PROPERTY-MIXIN

A mixin adding a property slot to the class.

Direct slots:

• PROPERTIES: A property list for storing unstructured information about this object.

Function: QUEUE->LIST QUEUE

Transforms queue to a list.

Function: RANGE &REST ARGS &KEY TO BELOW

Constructor for a range of numbers.

Class: RANGE

Range of numbers for iteration.

Direct slots:

• FROM: Start of range, defaults to 0.
• TO: Inclusive end of range, defaults to infinity.
• BELOW: Exclusive end of range, defaults to infinity.
• BY: Step size.

Function: RCURRY FUNC &REST ARGS

Supplies args to func from the right.

Function: REFERENCE VEC ITERATOR

Reader for the element of vec referenced by iterator.

Function: REQUIRED-ARGUMENT

Calling this function results in an error. Such a call may be used as default form when an argument should be supplied.

Function: SAMEP SEQUENCE &KEY (TEST (FUNCTION EQL)) (KEY (FUNCTION IDENTITY))

Returns t if sequence consists of equal elements.

Function: SANS PLIST &REST KEYS

Removes the items marked by keys from the property list plist. This function was posted at 2.12.2002 to the comp.lang.lisp newsgroup by Erik Naggum.

Function: SET-EQUAL SET1 SET2 &KEY (TEST (FUNCTION EQL))

Tests two sets for equality, e.g.

  (set-equal '(a b) '(b a)) ⇒ T

Function: SET-P LIST

Checks if list is a set, i.e. if no members occur twice.

Function: SPLIT-BY-LENGTH ITEMS LENGTHS

Breaks the list items in pieces of lengths determined by nrins. Example:

  (split-by-length '(1 2 3 4) '(1 3)) ⇒ ((1) (2 3 4))

Function: SQUARE X

Return the square of x.

Function: SUBSETS SET

Returns a list of all subsets of set.

Function: TRANSFER-BB FROM-BB TO-BB ITEMS &KEY ENSURE

Transfer items between the blackboards from-bb and to-bb. When ensure is set, an existing item is not modified.

Function: TRANSLATE ITEM TRANSLATIONS

Performs certain translations from an association table on the string item. Example: (translate "abcdefg" ’(("a" . "x") ("b" . "yz")))

Function: UNBOX BOX

Getter for a boxed object.

Function: VECTOR-LAST VEC

Reader for the last element of vec.

Function: VECTOR-MAP FUNC &REST VECS

Map vec with func to a vector of the same type.

Macro: WITH-ITEMS PROPERTIES BLACKBOARD-FORM &BODY BODY

Work with the items on blackboard corresponding to properties. If some property is a list, the second element is the default value and the third is an alias to be used to refer to this parameter. Example:

  (with-items (&key sol (rhs nil rhs-high)) blackboard
     (setq sol rhs-high))

Function: ZERO-VECTOR DIM ELEMENT-TYPE

Returns a uniform vector for the given element type filled with zeros.