The sequence-iterators Reference Manual

This is the sequence-iterators Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:51:44 2024 GMT+0.

Table of Contents


1 Systems

The main system appears first, followed by any subsystem dependency.


1.1 sequence-iterators

DOSEQUENCE & Co.

Author

Tobias C. Rittweiler <>

License

BSD

Dependency

parse-declarations-1.0 (system).

Source

sequence-iterators.asd.

Child Components

2 Files

Files are sorted by type and then listed depth-first from the systems components trees.


2.1 Lisp


2.1.1 sequence-iterators/sequence-iterators.asd

Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

ASDF Systems

sequence-iterators.


2.1.2 sequence-iterators/package.lisp

Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

Packages

tcr.sequence-iterators.


2.1.3 sequence-iterators/utils.lisp

Dependency

package.lisp (file).

Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

Internals

2.1.4 sequence-iterators/with-sexp-builder.lisp

Dependency

package.lisp (file).

Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

Internals

with-sexp-builder (macro).


2.1.5 sequence-iterators/define-api.lisp

Dependency

package.lisp (file).

Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

Internals

2.1.6 sequence-iterators/sequence-iterators.lisp

Dependencies
Source

sequence-iterators.asd.

Parent Component

sequence-iterators (system).

Public Interface
Internals

3 Packages

Packages are listed by definition order.


3.1 tcr.sequence-iterators

* Required Libraries

This library depends on parse-declarations, available at

http://common-lisp.net/project/parse-declarations/

* Notes on the API

This library has not been publically released yet. The API as described here should be pretty stable, and changes should hopefully only happen as additions. (No guarantee on that, of course.)

If you find use of this library, I’m eager to receive feedback about inconveniences or improvements to the API.

* Examples

There’s a presentation available at

http://common-lisp.net/~trittweiler/talks/sequence-iterators-2009.pdf

which is an introduction to the library, including examples.

* Acknowledgements

I’d like to thank Paul Khuong and Christophe Rhodes for valuable comments regarding details of the API.

Source

package.lisp.

Nickname

sequence-iterators

Use List
  • common-lisp.
  • tcr.parse-declarations-1.0.
Public Interface
Internals

4 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


4.1 Public Interface


4.1.1 Macros

Macro: check-sequence-bounds (seq-place start-place end-place &optional length-place)

This is a convenience wrapper around VALIDATE-SEQUENCE-BOUNDS to automatically assign its return values to the specified places.

As the return type of VALIDATE-SEQUENCE-BOUND is known, your Common Lisp implementation may henceforth be able to derive the types of the places.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: do-sequence-iterator ((var iterator &optional result) &body body)

This is a convenience wrapper around DO-SEQUENCE-ITERATORS*.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: do-sequence-iterators (((var iterator &optional result) &rest more-clauses) &body body)

DO-SEQUENCE-ITERATORS advances multiple sequence iterators at
once.

In each iteration, all iterators are run in _parallel_.

If no iterator exhausts, the ‘var’s, which may be of the form (‘elt’ ‘idx’), will be bound to the elements produced, and ‘body’ is executed.

If, however, an iterator exhausts, the ‘result’ form of the clause denoting the exhausted iterator will be evaluated (in an environment where all the variables are still bound to the elements as produced in the previous iteration), and returned. If several iterators exhaust, each respective ‘result’ form will be returned as multiple values (in the order the respective clauses appeared.)

‘body’ is executed in an implicit TAGBODY, and the iteration is performed in an implicit BLOCK named NIL.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: do-sequence-iterators* (((var iterator &optional result) &rest more-clauses) &body body)

DO-SEQUENCE-ITERATORS* advances multiple sequence iterators at once. It relates to DO-SEQUENCE-ITERATORS as DO* relates to DO.

In each iteration, the iterators are run and checked for exhaustion _sequentially_.

For each element produced by the currently executed iterator, the respective ‘var’ is bound to this element.

If no iterator exhausts, ‘body’ will be executed.

If, however, an iterator exhausts, the iteration will terminate at that point, and the ‘result’ form of the clause denoting the currently executed iterator is evaluated and returned. The form is evaluated in an environment where all the ‘var’s belonging to iterators already executed are bound to the elements produced in the current iteration, and the other variables are bound to the elements produced during the previous iteration.

