The generic-sequences Reference Manual

Table of Contents

The generic-sequences Reference Manual

This is the generic-sequences Reference Manual, version 0.1.1, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:52:17 2018 GMT+0.

1 Introduction

GENERIC-SEQUENCES -- Generic sequences for Common Lisp

GENERIC-SEQUENCES-CONT -- Generic sequence comprehension for Common Lisp

GENERIC-SEQUENCES-ITERATE -- Generic sequence iteration for Common Lisp

GENERIC-SEQUENCES-STREAM -- Lazy streams for Common Lisp

GENERIC-SEQUENCES-TEST -- Unit tests for the generic sequences 

Generic Sequences is a library for Common Lisp. It introduces the generic sequences, which are a hybrid between the ordinary lists, lazy streams and iterable sequences that can be found in other programming languages such as C#, F#, Java and Scala. 

Each sequence returns an enumerator or NIL. The NIL value means that the sequence is empty. The enumerator is a cons cell, which CAR part has the ordinary meaning for Common Lisp, i.e. it returns the current element, while the CDR-part is different. That part is already a function that returns either the next enumerator or NIL in case of reaching the end of the sequence. In other words, there is a delay before receiving the next element of the sequence, which actually makes many sequences lazy.

Unlike the lazy streams, the enumerator always returns a new continuation of the sequence through the CDR part. It recalculates the next element anew, while the stream would memoize it. When iterating, this makes the enumerator more efficient computationally as the memoization would require some kind of locking in the multi-threaded environment.

At the same time, unlike the C# enumerators, our enumerator is like a list cell, which allows defining the sequence in a more easy and declarative way as if we defined an ordinary list. Macros introduced below simplify this process. There exists even the sequence comprehension similar to the F# sequence expression syntax and the yield construction from C#.

Unfortunately, the approach has a drawback. When iterating the sequence, it allocates a lot of small short-term objects on the heap. But the tests show that the modern List-machines have efficient garbage collectors and sometimes the consing is relatively fast, at least in comparison with calling the generic functions. Along with simplicity of defining the sequences, it was the second reason why I decided to apply the described representation to the enumerators. They are not just as slow as they might seem!

Please read the Generic Sequences Manual in the doc directory for more information.

2 Systems

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

2.1 generic-sequences

Author

David Sorokin

License

MIT

Description

Generic sequences for Common Lisp.

Version

0.1.1

Source

generic-sequences.asd (file)

Component

src (module)

3 Modules

Modules are listed depth-first from the system components tree.

3.1 generic-sequences/src

Parent

generic-sequences (system)

Location

src/

Components

• generic-seq-pkg.lisp (file)
• generic-seq.lisp (file)
• readme (file)
• license (file)

4 Files

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

4.1 Lisp

4.1.1 generic-sequences.asd

Location

generic-sequences.asd

Systems

generic-sequences (system)

4.1.2 generic-sequences/src/generic-seq-pkg.lisp

Parent

src (module)

Location

src/generic-seq-pkg.lisp

Packages

generic-seq

4.1.3 generic-sequences/src/generic-seq.lisp

Dependency

generic-seq-pkg.lisp (file)

Parent

src (module)

Location

src/generic-seq.lisp

Exported Definitions

• delay-seq (macro)
• enum-append (macro)
• enum-car (macro)
• enum-cdr (macro)
• enum-cons (macro)
• make-seq (macro)
• seq (type)
• seq->list (function)
• seq->vector (function)
• seq-append (function)
• seq-car (function)
• seq-cdr (function)
• seq-compare (function)
• seq-cons (function)
• seq-count (function)
• seq-count-if (function)
• seq-count-if-not (function)
• seq-cycle (function)
• seq-drop (function)
• seq-drop-while (function)
• seq-drop-while-not (function)
• seq-elt (function)
• seq-enum (generic function)
• seq-enum (method)
• seq-enum (method)
• seq-enum (method)
• seq-enum (method)
• seq-equal (function)
• seq-every (function)
• seq-find (function)
• seq-find-if (function)
• seq-find-if-not (function)
• seq-foreach (function)
• seq-interpose (function)
• seq-iterate (function)
• seq-length (function)
• seq-map (function)
• seq-mappend (function)
• seq-member (function)
• seq-member-if (function)
• seq-member-if-not (function)
• seq-notany (function)
• seq-notevery (function)
• seq-null (function)
• seq-position (function)
• seq-position-if (function)
• seq-position-if-not (function)
• seq-range (function)
• seq-reduce (function)
• seq-remove (function)
• seq-remove-if (function)
• seq-remove-if-not (function)
• seq-repeat (function)
• seq-repeatedly (function)
• seq-some (function)
• seq-split (function)
• seq-split-if (function)
• seq-split-if-not (function)
• seq-take (function)
• seq-take-nth (function)
• seq-take-while (function)
• seq-take-while-not (function)
• seq-zip (function)
• seqp (generic function)
• seqp (method)
• seqp (method)
• seqp (method)
• seqp (method)
• seqp (method)

