TCR.SEQUENCE-ITERATORS - (unpublished)

     by Tobias C Rittweiler, Adlai Chandrasekhar
Repository:
 
     darcs get http://common-lisp.net/project/sequence-iterators/darcs/sequence-iterators/
 
Download:
 
     tcr.sequence-iterators-(unpublished).tar.gz
 

Contents

  1. Required Libraries
  2. Notes on the API
  3. Examples
  4. Acknowledgements
  5. Dictionary
    1. CANONICALIZE-KEY
    2. CANONICALIZE-TEST
    3. CHECK-SEQUENCE-BOUNDS
    4. DO-SEQUENCE-ITERATOR
    5. DO-SEQUENCE-ITERATORS
    6. DO-SEQUENCE-ITERATORS*
    7. DOSEQUENCE
    8. DOSEQUENCES*
    9. MAKE-SEQUENCE-LIKE
    10. SEQUENCE-INDEX
    11. SEQUENCE-LENGTH
    12. SEQUENCE-OUT-OF-BOUNDS-ERROR
    13. VALIDATE-SEQUENCE-BOUNDS
    14. WITH-SEQUENCE-ITERATOR

 

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.
 

 

Dictionary


[Function]
canonicalize-key key-designator => result

  Argument and Values:

key-designator: (OR SYMBOL FUNCTION)
result: FUNCTION
  Description:
Canonicalizes key-designator to a function object. If key-designator is NIL, the
IDENTITY function is returned.


[Function]
canonicalize-test test &optional test-not => result

  Argument and Values:

test: (OR SYMBOL FUNCTION)
test-not: (OR SYMBOL FUNCTION)
result: FUNCTION
  Description:
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.


[Macro]
check-sequence-bounds seq-place start-place end-place &optional length-place &environment env => result

  Description:

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


[Macro]
do-sequence-iterator (var iterator &optional result) &body body => result

  Description:

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


[Macro]
do-sequence-iterators ((var iterator &optional result) &rest more-clauses) &body body => result

  Description:

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

In each iteration, all iterators are run in parallel.

If no iterator exhausts, the vars, 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.


[Macro]
do-sequence-iterators* ((var iterator &optional result) &rest more-clauses) &body body => result

  Description:

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 vars 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.


[Macro]
dosequence (var sequence &optional result &key start end from-end place) &body body &environment macro-env => result

  Description:

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.


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

  Description:

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.


[Function]
make-sequence-like sequence length &rest keys &key initial-element initial-contents => result

  Argument and Values:

sequence: SEQUENCE
length: SEQUENCE-LENGTH
initial-element: T
initial-contents: SEQUENCE
result: SEQUENCE
  Description:
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.


[Condition type]
sequence-bounding-indices-error

  Readers:

SEQUENCE-OUT-OF-BOUNDS-ERROR--SEQUENCE
SEQUENCE-OUT-OF-BOUNDS-ERROR--START
SEQUENCE-OUT-OF-BOUNDS-ERROR--END


[Type]
sequence-index

  Description:

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.


[Condition type]
sequence-index-error

  Readers:

SEQUENCE-OUT-OF-BOUNDS-ERROR--SEQUENCE
SEQUENCE-OUT-OF-BOUNDS-ERROR--INDEX


[Type]
sequence-length

  Description:

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.


[Condition type]
sequence-out-of-bounds-error


[Function]
validate-sequence-bounds sequence start end &optional length => result

  Argument and Values:

sequence: SEQUENCE
start: SEQUENCE-INDEX
end: (OR NULL SEQUENCE-LENGTH)
length: (OR NULL SEQUENCE-LENGTH)
result: SEQUENCE, SEQUENCE-INDEX, SEQUENCE-LENGTH, SEQUENCE-LENGTH
  Description:
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.


[Macro]
with-sequence-iterator (iterator-name sequence &key start end from-end place) &body body => result

  Description:

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.

This documentation was generated on 2009-11-15 from a Lisp image using some home-brewn, duct-taped,
evolutionary hacked extension of Edi Weitz' DOCUMENTATION-TEMPLATE.