‘body’ is executed in an implicit TAGBODY, and the iteration is performed in an implicit BLOCK named NIL.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: dosequence ((var sequence &optional result &key start end from-end place) &body body)

DOSEQUENCE iterates over the elements of ‘sequence’ with ‘var’
bound to each element in turn, starting from ‘start’ until ‘end’; if ‘from-end’ is T, the iteration is performed in reverse order.

Instead of a symbol, ‘var’ can be a list of two elements (‘elt’ ‘index’) where ‘elt’ is bound to the current element, and ‘index’ to its index into the sequence.

An implicit block named NIL surrounds DOSEQUENCE, hence RETURN may be used to terminate the loop immediately. Otherwise ‘result’ is returned at the end of the loop.

‘body’ is executed in an implicit TAGBODY.

‘result’ is processed at a time where ‘var’ (or ‘elt’) is bound to
the last element, and ‘index’ (if given) to the index of the last element.

If ‘place’ is given, a /generalized reference/ for ‘place’ is defined within the lexical scope of ‘body’ such that a) an invocation of (‘place’) will (re)access the current element in the sequence, and such that b) an invocation of (SETF (‘place’) ‘new-value’) will destructively set the current element in ‘sequence’ to ‘new-value’. It is unspecified whether the SETF function updates ‘var’ (or ‘elt’, respectively.) Beyond that, CLHS 3.6 applies.

The bounding indices ‘start’ and ‘end’ are _not_ checked for validity.

It is unspecified whether DOSEQUENCE establishes a new binding for ‘var’ on each iteration, or only establishes one initial binding and assigns to it on subsequent iterations.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: dosequences* (((var sequence &optional result &key start end from-end place) &rest more-clauses) &body body)

DOSEQUENCES* iterates through multiple sequences at once.

Each iterator is run sequentially until one exhausts; the ‘result’ form belonging to the clause of the iterator that exhausts first, is returned.

For detailed information on the way the iterators are run, see DO-SEQUENCE-ITERATORS*. For a description of the format of each clause, see DOSEQUENCE.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Macro: with-sequence-iterator ((iterator-name sequence &key start end from-end place) &body body)

Within the lexical scope of ‘body’, ‘iterator-name’ is defined via FLET such that each successive invocation of (‘iterator-name’) will yield all the elements of ‘sequence’, one by one, starting from ‘start’ until ‘end’; if ‘from-end’ is T, in reverse order.

The /bounding indices/ ‘start’, and ‘end’ are _not_ checked for
validity upfront; to achieve that, use CHECK-SEQUENCE-BOUNDS.

Each invocation of the iterator form returns the following three values:

1. A generalized boolean that is true if an element is returned.

2. The element itself.

3. The index of the element in the sequence.

If ‘place’ is given, a /generalized reference/ for ‘place’ is defined within the lexical scope of ‘body’ such that a) an invocation of (‘place’) will (re)access the current element in the sequence, and such that b) an invocation of (SETF (‘place’) ‘new-value’) will destructively set the current element in ‘sequence’ to ‘new-value’. Beyond that, CLHS 3.6 applies.

Consequences are undefined if ‘place’ is referenced or assigned to before ‘iterator’ has run, or after ‘iterator’ has exhausted.

Consequences are undefined if a closure that closes over the iterator form (or ‘place’) is executed outside the dynamic extent of WITH-SEQUENCE-ITERATOR.

Consequences are undefined if multiple threads invoke the iterator concurrently.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.


4.1.2 Ordinary functions

Function: canonicalize-key (key-designator)

Canonicalizes ‘key-designator’ to a function object.
If ‘key-designator’ is NIL, the IDENTITY function is returned.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: canonicalize-test (test &optional test-not)

Canonicalizes ‘test’ and ‘test-not’ to a function object. If both are given, an error is signaled.
If both are NIL, the EQL function is returned.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: make-sequence-like (sequence length &rest keys &key initial-element initial-contents)

Returns a new sequence of length ‘length’ and of the same type as ‘sequence’.

The parameters ‘initial-element’ and ‘initial-contents’ specify how the new sequence is supposed to be initialized. Only one of them can be passed at a time.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: validate-sequence-bounds (sequence start end &optional length)