Internal Definitions

• basic-seq (structure)
• basic-seq-delayed-enum (function)
• (setf basic-seq-delayed-enum) (function)
• basic-seq-p (function)
• copy-basic-seq (function)
• copy-delayed-seq (function)
• delayed-seq (structure)
• delayed-seq-delayed-seq (function)
• (setf delayed-seq-delayed-seq) (function)
• delayed-seq-p (function)
• enum-append-2 (function)
• enum-reduce (function)
• make-basic-seq (function)
• make-delayed-seq (function)
• seq-every-1 (function)
• seq-foreach-1 (function)
• seq-map-1 (function)
• seq-mappend-1 (function)
• seq-notany-1 (function)
• seq-notevery-1 (function)
• seq-some-1 (function)

4.2 Other

4.2.1 generic-sequences/src/README

Dependency

generic-seq.lisp (file)

Parent

src (module)

Location

/home/quickref/quicklisp/dists/quicklisp/software/generic-sequences-20150709-git/src/README (not found)

4.2.2 generic-sequences/src/LICENSE

Dependency

readme (file)

Parent

src (module)

Location

/home/quickref/quicklisp/dists/quicklisp/software/generic-sequences-20150709-git/src/LICENSE (not found)

5 Packages

Packages are listed by definition order.

5.1 generic-seq

Source

generic-seq-pkg.lisp (file)

Nickname

gen-seq

Use List

common-lisp

Exported Definitions

• delay-seq (macro)
• enum-append (macro)
• enum-car (macro)
• enum-cdr (macro)
• enum-cons (macro)
• make-seq (macro)
• seq (type)
• seq->list (function)
• seq->vector (function)
• seq-append (function)
• seq-car (function)
• seq-cdr (function)
• seq-compare (function)
• seq-cons (function)
• seq-count (function)
• seq-count-if (function)
• seq-count-if-not (function)
• seq-cycle (function)
• seq-drop (function)
• seq-drop-while (function)
• seq-drop-while-not (function)
• seq-elt (function)
• seq-enum (generic function)
• seq-enum (method)
• seq-enum (method)
• seq-enum (method)
• seq-enum (method)
• seq-equal (function)
• seq-every (function)
• seq-find (function)
• seq-find-if (function)
• seq-find-if-not (function)
• seq-foreach (function)
• seq-interpose (function)
• seq-iterate (function)
• seq-length (function)
• seq-map (function)
• seq-mappend (function)
• seq-member (function)
• seq-member-if (function)
• seq-member-if-not (function)
• seq-notany (function)
• seq-notevery (function)
• seq-null (function)
• seq-position (function)
• seq-position-if (function)
• seq-position-if-not (function)
• seq-range (function)
• seq-reduce (function)
• seq-remove (function)
• seq-remove-if (function)
• seq-remove-if-not (function)
• seq-repeat (function)
• seq-repeatedly (function)
• seq-some (function)
• seq-split (function)
• seq-split-if (function)
• seq-split-if-not (function)
• seq-take (function)
• seq-take-nth (function)
• seq-take-while (function)
• seq-take-while-not (function)
• seq-zip (function)
• seqp (generic function)
• seqp (method)
• seqp (method)
• seqp (method)
• seqp (method)
• seqp (method)

Internal Definitions

• basic-seq (structure)
• basic-seq-delayed-enum (function)
• (setf basic-seq-delayed-enum) (function)
• basic-seq-p (function)
• copy-basic-seq (function)
• copy-delayed-seq (function)
• delayed-seq (structure)
• delayed-seq-delayed-seq (function)
• (setf delayed-seq-delayed-seq) (function)
• delayed-seq-p (function)
• enum-append-2 (function)
• enum-reduce (function)
• make-basic-seq (function)
• make-delayed-seq (function)
• seq-every-1 (function)
• seq-foreach-1 (function)
• seq-map-1 (function)
• seq-mappend-1 (function)
• seq-notany-1 (function)
• seq-notevery-1 (function)
• seq-some-1 (function)

6 Definitions

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

6.1 Exported definitions

6.1.1 Macros

Macro: delay-seq SEQ

Delay the sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Macro: enum-append &rest ENUMS

Append the specified enumerators.

Package

generic-seq

Source

generic-seq.lisp (file)

Macro: enum-car ENUM

Return the CAR part.

Package

generic-seq

Source

generic-seq.lisp (file)

Macro: enum-cdr ENUM

Return the CDR part.

Package

generic-seq

Source

generic-seq.lisp (file)

Macro: enum-cons ITEM ENUM

Construct a new enumerator.

Package

generic-seq

Source

