cl-enumeration

API Reference

enumerations

The CL-ENUMERATIONS project contains a Common Lisp Java-like enumeration/iteration library and protocol. Most basic Common Lisp types are handled. The project page can be found at http://common-lisp.net/project/cl-enumeration.

IT.UNIMIB.DISCO.MA.COMMON-LISP.EXTENSIONS.DATA-AND-CONTROL-FLOW.ENUMERATIONS

The CL Extensions Enumeration Package.

The package containing the API for a generic enumeration protocol in
Common Lisp.


Notes:

The package name is long because it indicates how to position the
library functionality within the breakdown in chapters of the ANSI
specification.

The lower-case "enum" package nickname is provided in order to appease
ACL Modern mode.

The "CL.EXT..." nicknames are provided as a suggestion about how to
'standardize' package names according to a meaninguful scheme.
  • Condition NO-SUCH-ELEMENT  (ERROR)
    The condition signalled when no reasonable element is available. Many methods (e.g., NEXT) signal this condition if no element is available in and ENUMERATION of some (enumerable) object.
  • Class ENUMERATION
    The CL Extensions Enumeration Class. The 'root' of all the different enumeration classes.
    ENUMERATED-OBJECT   Reader: ENUMERATION-OBJECT
    CURSOR   Accessor: ENUMERATION-CURSOR
  • Generic-Function ENUMERATIONP (x)
  • Method ENUMERATIONP ((x t))
  • Method ENUMERATIONP ((x t))
  • Method ENUMERATIONP ((x t))
  • Generic-Function ENUMERATE (enumerable-item &key start end &allow-other-keys)
    Creates a (specialized) ENUMERATION object. If applicable START and END delimit the range of the actual enumeration. The generic function ENUMERATE is the main entry point in the ENUMERATIONS machinery. It takes a CL object (ENUMERABLE-ITEM) and some additional parameters, which may or may not be used depending on the type of the object to be enumerated. Arguments and Values: ENUMERABLE-ITEM : an Common Lisp object START : an object (usually a non-negative integer) END : an object or NIL result : an ENUMERATION instance Exceptional Situations: ENUMERATE calls MAKE-INSTANCE on the appropriate ENUMERATION sub-class. The instance initialization machinery may signal various errors. See the documentation for each ENUMERATION sub-class for details.
  • Generic-Function HAS-MORE-ELEMENTS-P (x)
  • Method HAS-MORE-ELEMENTS-P ((x enumeration))
  • Method HAS-MORE-ELEMENTS-P ((x enumeration))
  • Method HAS-MORE-ELEMENTS-P ((x enumeration))
  • Generic-Function HAS-NEXT-P (x)
    The generic function HAS-NEXT-P checks whether the enumeration enumeration has another element that follows the current one in the traversal order. If so it returns a non-NIL result, otherwise, result is NIL. Arguments and Values: X : an ENUMERATION instance result : a T. Examples: cl-prompt> (defvar ve (enumerate (vector 1 2 3))) VE cl-prompt> (has-next-p ve) T cl-prompt> (loop repeat 3 do (print (next ve))) 1 2 3 NIL cl-prompt> (has-next-p ve) NIL Exceptional Situations: HAS-NEXT-P signals an error (i.e., NO-APPLICABLE-METHOD is run) if X is not an ENUMERATION instance.
  • Method HAS-NEXT-P ((e enumeration))
  • Method HAS-NEXT-P ((e enumeration))
  • Method HAS-NEXT-P ((e enumeration))
  • Generic-Function NEXT (e &optional default)
    The generic function NEXT returns the "next" object in the enumeration enumeration if there is one, as determined by calling HAS-NEXT-P. If HAS-NEXT-P returns NIL and DEFAULT is supplied, then DEFAULT is returned. Otherwise the condition NO-SUCH-ELEMENT is signaled. Arguments and Values: E : an ENUMERATION instance DEFAULT : a T result : a T. Exceptional Situations: NEXT signals the NO-SUCH-ELEMENT condition when there are no more elements in the enumeration and no default was supplied.
  • Generic-Function CURRENT (enum &optional errorp default)
    Returns the "current" element in the enumeration ENUM. Each ENUMERATION instance maintains a reference to its "current" element (if within "range"). Given an ENUMERATION instance enumeration, the generic function CURRENT returns the object in such reference. If ERRORP is non-NIL and no "current" element is available, then CURRENT signals an error: either NO-SUCH-ELEMENT or a continuable error. If ERRORP is NIL and no "current" element is available then DEFAULT is returned. Arguments and Values: ENUM : an ENUMERATION instance ERRORP : a generalized BOOLEAN DEFAULT : a T result : a T. Exceptional Situations: CURRENT may signal a continuable error or NO-SUCH-ELEMENT. See above for an explanation.
  • Generic-Function RESET (enum)
    Resets the enumeration ENUM internal state to its "initial" element. The "initial" element of the enumeration ENUM obviously depends on the actual enumerate object. Arguments and Values: ENUM : an ENUMERATION instance result : a T. Examples: cl-prompt> (defvar *se* (enumerate "foobar" :start 2)) *SE* cl-prompt> (loop repeat 3 do (print (next *se*))) #o #b #a NIL cl-prompt> (current *se*) #r cl-prompt> (reset *se*) 2 cl-prompt> (current *se*) #o cl-prompt> (loop repeat 3 do (print (next *se*))) #o #b #a NIL
  • Method NEXT ((x enumeration) &optional default)
  • Method NEXT ((x enumeration) &optional (default nil default-supplied-p))
  • Class BI-DIRECTIONAL-ENUMERATION  (ENUMERATION)
    The Bi-directional Enumeration Class. Enumerations that can be traversed back and forth.
    No slots.
  • Generic-Function BI-DIRECTIONAL-ENUMERATION-P (x)
  • Method BI-DIRECTIONAL-ENUMERATION-P ((e t))
  • Method BI-DIRECTIONAL-ENUMERATION-P ((e t))
  • Method BI-DIRECTIONAL-ENUMERATION-P ((e t))
  • Generic-Function PREVIOUS (x &optional default)
  • Method PREVIOUS ((x enumeration) &optional default)
  • Method PREVIOUS ((x enumeration) &optional default)
  • Method PREVIOUS ((x enumeration) &optional default)
  • Generic-Function HAS-PREVIOUS-P (x)
  • Method HAS-PREVIOUS-P ((x enumeration))
  • Method HAS-PREVIOUS-P ((x enumeration))
  • Method HAS-PREVIOUS-P ((x enumeration))
  • Method PREVIOUS ((x enumeration) &optional (default nil default-supplied-p))
  • Class BOUNDED-ENUMERATION  (ENUMERATION)
    START   Accessor: ENUMERATION-START
    END   Accessor: ENUMERATION-END
  • Generic-Function BOUNDED-ENUMERATION-P (x)
  • Method BOUNDED-ENUMERATION-P ((x bounded-enumeration))
  • Method BOUNDED-ENUMERATION-P ((x bounded-enumeration))
  • Method BOUNDED-ENUMERATION-P ((x bounded-enumeration))
  • Method BOUNDED-ENUMERATION-P ((x t))
  • Method BOUNDED-ENUMERATION-P ((x t))
  • Method BOUNDED-ENUMERATION-P ((x t))
  • Class FUNCTIONAL-ENUMERATION  (ENUMERATION)
    No slots.
  • Generic-Function FUNCTIONAL-ENUMERATION-P (x)
  • Method FUNCTIONAL-ENUMERATION-P ((x t))
  • Method FUNCTIONAL-ENUMERATION-P ((x t))
  • Method FUNCTIONAL-ENUMERATION-P ((x t))
  • Class LIST-ENUMERATION  (SEQUENCE-ENUMERATION)
    The List Enumeration Class.
    END-CONS   Accessor: END-CONS
  • Generic-Function LIST-ENUMERATION-P (x)
  • Method LIST-ENUMERATION-P ((x t))
  • Method LIST-ENUMERATION-P ((x t))
  • Method LIST-ENUMERATION-P ((x t))
  • Method ENUMERATE ((l list) &key (start 0) end &allow-other-keys)
    Calling ENUMERATE on a LIST returns a LIST-ENUMERATION instance. L should be a proper list. The behavior of ENUMERATE when passed a non proper list is undefined. START must be an integer between 0 and (length l). END must be an integer between 0 and (length L) or NIL. The usual CL semantics regarding sequence traversals applies.
  • Method HAS-MORE-ELEMENTS-P ((x list-enumeration))
  • Method HAS-NEXT-P ((x list-enumeration))
  • Method NEXT ((x list-enumeration) &optional default)
  • Method RESET ((x list-enumeration))
  • Method CURRENT ((x list-enumeration) &optional (errorp t) (default nil))
  • Class VECTOR-ENUMERATION  (SEQUENCE-ENUMERATION, BI-DIRECTIONAL-ENUMERATION)
    CURSOR
  • Generic-Function VECTOR-ENUMERATION-P (x)
  • Method VECTOR-ENUMERATION-P ((x t))
  • Method VECTOR-ENUMERATION-P ((x t))
  • Method VECTOR-ENUMERATION-P ((x t))
  • Method ENUMERATE ((v vector) &key (start 0) end &allow-other-keys)
    Calling ENUMERATE on a VECTOR returns a VECTOR-ENUMERATION instance. START must be an integer between 0 and (length V). end must be an integer between 0 and (length V) or NIL. The usual CL semantics regarding sequence traversals applies.
  • Method HAS-MORE-ELEMENTS-P ((x vector-enumeration))
  • Method HAS-NEXT-P ((x vector-enumeration))
  • Method NEXT ((x vector-enumeration) &optional default)
  • Method HAS-PREVIOUS-P ((x vector-enumeration))
  • Method PREVIOUS ((x vector-enumeration) &optional default)
  • Method CURRENT ((x vector-enumeration) &optional (errorp t) (default nil))
  • Method RESET ((x vector-enumeration))
  • Class STRING-ENUMERATION  (VECTOR-ENUMERATION)
    The String Enumeration Class.
    No slots.
  • Generic-Function STRING-ENUMERATION-P (x)
  • Method STRING-ENUMERATION-P ((x t))
  • Method STRING-ENUMERATION-P ((x t))
  • Method STRING-ENUMERATION-P ((x t))
  • Method ENUMERATE ((s string) &key (start 0) end &allow-other-keys)
    Calling ENUMERATE on a STRING returns a STRING-ENUMERATION instance. A STRING-ENUMERATION traverses the STRING s using the accessor CHAR. START must be an integer between 0 and (length S). end must be an integer between 0 and (length S) or NIL. The usual CL semantics regarding sequence traversals applies.
  • Method NEXT ((x string-enumeration) &optional default)
  • Method PREVIOUS ((x string-enumeration) &optional default)
  • Class SIMPLE-STRING-ENUMERATION  (STRING-ENUMERATION)
    The Simple String Enumeration Class.
    No slots.
  • Generic-Function SIMPLE-STRING-ENUMERATION-P (x)
  • Method SIMPLE-STRING-ENUMERATION-P ((x t))
  • Method SIMPLE-STRING-ENUMERATION-P ((x t))
  • Method SIMPLE-STRING-ENUMERATION-P ((x t))
  • Class HASH-TABLE-ENUMERATION  (ENUMERATION)
    The Hash Table Enumeration Class.
    KEYSP   Reader: KEYSP
    VALUESP   Reader: VALUESP
    KV-PAIRS-P   Reader: KEY-VALUE-PAIRS-P
    UNDERLYING-ENUMERATION   Accessor: UNDERLYING-ENUMERATION
  • Generic-Function HASH-TABLE-ENUMERATION-P (x)
  • Method HASH-TABLE-ENUMERATION-P ((x t))
  • Method HASH-TABLE-ENUMERATION-P ((x t))
  • Method HASH-TABLE-ENUMERATION-P ((x t))
  • Method ENUMERATE ((x hash-table) &key start end keys (values t) key-value-pairs &allow-other-keys)
    Calling ENUMERATE on a HASH-TABLE returns a HASH-TABLE-ENUMERATION instance. If KEYS is true, the HASH-TABLE-ENUMERATION scans the keys of the underlying HASH-TABLE. If VALUES is true (the default), the HASH-TABLE-ENUMERATION scans the values of the underlying HASH-TABLE. If KEY-VALUE-PAIRS is true, then the HASH-TABLE-ENUMERATION yields key-values dotted pairs. Note that it makes no sense to set "bounds" on a HASH-TABLE-ENUMERATION, as an HASH-TABLE is an unordered data structure. START and END are ignored.
  • Method HAS-MORE-ELEMENTS-P ((x hash-table-enumeration))
  • Method HAS-NEXT-P ((x hash-table-enumeration))
  • Method NEXT ((x hash-table-enumeration) &optional default)
  • Method CURRENT ((x hash-table-enumeration) &optional (errorp t) (default nil))
  • Method RESET ((x hash-table-enumeration))
  • Class ARRAY-TABLE-ENUMERATION  (BOUNDED-ENUMERATION, BI-DIRECTIONAL-ENUMERATION)
    The Array Table Enumeration Class.
    No slots.
  • Generic-Function ARRAY-TABLE-ENUMERATION-P (x)
  • Method ARRAY-TABLE-ENUMERATION-P ((x t))
  • Method ARRAY-TABLE-ENUMERATION-P ((x t))
  • Method ARRAY-TABLE-ENUMERATION-P ((x t))
  • Method ENUMERATE ((a array) &key (start 0) end &allow-other-keys)
    Calling ENUMERATE on an ARRAY returns an ARRAY-ENUMERATION instance. START must be either an integer between 0 and (array-total-size a), or a LIST of indices between 0 and the appropriate limit on the array-dimension. end must be an integer between 0 and (array-total-size A), or a LIST of indices between 0 and the appropriate limit on the array-dimension, or NIL. If END is NIL then it is set to (array-total-size A). The enumeration of a multidimensional array follows the row-major order of Common Lisp Arrays. Examples: ;;; The following example uses ENUM:FOREACH. cl-prompt> (foreach (e #3A(((1 2 3) (4 5 6)) ((7 8 9) (10 11 12))) :start (list 1 0 1)) (print e)) 8 9 10 11 12 NIL
  • Method HAS-MORE-ELEMENTS-P ((x array-table-enumeration))
  • Method HAS-NEXT-P ((x array-table-enumeration))
  • Method NEXT ((x array-table-enumeration) &optional default)
  • Method HAS-PREVIOUS-P ((x array-table-enumeration))
  • Method PREVIOUS ((x array-table-enumeration) &optional default)
  • Method CURRENT ((x array-table-enumeration) &optional (errorp t) (default nil))
  • Method RESET ((x array-table-enumeration))
  • Class NUMBER-ENUMERATION  (BOUNDED-ENUMERATION, BI-DIRECTIONAL-ENUMERATION, FUNCTIONAL-ENUMERATION)
    CURSOR
    BY   Accessor: NUMBER-ENUMERATION-INCREMENT
    REV-BY   Accessor: NUMBER-ENUMERATION-REVERSE-INCREMENT
  • Generic-Function NUMBER-ENUMERATION-P (x)
  • Method NUMBER-ENUMERATION-P ((x t))
  • Method NUMBER-ENUMERATION-P ((x t))
  • Method NUMBER-ENUMERATION-P ((x t))
  • Method ENUMERATE ((x (eql 'number)) &key (start 0) end (by #'1+) &allow-other-keys)
    Calling ENUMERATE on a the symbol NUMBER returns a NUMBER-ENUMERATION instance. NUMBER-ENUMERATIONs are not real enumerations per se, but they have a nice interface and serve to render things like Python xrange type. START must be a number, while END can be a number or NIL. The next (or previous) element is obtained by changing the current element by BY. BY can be a function (#'1+ is the default) or a number, in which case it is always summed to the current element. A NUMBER-ENUMERATION can also enumerate COMPLEX numbers, but in this case the actual enumeration properties are completely determined by the value of BY.
  • Method HAS-MORE-ELEMENTS-P ((x number-enumeration))
  • Method HAS-NEXT-P ((x number-enumeration))
  • Method NEXT ((x number-enumeration) &optional default)
  • Method HAS-PREVIOUS-P ((x number-enumeration))
  • Method PREVIOUS ((x number-enumeration) &optional default)
  • Method CURRENT ((x number-enumeration) &optional (errorp t) (default nil))
  • Method RESET ((x number-enumeration))
  • Function RANGE (start end &optional (incr #'1+))
    The function RANGE is a utility function the produce a "stream" (quote mandatory) of numbers. It is almost equivalent to the APL/J iota operator and to Python xrange type. The main use of RANGE is in conjunction with FOREACH and other iteration constructs. Arguments and Values: START : a NUMBER END : a NUMBER or NIL INCR : a NUMBER or a function of one argument (default is #'1+) result : a NUMBER-ENUMERATION Examples: ;;;; The two calls below are equivalent: cl-prompt> (range 2 10 3) #<Number enumeration [2 10) at 2 by #<FUNCTION> XXXXXX> cl-prompt> (enumerate 'number :start 2 :end 10 :by 3) #<Number enumeration [2 10) at 2 by #<FUNCTION> XXXXXX>
  • Macro FOREACH ((var object &rest keys) &body forms-and-clauses)
    Simplified iteration construct over an `enumerable' object. FOREACH is a thin macro over LOOP and it mixes, in a hybrid, and maybe not so beautiful, style the DOTIMES/DOLIST shape with LOOP clauses. FORMS-AND-CLAUSES are executed in an environment where VAR is bound to the elements of the result of (APPLY #'ENUM:ENUMERATE OBJECT KEYS). If KEYS contains a non-NIL :REVERSE keyword, then the enumeration must be bi-directional and PREVIOUS and HAS-PREVIOUS-P will be used to traverse it. :REVERSE and its value will be still passed to the embedded call to ENUMERATE. This is obviously only useful only for enumerations that can start "in the middle". FORMS-AND-CLAUSES can start with some declarations and then continue with either regular forms or LOOP clauses. After the first LOOP clause appears in FORMS-AND-CLAUSES, standard LOOP rules should be followed. FOREACH returns whatever is returned by FORMS-AND-CLAUSES according to standard LOOP semantics. Examples: ;;; Here are some examples of FOREACH. cl-prompt> (setf le (enumerate '(1 2 3))) #<CONS enumeration ...> cl-prompt> (foreach (i le) (print i)) 1 2 3 NIL ;;; Of course, FOREACH is smarter than that: cl-prompt> (foreach (i (vector 'a 's 'd)) (declare (type symbol i)) (print i)) A S D NIL ;;; Apart from declarations, FOREACH is just a macro built on top of ;;; LOOP, therefore you can leverage all the LOOP functionality. cl-prompt> (foreach (i '(1 2 3 4)) (declare (type fixnum i)) when (evenp i) collect i) (2 4) ;;; While this creates an admittedly strange hybrid between the ;;; standard DO... operators and LOOP, it does serve the purpose. The ;;; right thing would be to have a standardized way of extending LOOP. ;;; Alas, there is no such luxury. ;;; Finally an example of a reverse enumeration: cl-prompt> (foreach (i (vector 1 2 3 4 5 6 7 8) :reverse t :start 4) when (evenp i) collect i) (4 2)