Signals an error of type SEQUENCE-BOUNDING-INDICES-ERROR if ‘start’, and ‘end’ are not valid /bounding indices/ for sequence ‘sequence’.

If ‘start’ is NIL, the bounds are assumed to start at the first element of ‘sequence’.

If ‘end’ is NIL, the bounds are assumed to end at the length of ‘sequence’.

If ‘length’ is NIL, the length of the sequence is computed as by LENGTH. (The purpose of this parameter is to avoid having to compute the length twice if you already had to do so.)

This function returns ‘sequence’, and the possibly updated values of ‘start’, ‘end’, and ‘length’.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.


4.1.3 Generic functions

Generic Reader: sequence-out-of-bounds-error--end (condition)
Package

tcr.sequence-iterators.

Methods
Reader Method: sequence-out-of-bounds-error--end ((condition sequence-bounding-indices-error))
Source

sequence-iterators.lisp.

Target Slot

end.

Generic Reader: sequence-out-of-bounds-error--index (condition)
Package

tcr.sequence-iterators.

Methods
Reader Method: sequence-out-of-bounds-error--index ((condition sequence-index-error))
Source

sequence-iterators.lisp.

Target Slot

index.

Generic Reader: sequence-out-of-bounds-error--sequence (condition)
Package

tcr.sequence-iterators.

Methods
Reader Method: sequence-out-of-bounds-error--sequence ((condition sequence-index-error))
Source

sequence-iterators.lisp.

Target Slot

sequence.

Reader Method: sequence-out-of-bounds-error--sequence ((condition sequence-bounding-indices-error))
Source

sequence-iterators.lisp.

Target Slot

sequence.

Generic Reader: sequence-out-of-bounds-error--start (condition)
Package

tcr.sequence-iterators.

Methods
Reader Method: sequence-out-of-bounds-error--start ((condition sequence-bounding-indices-error))
Source

sequence-iterators.lisp.

Target Slot

start.


4.1.4 Conditions

Condition: sequence-bounding-indices-error
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Direct superclasses

sequence-out-of-bounds-error.

Direct methods
Direct slots
Slot: sequence
Package

common-lisp.

Initform

(quote (tcr.sequence-iterators::required-argument))

Initargs

:sequence

Readers

sequence-out-of-bounds-error--sequence.

Writers

This slot is read-only.

Slot: start
Initform

(quote (tcr.sequence-iterators::required-argument))

Initargs

:start

Readers

sequence-out-of-bounds-error--start.

Writers

This slot is read-only.

Slot: end
Initform

(quote (tcr.sequence-iterators::required-argument))

Initargs

:end

Readers

sequence-out-of-bounds-error--end.

Writers

This slot is read-only.

Condition: sequence-index-error
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Direct superclasses

sequence-out-of-bounds-error.

Direct methods
Direct slots
Slot: sequence
Package

common-lisp.

Initform

(quote (tcr.sequence-iterators::required-argument))

Initargs

:sequence

Readers

sequence-out-of-bounds-error--sequence.

Writers

This slot is read-only.

Slot: index
Initform

(quote (tcr.sequence-iterators::required-argument))

Initargs

:index

Readers

sequence-out-of-bounds-error--index.

Writers

This slot is read-only.

Condition: sequence-out-of-bounds-error
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Direct superclasses

type-error.

Direct subclasses

4.1.5 Types

Type: sequence-index (&optional length)

Represents an index into a sequence.

If ‘length’ is explicitly given, it’s taken to mean the (exclusive) upper bound of the sequence.

Otherwise, it’s either a non-negative integer in the general case, or a non-negative fixnum on implementations where such an assumption is reasonable.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Type: sequence-length ()

Represents the length of a sequence.

As this type is equivalent to SEQUENCE-INDEX + 1, you have to carefully consider whether something represents an index or the length of a sequence (lest you’re bitten by an off-by-one bug.) For example, the :START parameter is of type SEQUENCE-INDEX, but the :END parameter is of type SEQUENCE-LENGTH.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.


4.2 Internals


4.2.1 Macros

Macro: define-api (name lambda-list type-list &body body)
Package

tcr.sequence-iterators.

Source

define-api.lisp.

Macro: dolists (clauses &body body)
Package

tcr.sequence-iterators.

Source