generic-seq.lisp (file)

Macro: make-seq &body ENUM

Create a sequence by specifying its enumerator.

Package

generic-seq

Source

generic-seq.lisp (file)

6.1.2 Functions

Function: seq->list SEQ

Convert the sequence to a list.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq->vector SEQ

Convert the sequence to a vector.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-append &rest SEQS

Append the specified sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-car SEQ

Return the head of sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-cdr SEQ

Return the tail of sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-compare SEQ-1 SEQ-2 TEST &key KEY

Compare two sequences where the test function for items must return <0, >0 or 0.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-cons ITEM SEQ

Construct a new sequence that begins with the specified item and ends with the sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-count ITEM SEQ &key TEST KEY

Count and return the number of elements in the sequence that satisfy the test.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-count-if PREDICATE SEQ &key KEY

Count and return the number of elements in the sequence that satisfy the test.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-count-if-not PREDICATE SEQ &key KEY

Count and return the number of elements in the sequence that satisfy the test.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-cycle SEQ

It returns a lazy infinite sequence obtained by successively repeating the values in the supplied sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-drop N SEQ

Drop the first N elements of the sequence and return the rest.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-drop-while PREDICATE SEQ &key KEY

SEQ-DROP-WHILE takes a predicate function taking a single argument
and a sequence. It returns a sequence of all items in the original sequence, starting from the first item for which the predicate function returns NIL.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-drop-while-not PREDICATE SEQ &key KEY

SEQ-DROP-WHILE-NOT takes a predicate function taking a single argument
and a sequence. It returns a sequence of all items in the original sequence, starting from the first item for which the predicate function returns T.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-elt SEQ INDEX

Access the element of the sequence specified by index.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-equal SEQ-1 SEQ-2 &key TEST KEY

Test two sequences for equality.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-every PREDICATE &rest SEQS

Like the EVERY function but applied to generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-find ITEM SEQ &key TEST KEY

Search a sequence for an item and return this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-find-if PREDICATE SEQ &key KEY

Search a sequence for an item for which the predicate returns T and return this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-find-if-not PREDICATE SEQ &key KEY

Search a sequence for an item for which the predicate returns NIL and return this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-foreach FUNCTION &rest SEQS

Apply the specified function to the sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-interpose VALUE SEQ

SEQ-INTERPOSE takes two arguments, a value and a sequence. It returns
a lazy sequence obtained by inserting the supplied value between the values in the sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-iterate FUNCTION INITIAL-VALUE

It returns an infinite lazy sequence obtained by starting with the supplied value, and then by calling the supplied function passing the previous item in the sequence as its argument.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-length SEQ

Return the length of the specified sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-map FUNCTION &rest SEQS

Like the MAPCAR function but applied to generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-mappend FUNCTION &rest SEQS

Like SEQ-MAP but the specified function must return a sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-member ITEM SEQ &key TEST KEY

Search a sequence for an item and return the tail of the sequence beginning with this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-member-if PREDICATE SEQ &key KEY

Search a sequence for a top-level item for which the predicate returns T and
return the tail of the sequence beginning with this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-member-if-not PREDICATE SEQ &key KEY

Search a sequence for a top-level item for which the predicate returns NIL and return the tail of the sequence beginning with this element; otherwise NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-notany PREDICATE &rest SEQS

Like the NOTANY function but applied to generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-notevery PREDICATE &rest SEQS

Like the NOTEVERY function but applied to generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-null SEQ

Test whether the sequence is empty.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-position ITEM SEQ &key TEST KEY

Search a sequence for an element and return the index within the sequence; otherwise, NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-position-if PREDICATE SEQ &key KEY

Search a sequence for an element for which the predicate returns T and return the index within the sequence; otherwise, NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-position-if-not PREDICATE SEQ &key KEY

Search a sequence for an element for which the predicate returns NIL and return the index within the sequence; otherwise, NIL is returned.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-range &key START END STEP

SEQ-RANGE returns a lazy sequence of numbers from the start (inclusive, 0 by default) to the end (exclusive, nil by default) incremented by the step (1 by default).

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-reduce FUNCTION SEQ &key KEY INITIAL-VALUE

Like REDUCE but applied to the generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-remove ITEM SEQ &key TEST KEY

Like the REMOVE function but applied to the generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-remove-if TEST SEQ &key KEY

Like the REMOVE-IF function but applied to the generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-remove-if-not TEST SEQ &key KEY

Like the REMOVE-IF-NOT function but applied to the generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-repeat VALUE

It returns an infinite lazy sequence consisting of the argument value repeated endlessly.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-repeatedly FUNCTION

Return an infinite lazy sequence obtained by calling the function repeatedly.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-some PREDICATE &rest SEQS

Like the SOME function but applied to generic sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-split N SEQ

