The incf-cl Reference Manual

Table of Contents

The incf-cl Reference Manual

This is the incf-cl Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 12:01:05 2018 GMT+0.

1 Introduction

#+TITLE: (INCF CL)
#+AUTHOR: Juan M. Bello Rivas
#+EMAIL: jmbr@superadditive.com
#+DATE: <2010-09-05 Sun>

* Overview

The library =(INCF CL)= is a collection of convenience functions and
macros for Common Lisp.
The features it provides are:
  - List comprehensions.
  - Doctest suite for automatic verification of examples in docstrings.
  - List manipulation functions similar to those in Haskell's prelude.
  - Nesting functions akin to those available in Mathematica.

This library is released under the X11 license and it has been tested
with the following Common Lisp implementations:
  - [[http://www.clozure.com/clozurecl.html][Clozure Common Lisp]] 1.6
  - [[http://www.sbcl.org][Steel Bank Common Lisp]] 1.0.41
  - [[http://common-lisp.net/project/armedbear/][Armed Bear Common Lisp]] 0.22.0

* Usage

** Installation

The easiest way to install =(INCF CL)= is to use ASDF-INSTALL:
#+BEGIN_SRC lisp
(asdf:load-system :asdf-install)
(asdf-install:install :incf-cl)
#+END_SRC lisp

If you don't have ASDF-INSTALL, [[http://github.com/jmbr/incf-cl/tarball/master][download the latest snapshot]] or clone
[[http://github.com/jmbr/incf-cl][the source code repository]] by issuing the following command:
#+BEGIN_SRC sh
$ git clone git://github.com/jmbr/incf-cl.git
#+END_SRC
and then follow the ASDF installation procedure for your CL
implementation.

Note that you will need [[http://common-lisp.net/project/stefil/][Stefil]] if you want to run the test suite.

** Loading the library

To begin using the library write:
#+BEGIN_SRC lisp
(asdf:load-system :incf-cl)
(use-package :incf-cl)
#+END_SRC

** Features

*** Ranges

The function =RANGE= is similar to MATLAB's vector notation.  Some use
cases are:
#+BEGIN_SRC lisp
CL-USER> (range 1 10)
(1 2 3 4 5 6 7 8 9 10)

CL-USER> (range 0 1/4 1)
(0 1/4 1/2 3/4 1)
#+END_SRC

*** List comprehensions

List comprehensions are a programming language construct that closely
mimics the way you declare a set in mathematics and are sometimes more
succinct and readable than a composition of =MAPCAR= and =DELETE-IF=
or a loop.

Here are two examples of how to use the =LC= (short for List
Comprehension) macro:
#+BEGIN_SRC lisp
CL-USER> (lc (sin x) (<- x (range 0 .25 (/ pi 2))))
(0.0 0.24740396 0.47942555 0.6816388 0.84147096 0.9489846 0.997495)
CL-USER> (lc (cons x y) (<- x (range 0 2)) (<- y (range 0 2))
             (= (+ x y) 2))
((0 . 2) (1 . 1) (2 . 0))
#+END_SRC

*** Doctests

=DOCTEST= checks documentation strings for correctness.
For every exported function in the package name passed to =DOCTEST=,
1. each docstring is scanned for pieces of text resembling interactive sessions,
2. then those snippets are evaluated,
3. and the resulting values are checked against the expected ones.

For example, consider the package =TEST=:
#+BEGIN_SRC lisp
  (defpackage :test
    (:use :common-lisp :incf-cl)
    (:export :factorial))

  (in-package :test)

  (defun factorial (n &optional (acc 1))
    "Returns the factorial of N, where N is an integer >= 0.

    Examples:

    TEST> (lc (factorial n) (<- n (range 1 5)))
    (1 2 6 24 120)

    TEST> (factorial 450/15)
    265252859812191058636308480000000

    TEST> (signals-p arithmetic-error (factorial -1))
    T

    TEST> (signals-p type-error (factorial 30.1))
    T

    TEST> (factorial 0)
    1"
    (declare (type integer n))

    (cond
      ((minusp n) (error 'arithmetic-error))
      ((/= n (floor n)) (error 'type-error)))

    (if (= n 0)
        acc
        (factorial (1- n) (* n acc))))
#+END_SRC
You can use =DOCTEST= to make sure the examples given in =FACTORIAL='s
documentation string work as expected by writing
#+BEGIN_SRC lisp
CL-USER> (doctest :test)
.....
T
#+END_SRC
Or, equivalently,
#+BEGIN_SRC lisp
CL-USER> (doctest 'test::factorial)
.....
T
#+END_SRC


*** Prelude

Some list manipulation functions patterned after Haskell's prelude are
available.  Namely,
  - =BREAK*=
  - =CYCLE= (and its destructive version =NCYCLE=).
  - =DROP=
  - =DROP-WHILE=
  - =FLIP=
  - =GROUP=
  - =INSERT=
  - =INTERSPERSE= (and its destructive version =NINTERSPERSE=).
  - =PARTITION=
  - =REPLICATE=
  - =SCAN*= (using the key parameters =:INITIAL-VALUE= and =:FROM-END=
    it works as =scanl=, =scanl1=, =scanr=, or =scanr1=)
  - =SPAN=
  - =SPLIT-AT=
  - =TAKE=
  - =TAKE-WHILE=
  - =UNZIP=
The on-line documentation for each of them can be read using
=DESCRIBE= (or =M-x slime-describe-symbol= in [[http://common-lisp.net/project/slime/][SLIME]]).  See also [[http://ww2.cs.mu.oz.au/~bjpop/papers/haskell.tour.tar.gz][A Tour
of the Haskell Prelude]] for more information.

Since Common Lisp doesn't guarantee tail call elimination, these
functions are written iteratively to avoid stack overflows.

*** Nesting

The function =NEST-LIST= applies a function to an initial value, then
applies the same function to the previous result, and so on.  This
stops after a specified number of evaluations or when a given
predicate is true and a list containing all the results is returned.

=NEST= works as =NEST-LIST= but it only returns the last result, not
the whole list.

Some examples:
#+BEGIN_SRC lisp
CL-USER> (setf *print-circle* nil)
NIL
CL-USER> (nest-list (lambda (x) `(sin ,x)) 'z :max 3)
(Z (SIN Z) (SIN (SIN Z)) (SIN (SIN (SIN Z))))

CL-USER> (nest-list #'+ '(1 1) :max 10)
(1 1 2 3 5 8 13 21 34 55 89 144)

CL-USER> (nest #'+ '(1 1) :max 10)
144

CL-USER> (nest-list (lambda (x) (mod (* 2 x) 19))
                    2
                    :test (lambda (x) (/= x 1)))
(2 4 8 16 13 7 14 9 18 17 15 11 3 6 12 5 10 1)
#+END_SRC

The closely related function =FIXED-POINT= returns the fixed point of
a function starting from an initial value.  Whether a fixed point has
been reached or not is determined by a test function (=EQL= by
default).

For example, the square root of 2 using Newton's method can be
computed as:
#+BEGIN_SRC lisp
CL-USER> (fixed-point (lambda (x)
                        (float (- x (/ (- (expt x 2) 2) (* 2 x)))))
                      1)
1.4142135
#+END_SRC

*** Unfolds

There's an implementation of =UNFOLD= and =UNFOLD-RIGHT= as specified
in [[http://srfi.schemers.org/srfi-1/srfi-1.html#unfold][SRFI 1: List library]].  Here's an example of =UNFOLD=:
#+BEGIN_SRC lisp
  (defun euler (f x0 y0 interval h)
    "Computes an approximate solution of the initial value problem:

      y' = f(x, y), x in interval;  y(x0) = y0

    using Euler's explicit method.  Interval is a list of two elements
    representing a closed interval.  The function returns a list of
    points and the values of the approximate solution at those points.

    For example,

    EULER> (euler (lambda (x y)
                    (declare (ignore y))
                    (- (sin x)))
                  0 1 (list 0 (/ pi 2)) 0.5)
    ((0 1) (0.5 1.0) (1.0 0.7602872) (1.5 0.33955175))"
    (assert (<= (first interval) (second interval)))
    (unfold (lambda (x) (> (first x) (second interval)))
            #'identity
            (lambda (pair)
              (destructuring-bind (x y) pair
                (list (+ x h) (+ y (* h (funcall f x y))))))
            (list x0 y0)))
#+END_SRC

*** Functions

The function =$= returns the composition of several functions.  The
following example illustrates its use:
#+BEGIN_SRC lisp
CL-USER> (funcall ($ (lambda (x) (* x x))
                     (lambda (x) (+ x 2)))
                  2)
16
#+END_SRC

*** Hash table utilities

=DOHASH= iterates over a hash table with semantics similar to those of
=DOLIST=:
#+BEGIN_SRC lisp
CL-USER> (defparameter *hash-table* (make-hash-table))
*HASH-TABLE*
CL-USER> (setf (gethash "one" *hash-table*) 1)
1
CL-USER> (setf (gethash "two" *hash-table*) 2)
2
CL-USER> (setf (gethash "three" *hash-table*) 3)
3
CL-USER> (dohash (key value *hash-table*)
           (format t "~a => ~d~%" key value))
three => 3
two => 2
one => 1
NIL
CL-USER> (let ((product 1))
           (dohash (key value *hash-table* product)
             (setf product (* product value))))
6
#+END_SRC

*** Strings

=STRING-JOIN= glues together a list of strings placing a given
separator between each string.  By default, the separator is a space.
#+BEGIN_SRC lisp
CL-USER> (string-join '("Hello" "world"))
"Hello world"
CL-USER> (string-join '("Hello" "world") ", ")
"Hello, world"
#+END_SRC

* Links

Some of the features of =(INCF CL)= are discussed in:
- [[http://kyle-burton.livejournal.com/8219.html][Playing with List Comprehensions in CL]]
- [[http://i-need-closures.blogspot.com/2008/01/programming-collective-intelligence-in.html][Programming Collective Intelligence in Common Lisp, Chapter 5 -
  Optimizations]]

* Feedback

Please send suggestions, patches, and bug reports to the [[http://superadditive.com/contact/][author's
email address]].

# Some extra directives for HTML generation follow.  These have nothing to do with the document's content.
#+STYLE: 
#+STYLE: 
#+STYLE: 
#+OPTIONS: toc:2

2 Systems

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

2.1 incf-cl

Author

Juan M. Bello Rivas <jmbr@superadditive.com>

License

X11

Description

INCF CL is a library of convenience functions for Common Lisp

Dependency

cl-ppcre

Source

incf-cl.asd (file)

Components

• package.lisp (file)
• function.lisp (file)
• lc.lisp (file)
• nest.lisp (file)
• unfold.lisp (file)
• range.lisp (file)
• prelude.lisp (file)
• unscan.lisp (file)
• fixed-point.lisp (file)
• hash-table.lisp (file)
• iteration.lisp (file)
• string.lisp (file)
• doctest.lisp (file)
• symbol.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 incf-cl.asd

Location

incf-cl.asd

Systems

incf-cl (system)

3.1.2 incf-cl/package.lisp

Parent

incf-cl (system)

Location

package.lisp

Packages

incf-cl

3.1.3 incf-cl/function.lisp

Dependency

package.lisp (file)

Parent

incf-cl (system)

Location

function.lisp

Exported Definitions

$ (function)

Internal Definitions

canonicalize-test (function)

3.1.4 incf-cl/lc.lisp

Dependency

function.lisp (file)

Parent

incf-cl (system)

Location

lc.lisp

Exported Definitions

lc (macro)

Internal Definitions

• translate-comprehension (function)
• translate-filter (function)
• translate-generator (function)
• translate-generator-or-filter (function)

3.1.5 incf-cl/nest.lisp

Dependency

lc.lisp (file)

Parent

incf-cl (system)

Location

nest.lisp

Exported Definitions

• nest (function)
• nest-list (function)

Internal Definitions

• %nest-list (function)
• ensure-and-copy-list (function)

3.1.6 incf-cl/unfold.lisp

Dependency

nest.lisp (file)

Parent

incf-cl (system)

Location

unfold.lisp

Exported Definitions

• unfold (function)
• unfold-right (function)

3.1.7 incf-cl/range.lisp

Dependency

unfold.lisp (file)

Parent

incf-cl (system)

Location

range.lisp

Exported Definitions

range (function)

3.1.8 incf-cl/prelude.lisp

Dependency

range.lisp (file)

Parent

incf-cl (system)

Location

prelude.lisp

Exported Definitions

• break* (generic function)
• break* (method)
• cycle (generic function)
• cycle (method)
• cycle (method)
• drop (generic function)
• drop (method)
• drop-while (generic function)
• drop-while (method)
• flip (function)
• group (generic function)
• group (method)
• insert (generic function)
• insert (method)
• intersperse (generic function)
• intersperse (method)
• intersperse (method)
• ncycle (generic function)
• ncycle (method)
• ncycle (method)
• nintersperse (generic function)
• nintersperse (method)
• partition (generic function)
• partition (method)
• replicate (function)
• scan* (generic function)
• scan* (method)
• span (generic function)
• span (method)
• split-at (generic function)
• split-at (method)
• take (generic function)
• take (method)
• take-while (generic function)
• take-while (method)
• unzip (function)

Internal Definitions

• apply-key (function)
• first-with (function)
• function-or-null (type)
• scan-left* (function)
• scan-right* (function)

3.1.9 incf-cl/unscan.lisp

Dependency

prelude.lisp (file)

Parent

incf-cl (system)

Location

unscan.lisp

Exported Definitions

• unscan (generic function)
• unscan (method)
• unscan (method)

3.1.10 incf-cl/fixed-point.lisp

Dependency

unscan.lisp (file)

Parent

incf-cl (system)

Location

fixed-point.lisp

Exported Definitions

fixed-point (function)

3.1.11 incf-cl/hash-table.lisp

Dependency

fixed-point.lisp (file)

Parent

incf-cl (system)

Location

hash-table.lisp

Exported Definitions

dohash (macro)

3.1.12 incf-cl/iteration.lisp

Dependency

hash-table.lisp (file)

Parent

incf-cl (system)

Location

iteration.lisp

Exported Definitions

while (macro)

3.1.13 incf-cl/string.lisp

Dependency

iteration.lisp (file)

Parent

incf-cl (system)

Location

string.lisp

Exported Definitions

string-join (function)

3.1.14 incf-cl/doctest.lisp

Dependency

string.lisp (file)

Parent

incf-cl (system)

Location

doctest.lisp

Exported Definitions

• *doctest-show-progress* (special variable)
• doctest (function)
• signals-p (macro)

Internal Definitions

• actual-values (method)
• doctest-failure (condition)
• expected-values (method)
• sexpr (method)
• test-docstring (function)
• test-function (function)

3.1.15 incf-cl/symbol.lisp

Dependency

doctest.lisp (file)

Parent

incf-cl (system)

Location

symbol.lisp

Exported Definitions

• list-all-symbols (function)
• list-external-symbols (function)

4 Packages

Packages are listed by definition order.

4.1 incf-cl

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

• $ (function)
• *doctest-show-progress* (special variable)
• break* (generic function)
• break* (method)
• cycle (generic function)
• cycle (method)
• cycle (method)
• doctest (function)
• dohash (macro)
• drop (generic function)
• drop (method)
• drop-while (generic function)
• drop-while (method)
• fixed-point (function)
• flip (function)
• group (generic function)
• group (method)
• insert (generic function)
• insert (method)
• intersperse (generic function)
• intersperse (method)
• intersperse (method)
• lc (macro)
• list-all-symbols (function)
• list-external-symbols (function)
• ncycle (generic function)
• ncycle (method)
• ncycle (method)
• nest (function)
• nest-list (function)
• nintersperse (generic function)
• nintersperse (method)
• partition (generic function)
• partition (method)
• range (function)
• replicate (function)
• scan* (generic function)
• scan* (method)
• signals-p (macro)
• span (generic function)
• span (method)
• split-at (generic function)
• split-at (method)
• string-join (function)
• take (generic function)
• take (method)
• take-while (generic function)
• take-while (method)
• unfold (function)
• unfold-right (function)
• unscan (generic function)
• unscan (method)
• unscan (method)
• unzip (function)
• while (macro)

Internal Definitions

• %nest-list (function)
• actual-values (generic function)
• actual-values (method)
• apply-key (function)
• canonicalize-test (function)
• doctest-failure (condition)
• ensure-and-copy-list (function)
• expected-values (generic function)
• expected-values (method)
• first-with (function)
• function-or-null (type)
• scan-left* (function)
• scan-right* (function)
• sexpr (generic function)
• sexpr (method)
• test-docstring (function)
• test-function (function)
• translate-comprehension (function)
• translate-filter (function)
• translate-generator (function)
• translate-generator-or-filter (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *doctest-show-progress*

Determines if a dot will be displayed for each passed test.

Package

incf-cl

Source

doctest.lisp (file)

5.1.2 Macros

Macro: dohash (KEY VALUE HASH-TABLE &optional RESULT-FORM) &body BODY

DOHASH iterates over the keys and values of HASH-TABLE. It returns NIL or the result of evaluating RESULT-FORM if it was specified.

Package

incf-cl

Source

hash-table.lisp (file)

Macro: lc COLLECTION-FORM &rest QUANTIFIERS

Assembles a multiset containing the results of evaluating COLLECTION-FORM and subject to QUANTIFIERS.

Package

incf-cl

Source

lc.lisp (file)

Macro: signals-p CONDITION &body BODY

Returns T if evaluating BODY results in CONDITION being signalled, NIL otherwise.

Package

incf-cl

Source

doctest.lisp (file)

Macro: while PREDICATE-FORM &body BODY

Executes BODY while PREDICATE-FORM is non NIL.

Package

incf-cl

Source

iteration.lisp (file)

5.1.3 Functions

Function: $ &rest FUNCTIONS

Returns the composition of FUNCTIONS. Note that FUNCTIONS must
be composable in the order specified.

For example,

INCF-CL> (funcall ($ (lambda (x) (* x x))
(lambda (x) (+ x 2)))
2)
16

INCF-CL> (funcall ($ #’values #’floor #’sqrt (lambda (x) (expt x 2))) -2) 2

Package

incf-cl

Source

function.lisp (file)

Function: doctest SYMBOL &key STREAM

If SYMBOL corresponds to a function, then its documentation string is tested and the results are printed to STREAM. If SYMBOL refers to a package, then all the functions corresponding to the external symbols in the package are tested.
DOCTEST returns T if the tests succeed, NIL otherwise.

Package

incf-cl

Source

doctest.lisp (file)

Function: fixed-point FUNCTION INITIAL-VALUE &key TEST MAX-STEPS

Returns the fixed point of FUNCTION starting with INITIAL-VALUE. The keyword argument TEST determines when a fixed point has been reached. Use MAX-STEPS to stop after a certain (positive) number of iterations.

For example, the square root of 2 using Newton’s method can be computed as:

INCF-CL> (fixed-point (lambda (x)
(float (- x (/ (- (expt x 2) 2) (* 2 x))))) 1)
1.4142135

INCF-CL> (sqrt 2)
1.4142135

Package

incf-cl

Source

fixed-point.lisp (file)

Function: flip F

Applied to a binary function F, returns the same function with the order of the arguments reversed.

Package

incf-cl

Source

prelude.lisp (file)

Function: list-all-symbols PACKAGE

Returns a list containing all the symbols in PACKAGE.

Package

incf-cl

Source

symbol.lisp (file)

Function: list-external-symbols PACKAGE

Returns a list containing all the exported symbols in PACKAGE.

Package

incf-cl

Source

symbol.lisp (file)

Function: nest FUNCTION INITIAL-VALUES &key TEST TEST-NOT N M MAX

Package

incf-cl

Source

nest.lisp (file)

Function: nest-list FUNCTION INITIAL-VALUES &key TEST TEST-NOT N M MAX

Returns a list of the results of applying FUNCTION successively to INITIAL-VALUES and continuing until applying TEST (respectively TEST-NOT) to the result is non NIL.

If M is specified, then NEST-LIST supplies the M most recent results as arguments for TEST (respectivelly TEST-NOT) at each step.

If MAX is specified then FUNCTION is applied at most MAX times.

Package

incf-cl

Source

nest.lisp (file)

Function: range A B &optional C

Package

incf-cl

Source

range.lisp (file)

Function: replicate N X

Returns a list contaning N times the value X

Package

incf-cl

Source

prelude.lisp (file)

Function: string-join LIST &optional SEP

Returns a string joining each string in LIST by SEP. If SEP is not specified, the default separator is a space.

Package

incf-cl

Source

string.lisp (file)

Function: unfold PREDICATE TRANSFORMER INCREMENTOR INITIAL-VALUE &optional TAIL-GEN

Returns a list built following the pattern:

transformer(initial-value), transformer(incrementor(initial-value)), ...

Examples:

1. List of squares: 1^2, ..., 10^2

INCF-CL> (unfold (lambda (x) (> x 10)) (lambda (x) (expt x 2)) #’1+ 1) (1 4 9 16 25 36 49 64 81 100)

2. Append (3 4 5) onto (1 2)

INCF-CL> (unfold #’null #’first #’rest (list 1 2) (lambda (x) (declare (ignore x)) (list 3 4 5))) (1 2 3 4 5)

See also:
http://srfi.schemers.org/srfi-1/srfi-1.html#unfold

Package

incf-cl

Source

unfold.lisp (file)

Function: unfold-right PREDICATE TRANSFORMER INCREMENTOR INITIAL-VALUE &optional TAIL

Returns a list built following the pattern:

... transformer(incrementor(initial-value)), transformer(initial-value)

Examples:

1. List of squares: 1^2, ..., 10^2

INCF-CL> (unfold-right #’zerop (lambda (x) (* x x)) #’1- 10)
(1 4 9 16 25 36 49 64 81 100)

2. Reverse a proper list:

INCF-CL> (unfold-right #’null #’first #’rest (list 1 2 3 4 5))
(5 4 3 2 1)

See also: http://srfi.schemers.org/srfi-1/srfi-1.html#unfold-right

Package

incf-cl

Source

unfold.lisp (file)

Function: unzip ALIST

Applied to the association list ALIST, returns two lists (as VALUES) containing the keys and values of each element in ALIST respectively. This function is the inverse of PAIRLIS.

Package

incf-cl

Source

prelude.lisp (file)

5.1.4 Generic functions

Generic Function: break* PREDICATE LIST &key KEY

Given a PREDICATE and a LIST, breaks LIST into two
lists (returned as VALUES) at the point where PREDICATE is first satisfied. If PREDICATE is never satisfied then the first returned value is the entire LIST and the second element is NIL.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: break* (PREDICATE function) (LIST list) &key KEY

Generic Function: cycle LIST

Returns a circular list containing the elements in LIST (which should be a proper list).

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: cycle (LIST list)

Method: cycle (LIST null)

Generic Function: drop N LIST

Applied to N (a non-negative integer) and LIST,
returns the list with the specified number of elements removed from the front of LIST. If LIST has less than N elements then it returns NIL.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: drop (N integer) (LIST list)

Generic Function: drop-while PREDICATE LIST &key KEY

Applied to PREDICATE and LIST, removes elements
from the front of LIST while PREDICATE is satisfied.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: drop-while (PREDICATE function) (LIST list) &key KEY

Generic Function: group LIST &key KEY TEST TEST-NOT

Returns a list of lists where every item in each
sublist satisfies TEST and the concatenation of the result is equal to LIST.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

For example,

INCF-CL> (mapcar (lambda (x) (concatenate ’string x))
(group (coerce "Mississippi" ’list)))
("M" "i" "ss" "i" "ss" "i" "pp" "i")

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: group (LIST list) &key KEY TEST TEST-NOT

Generic Function: insert X LIST &key KEY TEST TEST-NOT

Inserts X before the first element in LIST which is
greater than X. The order relation can be specified by either one of the keyword arguments TEST and TEST-NOT.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: insert X (LIST list) &key KEY TEST TEST-NOT

Generic Function: intersperse ELEMENT LIST

Returns a list where ELEMENT is interspersed between the elements of SEQUENCE.

For example,

INCF-CL> (intersperse ’x (replicate 3 ’z)) (Z X Z X Z)

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: intersperse ELEMENT (LIST cons)

Method: intersperse ELEMENT (LIST null)

Generic Function: ncycle LIST

Destructive version of CYCLE. Again, keep in mind that LIST must be a proper list.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: ncycle (LIST list)

Method: ncycle (LIST null)

Generic Function: nintersperse ELEMENT LIST

Destructive version of INTERSPERSE.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: nintersperse ELEMENT (LIST list)

Generic Function: partition PREDICATE LIST &key KEY

Applied to PREDICATE and LIST, returns two values: a list containing all the elements from LIST that satisfy PREDICATE, and its complementary list.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: partition (PREDICATE function) (LIST list) &key KEY

Generic Function: scan* FUNCTION LIST &key KEY FROM-END INITIAL-VALUE

SCAN* is similar to REDUCE, but returns a list of
successive reduced values:

(scan* f (list x1 x2 ...) :initial-value z)
==> (z (funcall f z x1) (funcall f (funcall f z x1) x2) ...)

(scan* f (list x1 x2 ...))
==> (x1 (funcall f x1 x2) (funcall f (funcall f x1 x2) x2) ...)

(scan* f (list x1 ... x_n-1 x_n) :initial-value z :from-end t)
==> (... (funcall f x_n-1 (funcall f x_n z)) (funcall f x_n z) z)

(scan* f (list x1 ... x_n-1 x_n) :from-end t)
==> (... (funcall f x_n-1 (funcall f x_n-1 x_n)) (funcall f x_n-1 x_n) x_n)

Examples:

INCF-CL> (scan* #’/ (list 4 2 4) :initial-value 64)
(64 16 8 2)

INCF-CL> (scan* #’max (range 1 7) :initial-value 5)
(5 5 5 5 5 5 6 7)

INCF-CL> (scan* (lambda (x y) (+ (* 2 x) y)) (list 1 2 3) :initial-value 4) (4 9 20 43)

INCF-CL> (scan* #’+ (list 1 2 3 4))
(1 3 6 10)

INCF-CL> (scan* #’+ (list 1 2 3 4) :initial-value 5 :from-end t)
(15 14 12 9 5)

INCF-CL> (scan* #’+ (list 1 2 3 4) :from-end t)
(10 9 7 4)

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: scan* (FUNCTION function) (LIST list) &key KEY FROM-END INITIAL-VALUE

Generic Function: span PREDICATE LIST &key KEY

Splits LIST into two lists (returned as VALUES)
such that elements in the first list are taken from the head of LIST while PREDICATE is satisfied, and elements in the second list are the remaining elements from LIST once PREDICATE is not satisfied.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: span (PREDICATE function) (LIST list) &key KEY

Generic Function: split-at N LIST

Given a non-negative integer N and LIST, splits
LIST into two lists (returned as VALUES) at the position corresponding to the given integer. If N is greater than the length of LIST, it returns the entire list first and the empty list second in VALUES.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: split-at (N integer) (LIST list)

Generic Function: take N LIST

Applied to the integer N and LIST, returns the specified number of elements from the front of LIST. If LIST has less than N elements, TAKE returns the entire LIST.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: take (N integer) (LIST list)

Generic Function: take-while PREDICATE LIST &key KEY

Applied to PREDICATE and LIST, returns a list
containing elements from the front of LIST while PREDICATE is satisfied.

KEY is a designator for a function of one argument, or NIL. If KEY is supplied, it is applied once to each element of LIST before it is passed to PREDICATE. If it is not supplied or is NIL, the element of LIST itself is used.

Package

incf-cl

Source

prelude.lisp (file)

Methods

Method: take-while (PREDICATE function) (LIST list) &key KEY

Generic Function: unscan FUNCTION LIST &key INITIAL-VALUE

Semi-inverse of SCAN*.

INCF-CL> (equal (unscan (flip #’-) (scan* #’+ ’(1 2 3)) :initial-value 0) ’(1 2 3))
T

Package

incf-cl

Source

unscan.lisp (file)

Methods

Method: unscan (FUNCTION function) (LIST list) &key INITIAL-VALUE

Method: unscan (FUNCTION function) (LIST null) &key INITIAL-VALUE

5.2 Internal definitions

5.2.1 Functions

Function: %nest-list FUNCTION INITIAL-VALUES TEST N M MAX

Package

incf-cl

Source

nest.lisp (file)

Function: apply-key KEY ELEMENT

Package

incf-cl

Source

prelude.lisp (file)

Function: canonicalize-test TEST TEST-NOT

Returns a validated test function for those functions that use TEST and TEST-NOT keyword arguments.

Package

incf-cl

Source

function.lisp (file)

Function: ensure-and-copy-list X

Package

incf-cl

Source

nest.lisp (file)

Function: first-with KEY LIST

Package

incf-cl

Source

prelude.lisp (file)

Function: scan-left* FUNCTION LIST KEY INITIAL-VALUE IVP

Package

incf-cl

Source

prelude.lisp (file)

Function: scan-right* FUNCTION LIST KEY INITIAL-VALUE IVP

Package

incf-cl

Source

prelude.lisp (file)

Function: test-docstring DOCUMENTATION

Returns T if the first doctest found in DOCUMENTATION passes, signals DOCTEST-FAILURE otherwise.

Package

incf-cl

Source

doctest.lisp (file)

Function: test-function PACKAGE FUNCTION STREAM

Returns T if every test in FUNCTION’s docstring passes, NIL otherwise.

Package

incf-cl

Source

doctest.lisp (file)

Function: translate-comprehension COLLECTION-FORM QUANTIFIERS

Package

incf-cl

Source

lc.lisp (file)

Function: translate-filter COLLECTION-FORM FILTER-FORM QUANTIFIERS

Package

incf-cl

Source

lc.lisp (file)

Function: translate-generator COLLECTION-FORM VARIABLE COLLECTION QUANTIFIERS

Package

incf-cl

Source

lc.lisp (file)

Function: translate-generator-or-filter COLLECTION-FORM QUANTIFIERS

Package

incf-cl

Source

lc.lisp (file)

5.2.2 Generic functions

Generic Function: actual-values CONDITION

Package

incf-cl

Methods

Method: actual-values (CONDITION doctest-failure)

Source

doctest.lisp (file)

Generic Function: expected-values CONDITION

Package

incf-cl

Methods

Method: expected-values (CONDITION doctest-failure)

Source

doctest.lisp (file)

Generic Function: sexpr CONDITION

Package

incf-cl

Methods

Method: sexpr (CONDITION doctest-failure)

Source

doctest.lisp (file)

5.2.3 Conditions

Condition: doctest-failure ()

Package

incf-cl

Source

doctest.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• expected-values (method)
• actual-values (method)
• sexpr (method)

Direct slots

Slot: sexpr

Initargs

:sexpr

Readers

sexpr (generic function)

Slot: actual-values

Initargs

:actual-values

Readers

actual-values (generic function)

Slot: expected-values

Initargs

:expected-values

Readers

expected-values (generic function)

5.2.4 Types

Type: function-or-null ()

Package

incf-cl

Source

prelude.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types