utils.lisp.

Macro: with-sexp-builder ((start-symbol &rest stuff) &body body)
Package

tcr.sequence-iterators.

Source

with-sexp-builder.lisp.


4.2.2 Ordinary functions

Function: %make-sequence-iterator (sequence &key start end from-end)

Returns an iterator thunk that returns three values: a boolean flag that is true, if an element is returned, the current sequence index, and the current sequence element.

Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: %normalize-dosequence-binding-arg (arg)
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: %parse-do-sequence-iterators-clauses (clauses)
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: %parse-dosequences-clauses (clauses)
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.

Function: ensure-function (function-designator)

Returns the function designated by FUNCTION-DESIGNATOR:
if FUNCTION-DESIGNATOR is a function, it is returned, otherwise it must be a function name and its FDEFINITION is returned.

Package

tcr.sequence-iterators.

Source

utils.lisp.

Function: make-gensym-list (length &optional x)

Returns a list of LENGTH gensyms, each generated as if with a call to MAKE-GENSYM, using the second (optional, defaulting to "G") argument.

Package

tcr.sequence-iterators.

Source

utils.lisp.

Function: parse-body (body &key documentation whole)

Parses BODY into (values remaining-forms declarations doc-string). Documentation strings are recognized only if DOCUMENTATION is true. Syntax errors in body are signalled and WHOLE is used in the signal arguments when given.

Package

tcr.sequence-iterators.

Source

define-api.lisp.

Function: parse-ordinary-lambda-list (lambda-list)

Parses an ordinary lambda-list, returning as multiple values:

1. Required parameters.
2. Optional parameter specifications, normalized into form (NAME INIT SUPPLIEDP)
where SUPPLIEDP is NIL if not present.
3. Name of the rest parameter, or NIL.
4. Keyword parameter specifications, normalized into form ((KEYWORD-NAME NAME) INIT SUPPLIEDP) where SUPPLIEDP is NIL if not present.
5. Boolean indicating &ALLOW-OTHER-KEYS presence.
6. &AUX parameter specifications, normalized into form (NAME INIT).

Signals a PROGRAM-ERROR is the lambda-list is malformed.

Package

tcr.sequence-iterators.

Source

define-api.lisp.

Function: required-argument (&optional name)

Signals an error for a missing argument of NAME. Intended for use as an initialization form for structure and class-slots, and a default value for required keyword arguments.

Package

tcr.sequence-iterators.

Source

utils.lisp.

Function: reversed-list-of-ptrs (list start end)
Package

tcr.sequence-iterators.

Source

sequence-iterators.lisp.


4.2.3 Types

Type: array-index (&optional length)

Type designator for an index into array of LENGTH: an integer between 0 (inclusive) and LENGTH (exclusive). LENGTH defaults to ARRAY-DIMENSION-LIMIT.

Package

tcr.sequence-iterators.

Source

utils.lisp.

Type: array-length (&optional length)

Type designator for a dimension of an array of LENGTH: an integer between 0 (inclusive) and LENGTH (inclusive). LENGTH defaults to ARRAY-DIMENSION-LIMIT.

Package

tcr.sequence-iterators.

Source

utils.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %  
C   D   E   F   G   M   P   R   S   V   W  
Index Entry  Section

%
%make-sequence-iterator: Private ordinary functions
%normalize-dosequence-binding-arg: Private ordinary functions
%parse-do-sequence-iterators-clauses: Private ordinary functions
%parse-dosequences-clauses: Private ordinary functions

C
canonicalize-key: Public ordinary functions
canonicalize-test: Public ordinary functions
check-sequence-bounds: Public macros

D
define-api: Private macros
do-sequence-iterator: Public macros
do-sequence-iterators: Public macros
do-sequence-iterators*: Public macros
dolists: Private macros
dosequence: Public macros
dosequences*: Public macros

E
ensure-function: Private ordinary functions