Split the sequence at the N-th element and return the both parts as a list.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-split-if PREDICATE SEQ &key KEY

SEQ-SPLIT-IF takes a predicate function taking a single argument
and a sequence. It splits the sequence at the first item for which the predicate function returns T and and then SEQ-SPLIT-IF returns the both parts as a list.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-split-if-not PREDICATE SEQ &key KEY

SEQ-SPLIT-IF-NOT takes a predicate function taking a single argument
and a sequence. It splits the sequence at the first item for which the predicate function returns NIL and then SEQ-SPLIT-IF-NOT returns the both parts as a list.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-take N SEQ

Take the first N elements of the sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-take-nth N SEQ

TAKE-NTH takes two arguments, a number and a sequence. It returns a sequence of items from the supplied sequence, taking the first item and every Nth item, where N is the supplied number.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-take-while PREDICATE SEQ &key KEY

SEQ-TAKE-WHILE takes a predicate function taking a single argument
and a sequence. It returns a sequence of all items in the original sequence, up until the first item for which the predicate function returns NIL.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-take-while-not PREDICATE SEQ &key KEY

SEQ-TAKE-WHILE-NOT takes two arguments, a predicate function taking a single argument and a sequence. It returns a sequence of all items in the original sequence, up until the first item for which the predicate function returns T.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-zip &rest SEQS

Return a sequence that returns lists of items from the provided sequences.

Package

generic-seq

Source

generic-seq.lisp (file)

6.1.3 Generic functions

Generic Function: seq-enum SEQ

Returns either NIL or an enumerator.

Package

generic-seq

Source

generic-seq.lisp (file)

Methods

Method: seq-enum (SEQ vector)

Method: seq-enum (SEQ list)

Method: seq-enum (SEQ delayed-seq)

Method: seq-enum (SEQ basic-seq)

Generic Function: seqp SEQ

Test whether this is a sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Methods

Method: seqp (SEQ vector)

Method: seqp (SEQ list)

Method: seqp (SEQ delayed-seq)

Method: seqp (SEQ basic-seq)

Method: seqp SEQ

6.1.4 Types

Type: seq ()

The generic sequence type.

Package

generic-seq

Source

generic-seq.lisp (file)

6.2 Internal definitions

6.2.1 Functions

Function: basic-seq-delayed-enum INSTANCE

Function: (setf basic-seq-delayed-enum) VALUE INSTANCE

Package

generic-seq

Source

generic-seq.lisp (file)

Function: basic-seq-p OBJECT

Package

generic-seq

Source

generic-seq.lisp (file)

Function: copy-basic-seq INSTANCE

Package

generic-seq

Source

generic-seq.lisp (file)

Function: copy-delayed-seq INSTANCE

Package

generic-seq

Source

generic-seq.lisp (file)

Function: delayed-seq-delayed-seq INSTANCE

Function: (setf delayed-seq-delayed-seq) VALUE INSTANCE

Package

generic-seq

Source

generic-seq.lisp (file)

Function: delayed-seq-p OBJECT

Package

generic-seq

Source

generic-seq.lisp (file)

Function: enum-append-2 ENUM-1 DELAYED-ENUM-2

Append two enumerators.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: enum-reduce FUNCTION ENUM &key KEY INITIAL-VALUE

Like REDUCE but applied to the enumerators.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: make-basic-seq &key (DELAYED-ENUM DELAYED-ENUM)

Package

generic-seq

Source

generic-seq.lisp (file)

Function: make-delayed-seq &key (DELAYED-SEQ DELAYED-SEQ)

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-every-1 PREDICATE SEQ

Like EVERY but applied to one generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-foreach-1 FUNCTION SEQ

Apply the specified function to the sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-map-1 FUNCTION SEQ

Like the MAPCAR function but applied to a single generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-mappend-1 FUNCTION SEQ

Like SEQ-MAP-1 but the specified function must return a sequence. In other words, this is a monadic bind function.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-notany-1 PREDICATE SEQ

Like NOTANY but applied to one generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-notevery-1 PREDICATE SEQ

Like NOTEVERY but applied to one generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Function: seq-some-1 PREDICATE SEQ

Like SOME but applied to one generic sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

6.2.2 Structures

Structure: basic-seq ()

Represents the basic sequence that is defined only by its enumerator.

Package

generic-seq

Source

generic-seq.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

• seq-enum (method)
• seqp (method)

Direct slots

Slot: delayed-enum

Readers

basic-seq-delayed-enum (function)

Writers

(setf basic-seq-delayed-enum) (function)

Structure: delayed-seq ()

The delayed sequence.

Package

generic-seq

Source

generic-seq.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

• seq-enum (method)
• seqp (method)

Direct slots

Slot: delayed-seq

Readers

delayed-seq-delayed-seq (function)

Writers

(setf delayed-seq-delayed-seq) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types