GENERICCL provides a generic function wrapper over various functions in the Common Lisp standard, such as equality predicates and sequence operations. The goal of this wrapper is to provide a standard interface to common operations, such as testing for the equality of two objects, which is extensible to userdefined types.
Usage
The generic function interface is contained in the GENERICCL
package. This package should be used rather than COMMONLISP
, as it
shadows the symbols, in the COMMONLISP
package, which name a
function for which there is a generic function wrapper. GENERICCL
additionally reexports the remaining nonshadowed symbols in
COMMONLISP
.
The GENERICCLUSER package is also provided, which contains
all the symbols in the CLUSER package and GENERICCL . This
package is intended to be used only at the REPL.

Generic Interfaces
The generic function interface is divided into the following categories:
Equality
The equality interface provides functions for testing for equality of objects.
EQUALP is the generic binary equality predicate function to
implement for userdefined types. = and
/= are the nary equality predicates similar to the
functions with the same names in the COMMONLISP
package.
EQUALP
Generic Function: EQUALP A B
Returns true if object A
is equal to object B
.
Methods:

NUMBER NUMBER
Returns true if
A
andB
represent the same numeric value, byCL:=
. 
CHARACTER CHARACTER
Returns true if
A
andB
represent the same character, byCL:CHAR=
. 
CONS CONS
Returns true if the
CAR
ofA
is equal (byEQUALP
) to theCAR
ofB
and if theCDR
ofA
is equal (byEQUALP
) to theCDR
ofB
. 
VECTOR VECTOR
Returns true if
A
andB
are vectors of the same length and each element ofA
is equal (byEQUALP
) to the corresponding element ofB
. 
ARRAY ARRAY
Multidimensional arrays.
Returns true if
A
andB
have the same dimensions and each element ofA
is equal (byEQUALP
) to the corresponding element ofB
. 
STRING STRING
Returns true if both strings are equal, by
CL:STRING=
. 
PATHNAME PATHNAME
Returns true if both
PATHNAME
objects are functionally equivalent, byUIOP:PATHNAMEEQUAL
. 
T T
Default method.
Returns true if
A
andB
are the same object, byCL:EQ
.
LIKEP
Generic Function: LIKEP A B
Returns true if A
is similar to B
, where similarity is defined as
the same as equality however ignoring differences in certain aspects
such as case in strings.

CHARACTER CHARACTER
Returns true if
A
andB
represent the same character ignoring differences in case. Compared usingCL:CHAREQUAL
. 
CONS CONS
Returns true if the
CAR
ofA
is similar (byLIKEP
) to theCAR
ofB
and if theCDR
ofA
is similar (byLIKEP
) to theCDR
ofB
. 
VECTOR VECTOR
Returns true if
A
andB
are vectors of the same length and each element ofA
is similar (byLIKEP
) to the corresponding element ofB
. 
ARRAY ARRAY
Multidimensional arrays.
Returns true if
A
andB
have the same dimensions and each element ofA
is similar (byLIKEP
) to the corresponding element ofB
. 
STRING STRING
Returns true if both strings are equal, ignoring differences in case. Compared using
CL:STRINGEQUAL
. 
T T
Default method.
Returns true if
(EQUALP A B)
returns true.
=
Function: = X &REST XS
Returns true if all objects in XS
are equal (by EQUALP
) to X
.
/=
Function: = X &REST XS
Returns true if at least one object in XS
is not equal (by EQUALP
)
to X
.
Comparison
The comparison interface provides functions for comparing objects in terms of greater than, less than, greater than or equal to and less than or equal to relations.
LESSP, LESSEQUALP, GREATERP, GREATEREQUALP are the
generic binary comparison functions to implement for userdefined
types. It is sufficient to just implement LESSP
as the remaining
functions have default methods that are implemented in terms of
LESSP
.
<, <=, >,
>= are the nary comparison functions similar to
the functions with the same names in the COMMONLISP
package.
LESSP
Generic Function: LESSP A B
Returns true if object A
is less than object B
.
It is sufficient to just implement this function, for
userdefined types, as the rest of the comparison functions have
default (T T ) methods which are implemented in terms of LESSP .

Methods:

NUMBER NUMBER
Returns true if the numeric value of
A
is less than the numeric value ofB
, byCL:<
. 
CHARACTER CHARACTER
Returns true if the character code of
A
is less than the character code ofB
, byCL:CHAR<
. 
STRING STRING
Returns true if the string
A
is lexicographically less thanB
, byCL:STRING<
.
LESSEQUALP
Generic Function: LESSEQUALP A B
Returns true if object A
is less than or equal to object B
.
Methods:

NUMBER NUMBER
Returns true if the numeric value of
A
is less than or equal to the numeric value ofB
, byCL:<=
. 
CHARACTER CHARACTER
Returns true if the character code of
A
is less than or equal to the character code ofB
, byCL:CHAR<=
. 
STRING STRING
Returns true if the string
A
is lexicographically less than or equal toB
, byCL:STRING<=
. 
T T
(or (lessp a b) (equalp a b))
GREATERP
Generic Function: GREATERP A B
Returns true if object A
is greater than object B
.
Methods:

NUMBER NUMBER
Returns true if the numeric value of
A
is greater than the numeric value ofB
, byCL:>
. 
CHARACTER CHARACTER
Returns true if the character code of
A
is greater than the character code ofB
, byCL:CHAR>
. 
STRING STRING
Returns true if the string
A
is lexicographically greater thanB
, byCL:STRING>
. 
T T
Returns true if
A
is not less than or equal toB
, by LESSEQUALP.(not (lessequalp a b))
GREATEREQUALP
Generic Function: GREATEREQUALP A B
Returns true if object A
is greater than or equal to object B
.
Methods:

NUMBER NUMBER
Returns true if the numeric value of
A
is greater than or equal to the numeric value ofB
, byCL:>=
. 
CHARACTER CHARACTER
Returns true if the character code of
A
is greater than or equal to the character code ofB
, byCL:CHAR>=
. 
STRING STRING
Returns true if the string
A
is lexicographically greater than or equal toB
, byCL:STRING>=
. 
T T
Returns true if
A
is not less thanB
, by LESSP.(not (lessp a b))
COMPARE
Generic Function: COMPARE A B
Returns:
:LESS

if
A
is less thanB
. :EQUAL

if
A
is equal toB
. :GREATER

if
A
is greater thanB
.
The default T T
method returns:
:LESS

if
(LESSP A B)
is true. :EQUAL

if
(EQUALP A B)
is true. :GREATER

otherwise.
<
Function: < X &REST XS
Returns true if each argument is less than the following argument, by LESSP.
<=
Function: <= X &REST XS
Returns true if each argument is less than or equal to the following argument, by LESSEQUALP.
>
Function: > X &REST XS
Returns true if each argument is greater than the following argument, by GREATERP.
>=
Function: >= X &REST XS
Returns true if each argument is greater than or equal to the following argument, by GREATEREQUALP.
MIN
Function: MIN X &REST XS
Returns the minimum argument.
The comparisons are performed by LESSP. Any one of the arguments which is less than or equal to the other arguments may be returned.
MAX
Function: MAX X &REST XS
Returns the maximum argument.
The comparisons are performed by GREATERP. Any one of the arguments which is greater than or equal to the other arguments may be returned.
Arithmetic
The arithmetic interface provides generic functions for arithmetic operations.
ADD, SUBTRACT, MULTIPLY, DIVIDE are the generic binary arithmetic functions, and NEGATE is the generic unary negation function, to implement for userdefined types.
+, , *, /
are the nary arithmetic functions similar to the functions with the
same names in the COMMONLISP
package.
ADD
Generic Function: ADD A B
Returns the sum of A
and B
.
Methods:

NUMBER NUMBER
Returns
(CL:+ A B)
.
SUBTRACT
Generic Function: SUBTRACT A B
Returns the difference of A
and B
.
Methods:

NUMBER NUMBER
Returns
(CL: A B)
.
MULTIPLY
Generic Function: MULTIPLY A B
Returns the product of A
and B
.
Methods:

NUMBER NUMBER
Returns
(CL:* A B)
.
DIVIDE
Generic Function: DIVIDE A B
Returns the quotient of A
and B
. If A
is the constant 1
, the
result should be the reciprocal of B
.
Methods:

NUMBER NUMBER
Returns
(CL:/ A B)
.
NEGATE
Generic Function: NEGATE A
Returns the negation of A
.
Methods:

NUMBER
Returns
(CL: A)
.
+
Function: + X &REST XS
Returns the sum of all the arguments, computed by reducing over the argument list with the ADD function.
If no arguments are provided, 0
is returned. If a single argument is
provided it is returned.

Function:  X &REST XS
Returns the difference of all the arguments, computed by reducing over the argument list with the SUBTRACT function.
If only a single argument is provided the negation of that argument is returned, by the NEGATE function.
*
Function: * X &REST XS
Returns the product of all the arguments, computed by reducing over the argument list with the MULTIPLY function.
If no arguments are provided, 1
is returned. If a single argument is
provided it is returned.
/
Function: / X &REST XS
Returns the quotient of all the arguments, computed by reducing over the argument list with the DIVIDE function.
If only a single argument is provided, the reciprocal of the argument,
(DIVIDE 1 X)
, is returned.
1+
Generic Function: 1+ A
Returns A + 1
.
Methods:

NUMBER
Returns
(CL:1+ A)
. 
T
Returns
(ADD A 1)
.
1
Generic Function: 1 A
Returns A  1
.
Methods:

NUMBER
Returns
(CL:1 A)
. 
T
Returns
(SUBTRACT A 1)
.
INCF
Macro: INCF PLACE &OPTIONAL (DELTA 1)
Increments the value of PLACE
by DELTA
, which defaults to 1
,
using the ADD function.
Effectively:
(setf place (add place delta))
DECF
Macro: DECF PLACE &OPTIONAL (DELTA 1)
Decrements the value of PLACE
by DELTA
, which defaults to 1
,
using the SUBTRACT function.
Effectively:
(setf place (subtract place delta))
MINUSP
Generic Function: MINUSP A
Returns true if A
is less than zero.
Methods:

NUMBER
Returns
(CL:MINUSP A)
. 
T
Returns true if
A
compares less than0
, by LESSP.(lessp a 0)
PLUSP
Generic Function: PLUSP A
Returns true if A
is greater than zero.
Methods:

NUMBER
Returns
(CL:PLUSP A)
. 
T
Returns true if
A
compares greater than0
, by GREATERP.(greaterp a 0)
ZEROP
Generic Function: ZEROP A
Returns true if A
is equal to zero.
Methods:

NUMBER
Returns
(CL:ZEROP A)
. 
T
Returns true if
A
is equal to0
, by EQUALP.(equalp a 0)
SIGNUM
Generic Function: SIGNUM A
Returns 1
, 0
or 1
depending on whether A
is negative, is
equal to zero or is positive.
Methods:

SIGNUM
Returns
(CL:SIGNUM A)
. 
T
Returns
1
if(MINUSP A)
is true,0
if(ZEROP A)
is true,1
otherwise.
ABS
Generic Function: ABS A
Returns the absolute value of A
.
Methods:

NUMBER
Returns
(CL:ABS A)
. 
T
If
(MINUSP A)
is true, returns(NEGATE A)
otherwise returnsA
.(if (minusp a) (negate a) a)
EVENP
Generic Function: EVENP A
Returns true if A
is even.
Methods:

NUMBER
Returns
(CL:EVENP A)

T
Returns
(ZEROP (MOD A 2))
ODDP
Generic Function: ODDP A
Returns true if A
is odd.
Methods:

NUMBER
Returns
(CL:ODDP A)

T
Returns
(NOT (EVENP A))
FLOOR
Generic Function: FLOOR N D
Performs the division N/D
if D
is provided, otherwise equivalent
to N/1
, and returns the result rounded towards negative infinity as
the first value, and the remainder N  result * D
as the second return
value.
Methods:

NUMBER
Returns
(CL:FLOOR N D)
ifD
is provided otherwise returns(CL:FLOOR N)
.
CEILING
Generic Function: CEILING N D
Performs the division N/D
if D
is provided, otherwise equivalent
to N/1
, and returns the result rounded towards positive infinity as
the first value, and the N  result * D
as the second return value.
Methods:

NUMBER
Returns
(CL:CEILING N D)
ifD
is provided otherwise returns(CL:CEILING N)
.
TRUNCATE
Generic Function: TRUNCATE N D
Performs the division N/D
if D
is provided, otherwise equivalent
to N/1
, and returns the result rounded towards zero as the first
value, and the remainder N  result * D
as the second return value.
Methods:

NUMBER
Returns
(CL:TRUNCATE N D)
ifD
is provided otherwise returns(CL:TRUNCATE N)
.
ROUND
Generic Function: ROUND N D
Performs the division N/D
if D
is provided, otherwise equivalent
to N/1
, and returns the result rounded towards the nearest integer
as the first value, and the remainder N  result * D
as the second
return value.
If the result lies exactly halfway between two integers, it is rounded to the nearest even integer.
Methods:

NUMBER
Returns
(CL:ROUND N D)
ifD
is provided otherwise returns(CL:ROUND N)
.
MOD
Generic Function: MOD N D
Returns the remainder of the FLOOR operation on N
and D
.
Methods:

NUMBER
Returns
(CL:MOD N D)
. 
T
Returns the second return value of
(FLOOR N D)
.
REM
Generic Function: REM N D
Returns the remainder of the TRUNCATE operation on N
and D
.
Methods:

NUMBER
Returns
(CL:REM N D)
. 
T
Returns the second return value of
(TRUNCATE N D)
.
Objects
The object interface provides miscellaneous functions for manipulating objects.
COPY
Generic Function: COPY OBJECT &KEY &ALLOWOTHERKEYS
Returns a copy of OBJECT
. If OBJECT
is mutable, by some other
functions, then the returned object should be distinct (not EQ
) from
OBJECT
, otherwise the return value may be identical (EQ
) to
OBJECT
.
This function may accept additional keyword arguments which
specify certain options as to how the object should be copied. Methods
specialized on sequences accept a :DEEP keyword parameter, which if
provided and is true a deep copy is returned otherwise a shallow copy
is returned. If a userdefined type acts as a container or sequence
then the COPY method for that type should also accept the DEEP
keyword parameter.

Methods:

CONS
Returns a new list which contains all the elements in
OBJECT
. If:DEEP
is provided and is true, the list returned contains a copy of the elements, copied using(COPY ELEM :DEEP T)
. 
VECTOR
Returns a new vector which contains all the elements in
OBJECT
. If:DEEP
is provided and is true, the vector returned contains a copy of the elements, copied using(COPY ELEM :DEEP T)
. 
ARRAY
MultiDimensional Arrays.
Returns a new array, of the same dimensions as
OBJECT
, which contains all the elements inOBJECT
. If:DEEP
is provided and is true, the array returned contains a copy of the elements, copied using(COPY ELEM :DEEP T)
. 
T
Simply returns
OBJECT
.This method is provided to allow sequences containing arbitrary objects to be copied safely, without signaling a condition, and to avoid having to write simple passthrough methods for each userdefined type.
However this means that if the object, for which there is no specialized copy method, can be mutated, the constraints of the
COPY
function are violated.
DEFSTRUCT
Macro: DEFSTRUCT OPTIONS &REST SLOTS
This is the same as CL:DEFSTRUCT
however a COPY method for the
structure type is automatically generated, which simply calls the
structure’s copier function. If the (:COPIER NIL)
option is
provided, the COPY
method is not generated.
COERCE
Generic Function: COERCE OBJECT TYPE
Coerces OBJECT
to the type TYPE
.
The default (T T
) method simply calls CL:COERCE
.
Iterator
The iterator interface is a generic interface for iterating over the elements of sequences and containers.
Implemented for lists, vectors, multidimensional arrays and HASHMAP's.
(loop
with it = (iterator sequence) ; Create iterator for SEQUENCE
until (endp it) ; Loop until the iterator's end position is reach
do
(pprint (at it)) ; Print element at iterator's position
(advance it)) ; Advance iterator to next position
Base Iterator Type
Structure: ITERATOR
This structure serves as the base iterator type and is used by certain methods of generic functions to specialize on iterators.
All iterators should inherit from (include) ITERATOR
, in order for
methods which specialize on iterators to be invoked.
A COPY method should be implemented for userdefined iterators. 
Iterator Creation
ITERATOR is the highlevel function for creating iterators, whereas MAKEITERATOR AND MAKEREVERSEITERATOR are the generic iterator creation functions to implement for userdefined sequence types.
MAKEITERATOR
Generic Function: MAKEITERATOR SEQUENCE START END
Returns an iterator for the subsequence of SEQUENCE
, identified by
the range [START, END)
.
START
is the index of the first element to iterate over. 0
indicates the first element of the sequence.
END
is the index of the element at which to terminate the iteration,
i.e. 1 + the index of the last element to be iterated over. NIL
indicates iterate till the end of the sequence.
MAKEREVERSEITERATOR
Generic Function: MAKEREVERSEITERATOR SEQUENCE START END
Returns an iterator for the subsequence of SEQUENCE
, identified by
the range [START, END)
, in which the elements are iterated over in
reverse order.
Even though the elements are iterated over in reverse order,
START and END are still relative to the start of the sequence, as
in MAKEITERATOR .

START
is the index of the last element to visit.
END
is the index of the element following the first element to be
iterated over.
ITERATOR
Function: ITERATOR SEQUENCE &KEY (START 0) END FROMEND
Returns an iterator for the subsequence of SEQUENCE
identified by
the range [START, END)
.
START
(defaults to 0
 the start of the sequence) and END
(defaults to NIL
 the end of the sequence) are the start and end
indices of the subsequence to iterate over (see MAKEITERATOR and
MAKEREVERSEITERATOR for more a detailed description).
If FROMEND
is true a reverse iterator is created (by
MAKEREVERSEITERATOR) otherwise a normal iterator is created (by
MAKEITERATOR).
Mandatory Functions
These functions have to be implemented for all userdefined iterators.
AT
Generic Function: AT ITERATOR
Returns the value of the element at the current position of the
iterator ITERATOR
.
The effects of calling this method, after the iterator has reached the end of the subsequence are unspecified. 
ENDP
Generic Function: ENDP ITERATOR
Returns true if the iterator is at the end of the subsequence, false otherwise.
The end of the subsequence is defined as the position past the last element of the subsequence, that is the position of the iterator after advancing it (by ADVANCE) from the position of the last element.
If the subsequence is empty ENDP
should immediately return true.
The default T method calls CL:ENDP since this function
shadows the CL:ENDP function.