F
Function, %make-sequence-iterator: Private ordinary functions
Function, %normalize-dosequence-binding-arg: Private ordinary functions
Function, %parse-do-sequence-iterators-clauses: Private ordinary functions
Function, %parse-dosequences-clauses: Private ordinary functions
Function, canonicalize-key: Public ordinary functions
Function, canonicalize-test: Public ordinary functions
Function, ensure-function: Private ordinary functions
Function, make-gensym-list: Private ordinary functions
Function, make-sequence-like: Public ordinary functions
Function, parse-body: Private ordinary functions
Function, parse-ordinary-lambda-list: Private ordinary functions
Function, required-argument: Private ordinary functions
Function, reversed-list-of-ptrs: Private ordinary functions
Function, validate-sequence-bounds: Public ordinary functions

G
Generic Function, sequence-out-of-bounds-error--end: Public generic functions
Generic Function, sequence-out-of-bounds-error--index: Public generic functions
Generic Function, sequence-out-of-bounds-error--sequence: Public generic functions
Generic Function, sequence-out-of-bounds-error--start: Public generic functions

M
Macro, check-sequence-bounds: Public macros
Macro, define-api: Private macros
Macro, do-sequence-iterator: Public macros
Macro, do-sequence-iterators: Public macros
Macro, do-sequence-iterators*: Public macros
Macro, dolists: Private macros
Macro, dosequence: Public macros
Macro, dosequences*: Public macros
Macro, with-sequence-iterator: Public macros
Macro, with-sexp-builder: Private macros
make-gensym-list: Private ordinary functions
make-sequence-like: Public ordinary functions
Method, sequence-out-of-bounds-error--end: Public generic functions
Method, sequence-out-of-bounds-error--index: Public generic functions
Method, sequence-out-of-bounds-error--sequence: Public generic functions
Method, sequence-out-of-bounds-error--sequence: Public generic functions
Method, sequence-out-of-bounds-error--start: Public generic functions

P
parse-body: Private ordinary functions
parse-ordinary-lambda-list: Private ordinary functions

R
required-argument: Private ordinary functions
reversed-list-of-ptrs: Private ordinary functions

S
sequence-out-of-bounds-error--end: Public generic functions
sequence-out-of-bounds-error--end: Public generic functions
sequence-out-of-bounds-error--index: Public generic functions
sequence-out-of-bounds-error--index: Public generic functions
sequence-out-of-bounds-error--sequence: Public generic functions
sequence-out-of-bounds-error--sequence: Public generic functions
sequence-out-of-bounds-error--sequence: Public generic functions
sequence-out-of-bounds-error--start: Public generic functions
sequence-out-of-bounds-error--start: Public generic functions

V
validate-sequence-bounds: Public ordinary functions

W
with-sequence-iterator: Public macros
with-sexp-builder: Private macros


A.4 Data types

Jump to:   A   C   D   F   P   S   T   U   W  
Index Entry  Section

A
array-index: Private types
array-length: Private types

C
Condition, sequence-bounding-indices-error: Public conditions
Condition, sequence-index-error: Public conditions
Condition, sequence-out-of-bounds-error: Public conditions

D
define-api.lisp: The sequence-iterators/define-api․lisp file

F
File, define-api.lisp: The sequence-iterators/define-api․lisp file
File, package.lisp: The sequence-iterators/package․lisp file
File, sequence-iterators.asd: The sequence-iterators/sequence-iterators․asd file
File, sequence-iterators.lisp: The sequence-iterators/sequence-iterators․lisp file
File, utils.lisp: The sequence-iterators/utils․lisp file
File, with-sexp-builder.lisp: The sequence-iterators/with-sexp-builder․lisp file

P
Package, tcr.sequence-iterators: The tcr․sequence-iterators package
package.lisp: The sequence-iterators/package․lisp file

S
sequence-bounding-indices-error: Public conditions
sequence-index: Public types
sequence-index-error: Public conditions
sequence-iterators: The sequence-iterators system
sequence-iterators.asd: The sequence-iterators/sequence-iterators․asd file
sequence-iterators.lisp: The sequence-iterators/sequence-iterators․lisp file
sequence-length: Public types
sequence-out-of-bounds-error: Public conditions
System, sequence-iterators: The sequence-iterators system

T
tcr.sequence-iterators: The tcr․sequence-iterators package
Type, array-index: Private types
Type, array-length: Private types
Type, sequence-index: Public types
Type, sequence-length: Public types

U
utils.lisp: The sequence-iterators/utils․lisp file

W
with-sexp-builder.lisp: The sequence-iterators/with-sexp-builder․lisp file