Optional Functions
Implementing the following functions for userdefined iterators is optional either because a default method is provided, which is implemented using the mandatory functions, or the function is only used by a select few sequence operations.
START
Generic Function: START ITERATOR
Returns the element at the current position of the iterator, if the
iterator is not at the end of the sequence, otherwise returns NIL
.
The default method first checks whether the end of the iterator has
been reached, using ENDP
, and if not returns the current element
using AT
.
The default method is equivalent to the following:
(unless (endp iterator)
(at iterator))
(SETF AT)
Generic Function: (SETF AT) VALUE ITERATOR
Sets the value of the element at the position, in the sequence, specified by the iterator.
The effects of calling this function when, the iterator is past the end of the subsequence are unspecified. 
Implementing this function is only mandatory if destructive sequence operations will be used. 
Macros
Macros for iteratoring over a generic sequence. Analogous to
CL:DOLIST
.
DOITERS
Macro: DOITERS (&REST ITERS) &BODY BODY
Iterates over one or more sequences with the sequence iterators bound to variables.
Each element of ITERS
is a list of the form (ITVAR
SEQUENCE . ARGS)
, where ITVAR
is the variable to which the
iterator is bound, SEQUENCE
is the sequence which will be iterated
over and ARGS
are the remaining arguments passed to the
ITERATOR function.
The bindings to the ITVAR’s are visible to the forms in `BODY
,
which are executed once for each element in the sequence. After each
iteration the sequence iterators are ADVANCE'd. The loop
terminates when the end of a sequence is reached.
DOITER
Macro: DOITER (ITER &REST ARGS) &BODY BODY
The is the same as DOITERS except only a single sequence is iterated over.
DOSEQ
Macro: DOSEQ (ELEMENT SEQUENCE &REST ARGS) &BODY BODY
Iterates over the elements of SEQUENCE
. ARGS
are the remaining
arguments passed to the ITERATOR function.
The forms in BODY
are executed once for each element, with the value
of the element bound to ELEMENT
. If ELEMENT
is a list, the
sequence element is destructured, as if by DESTRUCTURINGBIND
according to the pattern specified by ELEMENT
.
Collector
The collector interface is a generic interface for accumulating items in a sequence/container.
Implemented for lists, vectors and HASHMAP's.
;; Create collector for the sequence, in this case an empty list
(let ((c (makecollector nil)))
(accumulate c 1) ; Collect 1 into the sequence
(accumulate c 2) ; Collect 2 into the sequence
(extend c '(3 4 5)) ; Collect 3 4 5 into the sequence
(collectorsequence c)) ; Get the resulting sequence => '(1 2 3 4 5)
MAKECOLLECTOR
Generic Function: MAKECOLLECTOR SEQUENCE &KEY FRONT
Returns a collector for accumulating items to the end of the sequence
SEQUENCE
. If :FRONT
is provided and is true, the items are
accumulated to the front of the sequence rather than end.
The collector may destructively modify SEQUENCE however
it is not mandatory and may accumulate items into a copy of SEQUENCE
instead.

ACCUMULATE
Generic Function: ACCUMULATE COLLECTOR ITEM
Accumulates ITEM
into the sequence associated with the collector
COLLECTOR
.
COLLECTORSEQUENCE
Generic Function: COLLECTORSEQUENCE COLLECTOR
Returns the underlying sequence associated with the collector
COLLECTOR
. The sequence should contain all items accumulated up to
the call to this function.
The effects of accumulating items into the sequence, by ACCUMULATE or EXTEND, after this function is called, are unspecified. 
The sequence returned might not be the same object passed to MAKECOLLECTOR. 
EXTEND
Generic Function: EXTEND COLLECTOR SEQUENCE
Accumulates all elements of the sequence SEQUENCE
into the sequence
associated with the collector COLLECTOR
.
If SEQUENCE
is an iterator all elements upto the end of the
iterator (till ENDP returns true) should be accumulated.
Implementing this method is optional as default methods are provided for iterators and sequences, which simply accumulate each element one by one using ACCUMULATE. 
Methods:

T ITERATOR
Accumulates all elements returned by the iterator
SEQUENCE
(till(ENDP SEQUENCE)
returns true), into the sequence associated with the collector. The elements are accumulated one by one using ACCUMULATE.The iterator is copied thus the position of the iterator passed as an argument is not modified. 
T T
Accumulates all elements of
SEQUENCE
, into the sequence associated with the collector. The elements are accumulated one by one using ACCUMULATE.The sequence iteration is done using the Iterator interface.
Sequences
Generic sequence functions.
Creation
The following functions are for creating a sequence into which items will be accumulated using the collector interface.
CLEARED
Generic Function: CLEARED SEQUENCE &KEY &ALLOWOTHERKEYS
Returns a new empty sequence, of the same type and with the same
properties as SEQUENCE
, suitable for accumulating items into it
using the collector interface.
Individual methods may accept keyword parameters which specify certain options of the sequence which is to be created. 
Methods:

LIST
Returns
NIL
. 
VECTOR
Returns an adjustable vector of the same length as
SEQUENCE
, with the fillpointer set to0
.If the
:KEEPELEMENTTYPE
argument is provided and is true, the element type of the new vector is the same as the element type ofSEQUENCE
.
MAKESEQUENCEOFTYPE
Generic Function: MAKESEQUENCEOFTYPE TYPE ARGS
Returns a new empty sequence of type TYPE
. ARGS
are the type
arguments, if any.
The default method creates a builtin sequence of the same type as that returned by:
(makesequence (cons type args) 0)
SEQUENCEOFTYPE
Function: SEQUENCEOFTYPE TYPE
Creates a new sequence of type TYPE
, using
MAKESEQUENCEOFTYPE.
If TYPE
is a list the CAR
of the list is passed as the first
argument, to MAKESEQUENCEOFTYPE
, and the CDR
is passed as the
second argument. Otherwise, if TYPE
is not a list, it is passed as
the first argument and NIL
is passed as the second argument.
Sequence Elements
ELT
Generic Function: ELT SEQUENCE INDEX
Returns the element at position INDEX
in the sequence SEQUENCE
.
Methods:

SEQUENCE T
andVECTOR T
Returns
(CL:ELT SEQUENCE INDEX)
. 
ARRAY INTEGER
MultiDimensional Arrays.
Returns
(ROWMAJORAREF SEQUENCE INDEX)
. 
ARRAY LIST
MultiDimensional Arrays.
If length of
index
matches array’s rank, returns(apply #'aref sequence index)
.
If index’s length is less than the array’s rank, then returns a displaced
array whose dimensions are `sequence’s "unused" dimensions (ie `(nthcdr
(arraydimensions sequence) (length index))
) and which shares storage with the
"subarray" of sequence
specificied by index

HASHTABLE T
Hash Tables.
Returns
(CL:GETHASH INDEX SEQUENCE)
. 
HASHMAP T
Hash Maps.
Returns
(GENERICCL:GET INDEX SEQUENCE)
. 
T T
Creates an iterator for
SEQUENCE
, with start positionINDEX
, and returns the first element returned by the iterator.
(SETF ELT)
Generic Function: (SETF ELT) VALUE SEQUENCE INDEX
Sets the value of the element at position INDEX
in the sequence
SEQUENCE
.
Methods:

T SEQUENCE T
andT VECTOR T
Returns
(SETF (CL:ELT SEQUENCE INDEX) VALUE)
. 
T ARRAY INTEGER
MultiDimensional Arrays.
Returns
(SETF (ROWMAJORAREF SEQUENCE INDEX) VALUE)

ARRAY LIST
MultiDimensional Arrays.
If length of
index
matches array’s rank, returns(setf (apply #'aref sequence index) value)
.
If index’s length is less than the array’s rank, then copies the contents of
`value
to the "subarray" (see genericcl:elt
) specified by index
and then
returns (elt sequence index)
. value’s dimensions must equal the "unused"
dimensions of `sequence
(ie (nthcdr (arraydimensions sequence) (length
index))
).

T HASHTABLE T
Hash Tables.
Returns
(SETF (CL:GETHASH SEQUENCE INDEX) VALUE)
. 
T HASHMAP T
Hash Maps.
Returns
(SETF (GENERICCL:GET SEQUENCE INDEX) VALUE)
. 
T T T
Creates an iterator for
SEQUENCE
, with start positionINDEX
, and sets the value of the element at the starting position of the iterator.
FIRST
Generic Function: FIRST SEQUENCE
Returns the first element in the sequence SEQUENCE
.
Implemented for lists, vectors and multidimensional arrays. For
multidimensional arrays, the first element is obtained by
ROWMAJORAREF
.
The default method is implemented using GENERICCL:ELT, i.e. is equivalent to:
(elt sequence index)
LAST
Generic Function: LAST SEQUENCE &OPTIONAL (N 0)
Returns the N’th element from the last element of the sequence
`SEQUENCE
. N
defaults to 0
which indicates the last element. 1
indicates the second to last element, 2
the third to last and so on.
Implemented for lists, vectors and multidimensional arrays. For multidimensional arrays, the last element is obtained by:
(rowmajoraref sequence ( (arraytotalsize array) 1 n))
The default method is implemented using GENERICCL:ELT, i.e. is equivalent to:
(elt sequence ( (length sequence) 1 n))
The behaviour of this function differs from CL:LAST when
called on lists, it returns the last element rather than the last
CONS cell. The LASTCDR function performs the same function as
CL:LAST .

LASTCDR
Function: LASTCDR LIST &OPTIONAL (N 1)
This function is equivalent to CL:LAST
list function.
Returns the CDR
of the N’th `CONS
cell from the end of the list.
ERASE
Generic Function: ERASE SEQUENCE INDEX
Removes the element at index INDEX
from the sequence SEQUENCE
.
Destructively modifies SEQUENCE
.
Methods:

VECTOR T
Shifts the elements following
INDEX
one element towards the front of the vector and shrinks the vector by one element.Signals a TYPEERROR
if the vector is not adjustable.
This method is not implemented for lists as removing the first element of a list cannot be implemented (efficiently) as a side effect alone. 
Sequence Length
LENGTH
Generic Function: LENGTH SEQUENCE
Returns the number of elements in the sequence SEQUENCE
. If
SEQUENCE
is an iterator, returns the number of remaining elements to
be iterated over.
This function is implemented for all Common Lisp sequences, returning
the length of the sequence (by CL:LENGTH
), multidimensional arrays,
returning the total number of elements in the array (by
ARRAYTOTALSIZE
), and HASHMAP's / hash tables, returning the
total number of elements in the map/table.
The following default methods are implemented:

ITERATOR
Returns the number of elements between the iterator’s current position (inclusive) and the end of the iterator’s subsequence.
This is implemented by advancing the iterator (by ADVANCE) till ENDP returns true, thus is a linear
O(n)
time operation.More efficient specialized methods are provided for iterators to sequences for which the size is known.

T
Returns the length of the generic sequence by creating an iterator to the sequence and calling the ITERATOR specialized method. Thus this is a linear
O(n)
, in time, operation unless a more efficient method, which is specialized on the sequence’s iterator type, is implemented.
EMPTYP
Generic Function: EMPTYP SEQUENCE
Returns true if the sequence SEQUENCE
is empty.
Implemented for lists, vectors, multidimensional arrays (always
returns NIL
) and HASHMAP's.
The default returns true if ENDP returns true for a newly created
iterator for SEQUENCE
.
CLEAR
Generic Function: CLEAR SEQUENCE
Destructively removes all elements from the sequence SEQUENCE
.
Implemented for vectors and HASHMAP's.
ADJUSTSIZE
Generic Function: ADJUSTSIZE SEQUENCE N &KEY ELEMENT
Return a new sequence containing the same elements as SEQUENCE
however
with its size changed to N
.
If N
is less than the number of elements in SEQUENCE
, the returned
sequence contains only the first N elements of SEQUENCE
.
If N
is greater than the number of elements in SEQUENCE
, the
returned sequence contains all the elements of SEQUENCE
with an
additional (LENGTH SEQUENCE)  N
elements initialized to the value
of ELEMENT
.
NADJUSTSIZE
Generic Function: NADJUSTSIZE SEQUENCE N &KEY ELEMENT
Return a new sequence containing the same elements as SEQUENCE
however with its size changed to N
.
SEQUENCE may be destructively modified.

If N
is less than the number of elements in SEQUENCE
, the returned
sequence contains only the first N elements of SEQUENCE
.
If N
is greater than the number of elements in SEQUENCE
, the
returned sequence contains all the elements of SEQUENCE
with an
additional (LENGTH SEQUENCE)  N
elements initialized to the value
of ELEMENT
.
Subsequences
SUBSEQ
Generic Function: SUBSEQ SEQUENCE START &OPTIONAL END
Returns a new sequence that contains the elements of SEQUENCE
at the
positions in the range [START, END)
. If SEQUENCE
is an iterator,
an iterator for the subsequence relative to the current position of
the iterator is returned.
START
is the index of the first element of the subsequence, with 0
indicating the start of the sequence. if SEQUENCE
is an iterator,
START
is the number of times the iterator should be ADVANCE'd to
reach the first element of the subsequence.
END
is the index of the element following the last element of the
subsequence. NIL
(the default) indicates the end of the sequence. If
SEQUENCE
is an iterator, END
is the number of times the iterator
should be ADVANCE'd till the end position is reached.
Methods:

SEQUENCE T
Returns the subsequence using
CL:SUBSEQ
. 
ITERATOR T
Returns a subsequence iterator which wraps a copy of the original iterator.

T T
(SETF SUBSEQ)
Generic Function: (SETF SUBSEQ) NEWSEQUENCE SEQUENCE START &OPTIONAL END
Replaces the elements of SEQUENCE
at the positions in the range
[START, END)
, with the elements of NEWSEQUENCE
. The shorter
length of NEWSEQUENCE
and the number of elements between START
and END
determines how many elements of SEQUENCE
are actually
modified.
See SUBSEQ for more details of how the START
and END
arguments are
interpreted.
Methods:

SEQEUNCE SEQUENCE T
Sets the elements of the subsequence using
(SETF CL:SUBSEQ)
. 
T T T
Sequence Operations
Generic function wrappers, which are identical in behavior to their
counterparts in the COMMONLISP
package, are provided for the
following sequence operations:

FILL

REPLACE

REDUCE

COUNT

COUNTIF

COUNTIFNOT

FIND

FINDIF

FINDIFNOT

POSITION

POSITIONIF

POSITIONIFNOT

SEARCH

MISMATCH

REVERSE

NREVERSE

SUBSTITUTE

NSUBSTITUTE

SUBSTITUTEIF

NSUBSTITUTEIF

SUBSTITUTEIFNOT

NSUBSTITUTEIFNOT

REMOVE

DELETE

REMOVEIF

DELETEIF

REMOVEIFNOT

DELETEIFNOT

REMOVEDUPLICATES

DELETEDUPLICATES
Two methods are implemented, for all functions, which are specialized on the following types:

CL:SEQUENCE
Simply calls the corresponding function in the
COMMONLISP
package. 
T
Implements the sequence operation for generic sequences using the iterator interface.
The nondestructive functions only require that the Mandatory Iterator Functions, the Collector interface and CLEARED method are implemented for the sequence’s type.
The destructive versions may additionally require that the optional (SETF AT) method is implemented as well.
The default value of the :TEST keyword arguments is
GENERICCL:EQUALP. This should be the default value when
implementing methods for userdefined sequence types. The :TESTNOT
keyword arguments have been removed.

The following functions are identical in behavior to their CL
counterparts, however are reimplemented using the iterator
interface. Unlike the functions in the previous list, these are not
generic functions since they take an arbitrary number of sequences as
arguments.

EVERY

SOME

NOTEVERY

NOTANY
The following functions either have no CL
counterparts or differ
slightly in behavior from their CL
counterparts:
MERGE
Generic Function: MERGE SEQUENCE1 SEQUENCE2 PREDICATE &KEY
Returns a new sequence, of the same type as SEQUENCE1
, containing
the elements of SEQUENCE1
and SEQUENCE2
. The elements are ordered
according to the function PREDICATE
.
Unlike CL:MERGE this function is nondestructive.

NMERGE
Generic Function: MERGE SEQUENCE1 SEQUENCE2 PREDICATE &KEY
Same as MERGE
however is permitted to destructively modify either
SEQUENCE1
or SEQUENCE2
.
SORT
Generic Function: SORT SEQUENCE &KEY TEST KEY
Returns a new sequence of the same type as SEQUENCE
, with the same
elements sorted according to the order determined by the function
TEST
. TEST
is GENERICCL:LESSP by default.
Unlike CL:SORT this function is nondestructive.

STABLESORT
Generic Function: STABLESORT SEQUENCE &KEY TEST KEY
Same as SORT
however the sort operation is guaranteed to be
stable. TEST
is GENERICCL:LESSP by default.
Unlike CL:STABLESORT this function is nondestructive.

NSORT
Generic Function: NSORT SEQUENCE &KEY TEST KEY
Same as SORT
however is permitted to destructively modify
SEQUENCE
.
STABLENSORT
Generic Function: STABLENSORT SEQUENCE &KEY TEST KEY
Same as STABLESORT
however is permitted to destructively modify
SEQUENCE
.
CONCATENATE
Generic Function: CONCATENATE SEQUENCE &REST SEQUENCES
Returns a new sequence, of the same type as SEQUENCE
, containing all
the elements of SEQUENCE
and of each sequence in SEQUENCES
, in the
order they are supplied.
Unlike CL:CONCATENATE does not take a result type
argument.

NCONCATENATE
Generic Function: NCONCATENATE RESULT &REST SEQUENCES
Destructively concatenates each sequence in SEQUENCES
to the
sequence RESULT
.
Returns the result of the concatenation.
Whilst this function is permitted to destructively modify
RESULT and SEQUENCES , it is not required and may return a new
sequence instead. Thus do not rely on this function for its side
effects.

MAP
Generic Function: MAP FUNCTION SEQUENCE &REST SEQUENCES
Creates a new sequence, of the same type as SEQUENCE
(by
CLEARED), containing the result of applying FUNCTION
to each
element of SEQUENCE and each element of each SEQUENCE
in
SEQUENCES
.
This function is equivalent (in behavior) to the CL:MAP
function except the resulting sequence is always of the same type as
the first sequence passed as an argument, rather than being determined
by a type argument.

NMAP
Generic Function: NMAP RESULT FUNCTION &REST SEQUENCES
Destructively replaces each element of RESULT
with the result of
applying FUNCTION
to each element of RESULT
and each element of
each sequence in SEQUENCES.
Returns the resulting sequence.
This function is similar in behavior to CL:MAPINTO with
the exception that if RESULT is a vector, then FUNCTION is only
applied on the elements upto the fill pointer i.e. the fillpointer
is not ignored.

Whilst this function is permitted to modify RESULT , it is
not required and may return the result in a new sequence instead. Thus
do not rely on this function for its side effects.

MAPINTO
Generic Function: MAPINTO RESULT FUNCTION &REST SEQUENCES
Applies FUNCTION
on each element of each sequence in SEQUENCES
and
accumulates the result in RESULT, using the Collector interface.
Returns the resulting sequence.
Whilst this function is permitted to modify RESULT , it is
not required and may return the result in a new sequence instead. Thus
do not rely on this function for its side effects.

MAPTO
Generic Function: MAPTO TYPE FUNCTION &REST SEQUENCES
Applies FUNCTION
to each element of each sequence in SEQUENCES
and
stores the result in a new sequence of type TYPE
(created using
SEQUENCEOFTYPE). Returns the sequence in which the results of
applying the function are stored.
This function is equivalent in arguments, and almost
equivalent in behavior, to CL:MAP . The only difference is that if
TYPE is a subtype of vector, the vector returned is adjustable with
a fillpointer. A NIL type argument is not interpreted as do not
accumulate the results, use FOREACH for that.

MAPEXTEND
Generic Function: MAPEXTENDTO FUNCTION SEQUENCE &REST SEQUENCES
Applies FUNCTION
to each respective element of SEQUENCE
, and of
each sequence in SEQUENCES
, accumulating, using the EXTEND
method of the Collector Interface, the elements of the result,
which is expected to be a sequence, in a sequence of the same type as
SEQUENCE
. The resulting sequence is returned.
MAPEXTENDTO
Generic Function: MAPEXTENDTO TYPE FUNCTION &REST SEQUENCES
Applies FUNCTION
to each respective element of each sequence in
SEQUENCES
, and accumulates, using the EXTEND method of the
Collector Interface, the elements of the result, which is expected
to be a sequence, in a sequence of type TYPE
, created using
SEQUENCEOFTYPE. The resulting sequence is returned.
MAPEXTENDINTO
Generic Function: MAPEXTENDINTO RESULT FUNCTION &REST SEQUENCES
Applies FUNCTION
to each respective element of each sequence in
SEQUENCES
, and accumulates, using the EXTEND method of the
Collector Interface, the elements of the result, which is expected
to be a sequence, in the sequence RESULT
. The resulting sequence is
returned.
RESULT may be destructively modified, however that is not
guaranteed thus this function should only be used for its return
value, not its side effects.

FOREACH
Function: FOREACH &REST SEQUENCES
Applies FUNCTION
on each element of each sequence in SEQUENCES
.
Returns NIL
.
Lazy Sequences
Lazy sequences are sequences in which the elements are only computed when they are actually referenced, rather than being computed immediately.
Lazy sequences are implemented with LAZYSEQ
structure which is
similar to a CONS
cell, however the CDR
, the TAIL
slot of the
LAZYSEQ
structure, stores a function which computes and returns the
remainder of the sequence, rather than storing the sequence directly.
LAZYSEQ Structure
Structure: LAZYSEQ
Lazy sequence analogous to a CONS
.
HEAD

The first element of the sequence. Can be accessed with the
LAZYSEQHEAD
accessor function. TAIL

A function of zero arguments which returns a
LAZYSEQ
containing the remaining elements in the sequence. If there are no more elements the function returnsNIL
. Can be accessed with theLAZYSEQTAIL
accessor function.

EQUALP
function. 
COPY
function. Accepts the:DEEP
keyword parameter which indicates whether the elements should also be copied. 
COERCE
function. 
Mandatory Functions, of the Iterator interface.

MAKECOLLECTOR
function of the Collector interface.The method specialized on LAZYSEQ
's returns a collector for aLIST
since it does not make sense to be collecting items, which have already been evaluated, into aLAZYSEQ
. 
SUBSEQ function which returns the subsequence as a
LAZYSEQ
. 
Methods, specialized on
LAZYSEQ
, are implemented for the following Sequence Operations and their destructive counterparts:
REMOVE

REMOVEIF

REMOVEIFNOT

SUBSTITUTE

SUBSTITUTEIF

SUBSTITUTEIFNOT

REMOVEDUPLICATES
These methods return a
LAZYSEQ
with the sequence operation 'lazily' applied to the sequence.The destructive versions are identical to the nondestructive versions. 
MAKELAZYSEQ
Function: MAKELAZYSEQ HEAD TAIL
Creates a LAZYSEQ
with the HEAD
slot initialized to HEAD
and
the TAIL
slot initialized to TAIL
.
TAIL must be a function of zero arguments that returns
either a LAZYSEQ containing the remaining elements in the sequence
or NIL indicating there are no more elements.

For efficiency the function in TAIL should only compute the
remainder of the sequence the first time it is called. Remaining calls
to the function should simply return the previously computed result.

The LAZYSEQ macro automatically wraps the
form, which returns the remainder of the sequence, in a function.

LAZYSEQ Macro
Macro: LAZYSEQ HEAD &OPTIONAL TAIL
Creates a LAZYSEQ
instance with the HEAD
slot initialized to
HEAD
and the TAIL
slot initialized to a function which evaluates
the form TAIL
.
The function only evaluates TAIL the first time it is
call. Subsequent calls will simply return the previously computed
result.

COERCE Methods
The following COERCE
methods are provided which specialize on
LAZYSEQ
's.

LAZYSEQ (EQL 'LIST)
Returns a list containing all the elements in the
LAZYSEQ
.If the LAZYSEQ
is an infinite sequence, this function will never terminate.
CONCATENATE Methods
Method: CONCATENATE LAZYSEQ &REST SEQUENCES
Method: NCONCATENATE LAZYSEQ &REST SEQUENCES
Method: CONCATENATETO (EQL 'LAZYSEQ) &REST SEQUENCES
Concatenates sequences to a lazy sequence.
The concatenation is done lazily, that is the elements of the
sequences, in SEQUENCES
, are only added to the lazy sequence when
elements past the end of the LAZYSEQ
, passed in the first argument,
are referenced.
The CONCATENATETO
method returns a lazy sequence containing the
concatenation of SEQUENCES
. Like CONCATENATE
and NCONCATENATE
the concatenation is done lazily.
NCONCATENATE is identical to CONCATENATE , that is the
LAZYSEQ is not destructively modified.

MAP Methods
Method: MAP FUNCTION LAZYSEQ &REST SEQUENCES
Method: NMAP FUNCTION LAZYSEQ &REST SEQUENCES
Method: MAPINTO LAZYSEQ FUNCTION &REST SEQUENCES
Method: MAPTO (EQL 'LAZYSEQ) FUNCTION &REST SEQUENCES
Applies a function on each element of the LAZYSEQ
and of each
sequence in SEQUENCES
.
The result is a LAZYSEQ
with the function applied lazily to each
element, that is it is only applied when that element is referenced.
The MAPTO
method returns the result, of lazily applying the
function on each element of each sequence in SEQUENCES
, in a
LAZYSEQ
.
NMAP and MAPINTO do not destructively modify the LAZYSEQ
but return a new sequence instead.

Utilities
RANGE
Function: RANGE START &OPTIONAL END STEP
Returns a LAZYSEQ
containing all numbers in the range [START,
END)
.
If END
is NIL
, an infinite sequence, without an upper bound, is
returned.
STEP
, defaults to 1
, is the delta by which each number is incremented
to obtain the next successive number in the sequence.
Generic HashTables
This interface provides a hashtable data structure with the generic function HASH as the hash function and the generic function GENERICCL:EQUALP as the key comparison function. This allows the hashtables to utilize keys of userdefined types, whereas the keys of standard hash tables are limited to numbers, characters, lists and strings.
The generic hashtables are implemented using
CLCUSTOMHASHTABLE. If
the Common Lisp implementation supports creating hashtables with
userdefined hash and comparison functions, standard hashtables are
used. However if the implementation does not support userdefined hash
and comparison functions, a fallback solution is used, which is a
custom hashtable implementation on top of standard hashtables. The
HASHMAP structure wraps the custom hashtable which allows
methods methods to be specialized on a single type HASHMAP
regardless of whether standard or custom hashtables are used. If the
HASHMAP
wrapper were not used, two identical methods would have to
be implemented, one specializing on standard hashtables and one
specializing on custom hashtables. More identical methods would have
to be implemented if the method has hashtable specializers for more
than one arguments, leading to a combinatorial explosion.
The functions in this interface are specialized on the HASHMAP
type, due to the issue described above, thus use this type, created
with MAKEHASHMAP, rather than builtin hashtables. If a
hashtable is obtained from an external source, use HASHMAP or
ENSUREHASHMAP to convert it to a HASHMAP
.
Standard HashTable Analogues:
CL:HASHTABLE 
HASHMAP 

GETHASH 
GET 
HASHTABLECOUNT 
LENGTH 
REMHASH 
ERASE 
CLRHASH 
CLEAR 
HASHMAP
Structure: HASHMAP
with slots: TABLE
Function: HASHMAP TABLE
The HASHMAP
structure wraps a standard HASHTABLE
or
CUSTOMHASHTABLE
. The TABLE
slot, accessed with HASHMAPTABLE
,
stores the underlying hashtable.
The HASHMAP
function creates a hashmap wrapping a hash table
passed as its only argument.
Implemented Interfaces
The iterator interface is implemented for HASHMAP
's. Each element
returned by the iterator is a CONS
with the key in the CAR
and the
corresponding value in the CDR
. The order in which the entries are
iterated over is unspecified. Likewise it is unspecified which entries
will be iterated over if START
is nonzero and/or END
is nonNIL,
the only guarantee being that END  START
entries are iterated
over. The reverse iterator iterates over the entries in the same order
as the normal iterator due to the order of iteration being
unspecified.
The (SETF AT) method for the HASHMAP
iterator sets the value
corresponding to the key of the current entry, being iterated over, to
the value passed as the argument to SETF
.
The collector interface is implemented for HASHMAP
's. The
ACCUMULATE method expects a CONS
where the CAR
is the key of
the entry to create and the CDR
is the corresponding value.
An EQUALP method is implemented for HASHMAP
's which returns
true if both maps contain the same number of entries and each key in
the first map is present in the second map, with the corresponding
value in the first map equal (by EQUALP
) to the corresponding value
in the second
map.
if the two maps have different test functions, the EQUALP
method is not necessarily symmetric i.e. (EQUALP A B) does not imply
(EQUALP B A) .

A LIKEP method is implemented for HASHMAP
's, which is
similar to the EQUALP
method, however the keys and values are
compared using LIKEP
.
A COPY method is implemented for HASHMAP
's which by default
creates a new map with the same entries as the original map. If :DEEP
T
is provided the values (but not the keys as they should be
immutable) are copied by (COPY VALUE :DEEP T)
.
MAKEHASHMAP
Function: MAKEHASHMAP &KEY TEST &ALLOWOTHERKEYS
Creates a HASHMAP
wrapping a hash table with test function TEST
,
which defaults to #'GENERICCL:EQUALP
.
TEST
may be one of the following:
GENERICCL:EQUALP

A hash table with hash function HASH and comparison function GENERICCL:EQUALP is created.
LIKEP

A hash table with hash function LIKEHASH and comparison function LIKEP is created.
TEST
may also be a standard hashtable test specifier, in which case
a native hash table is created, wrapped in a HASHMAP
.
The function accepts all additional arguments (including
implementation specific arguments) accepted by CL:MAKEHASHTABLE
.
ENSUREHASHMAP
Function: ENSUREHASHMAP THING
If MAP
is a HASHMAP returns it, otherwise if MAP
is a
HASHTABLE
or CUSTOMHASHTABLE
returns a HASHMAP
which wraps
it. Signals an error if MAP
is not of the aforementioned types.
HASHMAPTEST
Function: HASHMAPTEST MAP
Returns the test function, as a symbol, of the underlying hash table.
On some implementations the return value is not
GENERICCL:EQUALP , even if the hash table has HASH and
GENERICCL:EQUALP as its hash and comparison functions.

HASH
Generic Function: HASH OBJECT
Hash function for hash tables with the GENERICCL:EQUALP
test
specifier.
Returns a hash code for OBJECT
, which should be a nonnegative
fixnum. If two objects are equal (under GENERICCL:EQUALP)
then the hash codes, for the two objects, returned by HASH
, should
also be equal.
The default method calls CL:SXHASH
which satisfies the constraint
that (CL:EQUAL X Y)
implies (= (CL:SXHASH X) (CL:SXHASH
Y))
.
Currently no specialized method is provided for container/sequence objects such as lists. The default method does not violate the constraint for lists (but does violate the constraints for nonstring vectors) as keys, provided they only contain numbers, characters, symbols, strings and other lists as elements. 
LIKEHASH
Generic Function: LIKEHASH OBJECT
Hash function for hash tables with the LIKEP
test
specifier.
Returns a hash code for OBJECT
, which should be a nonnegative
fixnum. If two objects are equal (under LIKEP) then the hash
codes, for the two objects, returned by LIKEHASH
, should also be
equal.
Methods which satisfy these constraints are provided for strings,
characters, lists, vectors and multidimensional arrays. The default
method calls the HASH
function.
GET
Generic Function: GET KEY MAP &OPTIONAL DEFAULT
Returns the value of the entry corresponding to the key KEY
in the
map MAP
. If the MAP
does not contain any entry with that key,
DEFAULT
is returned. The second return value is true if an entry
with key KEY
was found in the map, false otherwise.
Methods are provided for HASHMAP
's, standard HASHTABLE
's,
association lists (ALISTS
) and property lists (PLISTS
). For
ALISTS
the EQUALP key comparison function is used. For PLISTS
the EQ
key comparison function is used.
(SETF GET)
Generic Function: (SETF GET) VALUE KEY MAP &OPTIONAL DEFAULT
Sets the value of the entry corresponding to the key KEY
in the map
MAP
. DEFAULT
is ignored.
Only a method for HASHMAPS and HASHTABLES is
provided.

ENSUREGET
Macro: ENSUREGET KEY MAP &OPTIONAL DEFAULT
Like GET
however if KEY
is not found in MAP
it is added, by
(SETF GET)
with the value DEFAULT
.
The first return value is the value corresponding to the key KEY
, or
DEFAULT
if KEY
is not found in MAP
. The second return value is
true if KEY
was found in MAP
, false otherwise.
ERASE Method
Method: ERASE (MAP HASHMAP) KEY
Removes the entry with key KEY
from MAP
.
Returns true if the map contained an entry with key KEY
.
HASHMAPALIST
Function: HASHMAPALIST MAP
Returns an association list (ALIST
) containing all the entries in
the map MAP
.
ALISTHASHMAP
Function: ALISTHASHMAP ALIST &REST ARGS
Returns a HASHMAP containing all entries in the association list
ALIST
. ARGS
are the additional arguments passed to
MAKEHASHMAP.
MAPKEYS
Generic Function: MAPKEYS MAP
Returns a sequence containing all the keys in the map MAP
.
Specialized only on HASHMAP 's and CL:HASHTABLE 's.

MAPVALUES
Generic Function: MAPVALUES MAP
Returns a sequence containing all the values in the map MAP
.
Specialized only on HASHMAP 's and CL:HASHTABLE 's.

COERCE Methods
The following COERCE
methods are provided for HASHMAPS
:

HASHMAP (EQL 'ALIST)
Returns an association list (
ALIST
) containing all the entries in the map. Equivalent to HASHMAPALIST. 
HASHMAP (EQL 'PLIST)
Returns a property list (
PLIST
) containing all the entries in the map.
Set Operations
The set interface provides generic functions for performing set operations and implementations of those operations for a hashset data structure.
Generic function wrappers are provided over the following Common Lisp set operation functions:

SUBSETP

ADJOIN

INTERSECTION

NINTERSECTION

SETDIFFERENCE

NSETDIFFERENCE

SETEXCLUSIVEOR

NSETEXCLUSIVEOR

UNION

NUNION
For each function, methods specializing on LISTS
, which simply call
the corresponding function in the CL
package, and HASHMAP's are
implemented. Each function accepts all keyword arguments accepted by
the corresponding CL
functions however they are ignored by the
HASHMAP
methods.
HASHMAP's may be used as sets, in which case the set elements are stored in the keys. The values of the map’s entries are ignored by the set operations, thus the map values of the sets returned, by the set operation functions, are unspecified. 
ADJOIN
Generic Function: ADJOIN ITEM SET &KEY &ALLOWOTHERKEYS
Returns a new set, of the same type as SET
, which contains ITEM
and all elements in SET
.
This function is nondestructive. A new set is always returned even if
SET is a HASHMAP / HASHSET.

Accepts all keyword arguments accepted by CL:ADJOIN however
they are ignored by the HASHMAP method.

NADJOIN
Generic Function: ADJOIN ITEM SET &KEY &ALLOWOTHERKEYS
Same as ADJOIN however is permitted to destructively modify SET
.
The set returned is EQ to SET in the case of SET
being a HASHMAP however is note required to be EQ and is not
EQ if SET is a list. Thus this function should not be relied upon
for its side effects.

Implemented for both lists and HASHMAP's. 
MEMBERP
Generic Function: MEMBERP ITEM SET &KEY &ALLOWOTHERKEYS
Returns true if ITEM
is an element of the set SET
.
Implemented for both lists and HASHMAP's. All keyword arguments
accepted by CL:MEMBER are accepted, however are ignored by the
HASHMAP method.

HASHSET
Structure: HASHSET
A hashset is a HASHMAP however it is used to indicate that only
the keys are important. This allows the EQUALP and COPY
methods, specialized on `HASHSET’s to be implemented more
efficiently, than the methods specialized on HASHMAP
's, as the
map values are not compared/copied.
The implementation of the Iterator interface for HASHSETS
differs
from the implementation for HASHMAPS
in that only the set elements,
i.e. the keys of the underlying hash table, are returned rather than
the keyvalue pairs.
The set operations are implemented both for HASHMAP 's and
HASHSET 's.

HASHTABLESET
Function: HASHTABLESET TABLE
Returns a HASHSET
structure wrapping the standard HASHTABLE
or
CUSTOMHASHTABLE
.
MAKEHASHSET
Function: MAKEHASHSET &KEY &ALLOWOTHERKEYS
Returns a new empty HASHSET.
Accepts the same keyword arguments as MAKEHASHMAP. The default
TEST
function is GENERICCL:EQUALP.
COERCE Methods
The following COERCE
Methods are provided:

LIST (EQL 'HASHSET)
Returns a
HASHSET
containing the elements in the list.
Math Functions
Generic function wrappers are provided over a number of math
functions. Methods specialized on NUMBER
are provided, which simply
call the corresponding functions in the CL
package. The idea of this
interface is to allow the mathematical functions to be extended to
vectors and matrices. This interface might not used as often as the
previous interfaces, thus is contained in a separate package
GENERICMATHCL
which exports all symbols exported by GENERICCL
and shadows the math functions.
Generic function wrappers are provided for the following functions:

SIN

COS

TAN

ASIN

ACOS

ATAN

SINH

COSH

TANH

ASINH

ACOSH

ATANH

EXP

EXPT

LOG

SQRT

ISQRT

REALPART

IMAGPART

CIS

CONJUGATE

PHASE

NUMERATOR

DENOMINATOR

RATIONAL

RATIONALIZE
Miscellaneous
DEFCONSTANT
Macro: DEFCONSTANT SYMBOL VALUE &OPTIONAL DOCUMENTATION
Ensures that SYMBOL
is a constant with a value that is equal, by
GENERICCL:EQUALP
to VALUE
. This means that if SYMBOL
already
names a constant, which occurs when the DEFCONSTANT
form is
reevaluated, no condition will be signalled if its value is equal (by
GENERICCL:EQUALP
) to VALUE
.
Implemented using ALEXANDRIA:DEFINECONSTANT

System GENERICCL.UTIL
The system GENERICCL.UTIL
provides additional utilities implemented
on top of GENERICCL
. These utilities are contained in the package
GENERICCL.UTIL
.
Lazy Sequence Utilities
REPEAT
Function: REPEAT X &OPTIONAL N TYPE
Create a lazy sequence containing N
elements with the value X
. If
N
is NIL
or is not provided, an infinite sequence is returned.
If TYPE
is nonNIL
a sequence of type TYPE
is returned. The
sequence is created using the SEQUENCEOFTYPE function, and the
elements are accumulated into the sequence using the Collector
interface.
REPEATEDLY
Function: REPEATEDLY F &OPTIONAL N TYPE
Create a lazy sequence containing N
elements, with each element each
being the result of an application of the function F
on no
arguments. If N
is NIL
or not provided, an infinite sequence is
returned.
If TYPE
is nonNIL
a sequence of type TYPE
is returned. The
sequence is created using the SEQUENCEOFTYPE function, and the
elements are accumulated into the sequence using the Collector
interface.
ITERATE
Function: ITERATE F X &KEY INITIAL
Return an infinite lazy sequence where each element is the result of
applying the function F
on the previous element.
IF the keyword argument INITIAL
is true, the first element of the
sequence is X
, otherwise the first element is the result of applying
F
on X
.
FITERATE
Function: FITERATE F X &KEY INIITIAL
Deprecated alias for ITERATE
CYCLE
Function: CYCLE SEQUENCE
Return a lazy sequence containing an infinite repetition of the
elements in SEQUENCE
.
The resulting sequence contains the elements of SEQUENCE
in order,
with the last element of SEQUENCE
followed by the first, and
remaining, elements.
Optimization
There is an overhead associated with generic functions. Code making
use of the generic function interface will be slower than code which
calls the CL
functions directly, due to the cost of dynamic method
dispatch. For most cases this will not result in a noticeable decrease
in performance, however for those cases where it does there is an
optimization.
This library is built on top of STATICDISPATCH, which is a library that allows genericfunction dispatch to be performed statically, at compiletime, rather than dynamically, at runtime. The library allows a call to a generic function to be replaced with the body of the appropriate method, which is selected based on the type declarations of its arguments.
For a generic function call to be inlined, the generic function has to
be declared inline (either locally or globally), and the arguments
must either have type declarations (if they are variables), or be
surrounded in a THE
form.
(let ((x 1))
(declare (inline equalp)
(type number x))
(equalp x (the number (+ 3 4))))
This will result in the call to the EQUALP
function being replaced
with the body of the NUMBER NUMBER
method.
The nargument equality, comparison and arithmetic functions also have
associated compilermacros which replace the calls to the nargument
functions with multiple inline calls to the binary functions, e.g. (=
1 2 3)
is replaced with (and (equalp 1 2) (equalp 1 3))
.
Thus the following should also result in the EQUALP
function calls
being statically dispatched, though this has not yet been tested:
(let ((x 1))
(declare (inline equalp)
(type number x))
(= x (the number (+ 3 4))))
STATICDISPATCH requires the ability to extract TYPE and
INLINE declarations from implementation specific environment
objects. This is provided by the
CLENVIRONMENTS
library however in order for it to work on all supported
implementations, the ENABLEHOOK function (exported by
GENERICCL ) has to be called at some point before the generic
function call is compiled.

See STATICDISPATCH and CLENVIRONMENTS for more information about these optimizations and the current limitations.