API Reference

This section contains reference of all the basic functions, classes and macros provided by this library to the user.

Common API

Generic Functions

The following set contains generic functions that can be used to query or manipulate containers. Not all containers can be manipulated with entieriety of those functions. However, applicable functions are defined in the category of container, and thus, this manual lists functions applicable for instances of containers in each category.

Query Functions

Following generic functions check state of the container and are not allowed to change it.

Symbols in the package CL-DATA-STRUCTURES:
AT
Lambda List: (CONTAINER LOCATION &REST MORE-LOCATIONS)
Syntax:
  • for dictionary containers: at dictionary key => value found
  • for everything else: at sequence location => value

Arguments:
  • CONTAINER, Instance of subclass of fundamental-container.
  • LOCATION, Where are we looking at? Key in hashtable, index of vector, etc.

Examples:
(LET ((TABLE
       (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                   #'EQ)))
  (PROVE.TEST:DIAG "Testing example for AT function.")
  (MULTIPLE-VALUE-BIND (VALUE FOUND)
      (CL-DATA-STRUCTURES:AT TABLE 'A)
    (PROVE.TEST:IS VALUE NIL)
    (PROVE.TEST:IS FOUND NIL))
  (SETF (CL-DATA-STRUCTURES:AT TABLE 'A) 1)
  (MULTIPLE-VALUE-BIND (VALUE FOUND)
      (CL-DATA-STRUCTURES:AT TABLE 'A)
    (PROVE.TEST:IS VALUE 1)
    (PROVE.TEST:IS FOUND T)))

Description: Obtain element stored at LOCATION in the CONTAINER.
Returns: In case of associative containers, second value informs if LOCATION was found in the CONTAINER (first value is NIL if element was not found). In case of non-associtive containers (e.g. vectors), the function returns value under LOCATION if LOCATION is valid, otherwise condition of type ARGUMENT-VALUE-OUT-OF-BOUNDS will be raised.
NEAR
Lambda List: (CONTAINER ITEM MAXIMAL-DISTANCE)
Arguments:
  • CONTAINER, Container searched for element.
  • ITEM, Item to search around.
  • MAXIMAL-DISTANCE, Don't yield elements longer

Examples:
(LET* ((DATA #(10 20 40 5 11 12 50 30 20 1 6 7 8 18 21 51 52 80 78))
       (SET
        (CL-DATA-STRUCTURES:MAKE-FROM-TRAVERSABLE DATA
                                                  'CL-DATA-STRUCTURES.METRIC-SPACE.EGNAT:MUTABLE-EGNAT-METRIC-SET
                                                  #'=
                                                  (ALEXANDRIA:COMPOSE #'ABS
                                                                      #'-)
                                                  'FIXNUM))
       (NEAR
        (CL-DATA-STRUCTURES.ALGORITHMS:TO-VECTOR
         (CL-DATA-STRUCTURES:NEAR SET 10 7))))
  (PROVE.TEST:OK (EVERY (LAMBDA (X) (< 3 X 17)) NEAR)))

Description: Searches the CONTAINER for elements that are at most a MAXIMAL-DISTANCE away from the ITEM. Returns a range of elements.
SIZE
Lambda List: (CONTAINER)
Syntax: size container => count
Arguments:
  • container, instance that will be checked.

Examples:
(LET ((CONTAINER
       (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                   #'EQ)))
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:SIZE CONTAINER) 0)
  (SETF (CL-DATA-STRUCTURES:AT CONTAINER 'A) 1)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:SIZE CONTAINER) 1))

Description: How many elements the CONTAINER holds currently?
Returns: The number of elements in the container.
MUTABLEP
Lambda List: (CONTAINER)
Syntax:
  • mutablep mutable-container => t
  • mutablep functional-container => nil

Arguments:
  • CONTAINER, Any subclass of fundamental-container

Examples:
(PROGN
 (PROVE.TEST:DIAG "Running example for mutablep.")
 (LET ((MUTABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                    #'EQ)))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:MUTABLEP MUTABLE))
   (PROVE.TEST:OK (NOT (CL-DATA-STRUCTURES:FUNCTIONALP MUTABLE))))
 (LET ((FUNCTIONAL
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-FUNCTIONAL-HAMT-DICTIONARY #'SXHASH
                                                                       #'EQ)))
   (PROVE.TEST:OK (NOT (CL-DATA-STRUCTURES:MUTABLEP FUNCTIONAL)))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:FUNCTIONALP FUNCTIONAL))))

Returns: T if CONTAINER exposes mutable API and NIL if not.
TRANSACTIONALP
Lambda List: (CONTAINER)
Syntax: transactionalp container => boolean
Arguments:
  • container, An subclass of the fundamental-container.

Examples:
(PROGN
 (PROVE.TEST:DIAG "Running example for the transactionalp.")
 (LET ((CONTAINER
        (CL-DATA-STRUCTURES:BECOME-TRANSACTIONAL
         (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                     #'EQ))))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:MUTABLEP CONTAINER))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:TRANSACTIONALP CONTAINER))))

Returns: T if the CONTAINER is transactional and NIL if it is not.
FUNCTIONALP
Lambda List: (CONTAINER)
Syntax:
  • (functionalp mutable-container) -> nil
  • (functionalp functional-container) -> t

Arguments:
  • container, A subclass of the fundamental-container

Examples:
(PROGN
 (PROVE.TEST:DIAG "Running example for the functionalp function.")
 (LET ((MUTABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                    #'EQ)))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:MUTABLEP MUTABLE))
   (PROVE.TEST:OK (NOT (CL-DATA-STRUCTURES:FUNCTIONALP MUTABLE))))
 (LET ((FUNCTIONAL
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-FUNCTIONAL-HAMT-DICTIONARY #'SXHASH
                                                                       #'EQ)))
   (PROVE.TEST:OK (NOT (CL-DATA-STRUCTURES:MUTABLEP FUNCTIONAL)))
   (PROVE.TEST:OK (CL-DATA-STRUCTURES:FUNCTIONALP FUNCTIONAL))))

Returns: T if CONTAINER exposes functional API and NIL if not.

Immutable and mutable containers are modified by separate sets of functions.

Immutable Mutable
INSERT(SETF AT)
ADDADD!
UPDATEUPDATE!
UPDATE-IFUPDATE-IF!
ERASEERASE!
ERASE-IFERASE-IF!
PUTPUT!
TAKE-OUTTAKE-OUT!
Functional modification API
Symbols in the package CL-DATA-STRUCTURES:
INSERT
Lambda List: (CONTAINER LOCATION NEW-VALUE)
Syntax: insert container location new-value => new-instance status
Arguments:
  • container, Instance of container.
  • location, Designates place in returned instance that will be changed
  • new-value, Value that will be inserted into returned instance

Examples:
(LET* ((TABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-FUNCTIONAL-HAMT-DICTIONARY #'SXHASH
                                                                       #'EQ))
       (NEXT-TABLE (CL-DATA-STRUCTURES:INSERT TABLE 'A 5)))
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'A) 5)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT TABLE 'A) 5 :TEST
                 (ALEXANDRIA:COMPOSE #'NULL #'EQL)))

Description: Functional API: non-destructively insert the NEW-VALUE into the CONTAINER at the LOCATION. Will replace a value at the LOCATION if it was already occupied.
Returns:
  • Instance of the same type as CONTAINER, with NEW-VALUE at LOCATION
  • Modification status object.

Notes: This is the functional counterpart to the (SETF AT) function.
ADD
Lambda List: (CONTAINER LOCATION NEW-VALUE)
Description: Add NEW-VALUE into the CONTAINER at the LOCATION. Will not replace a value at LOCATION if it was already occupied.
UPDATE
Lambda List: (CONTAINER LOCATION NEW-VALUE)
Syntax: update container location new-value => new-instance status
Arguments:
  • container, The instance that shall be transformed.
  • location, The location in the container that we want to transform.

Description: Functional API: if there is value at LOCATION in the CONTAINER return new instance with NEW-VALUE at LOCATION.
Returns:
  • New container, with updated value at LOCATION if UPDATE took place
  • Modification status object

Notes: This is the functional counterpart to the UPDATE! function.
UPDATE-IF
Lambda List: (CONTAINER LOCATION NEW-VALUE CONDITION-FN)
Syntax: update-if container location new-value CONDITION-FN => new-instance status
Arguments:
  • CONTAINER, The instance that shall be transformed.
  • LOCATION, The location in the container that we want to transform.
  • CONDITION-FN, Function used to check if update should happen.

Description: Functional API: if there is a value at the LOCATION in the CONTAINER and the supplied CONDITION-FN returns true when called with the value, return new instance with NEW-VALUE at the LOCATION. Otherwise returns the same CONTAINER.
Returns:
  • A new container, with the updated value at the LOCATION if UPDATE took place.
  • The modification status object

Notes: This is the functional counterpart to the UPDATE-IF! function.
ERASE
Lambda List: (CONTAINER LOCATION)
Syntax: erase container location => new-instance status
Arguments:
  • CONTAINER, Container that shall be modified.
  • LOCATION, Designates place in returned instance that will be changed.

Examples:
(LET* ((TABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-FUNCTIONAL-HAMT-DICTIONARY #'SXHASH
                                                                       #'EQ))
       (NEXT-TABLE (CL-DATA-STRUCTURES:INSERT TABLE 'A 5)))
  (PROVE.TEST:DIAG "Running example for ERASE")
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'A) 5)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT TABLE 'A) 5 :TEST
                 (ALEXANDRIA:COMPOSE #'NULL #'EQL))
  (CL-DATA-STRUCTURES:MOD-BIND (ERASED-TABLE FOUND VALUE)
      (CL-DATA-STRUCTURES:ERASE NEXT-TABLE 'A)
    (PROVE.TEST:OK FOUND)
    (PROVE.TEST:IS VALUE 5)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT ERASED-TABLE 'A) NIL)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'A) 5)))

Description: Functional API: non-destructively remove an element at the LOCATION from the CONTAINER.
Returns:
  • Instance of the same type as CONTAINER, without value at the LOCATION.
  • Modification status object.

Notes: This is the functional counterpart to the ERASE! function.
ERASE-IF
Lambda List: (CONTAINER LOCATION CONDITION-FN)
Syntax: erase-if container location condition => new-instance status
Arguments:
  • CONTAINER, Container that shall be modified.
  • LOCATION, Designates place in returned instance that will be changed.
  • CONDITION, Function of two arguments, should return boolean.

Examples:
(LET* ((TABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-FUNCTIONAL-HAMT-DICTIONARY #'SXHASH
                                                                       #'EQ))
       (NEXT-TABLE
        (CL-DATA-STRUCTURES:INSERT (CL-DATA-STRUCTURES:INSERT TABLE 'A 5) 'B
                                   6)))
  (PROVE.TEST:DIAG "Running example for ERASE-IF")
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'A) 5)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT TABLE 'A) 5 :TEST
                 (ALEXANDRIA:COMPOSE #'NULL #'EQL))
  (CL-DATA-STRUCTURES:MOD-BIND (ERASED-TABLE FOUND VALUE)
      (CL-DATA-STRUCTURES:ERASE-IF NEXT-TABLE 'A
                                   (LAMBDA (LOCATION VALUE)
                                     (DECLARE (IGNORE LOCATION))
                                     (EVENP VALUE)))
    (PROVE.TEST:OK (NULL FOUND))
    (PROVE.TEST:IS VALUE NIL)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT ERASED-TABLE 'A) 5)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'A) 5))
  (CL-DATA-STRUCTURES:MOD-BIND (ERASED-TABLE FOUND VALUE)
      (CL-DATA-STRUCTURES:ERASE-IF NEXT-TABLE 'B
                                   (LAMBDA (LOCATION VALUE)
                                     (DECLARE (IGNORE LOCATION))
                                     (EVENP VALUE)))
    (PROVE.TEST:OK FOUND)
    (PROVE.TEST:IS VALUE 6)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT ERASED-TABLE 'B) NIL)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT NEXT-TABLE 'B) 6)))

Description: Functional API: non-destructively removes an element at LOCATION from the CONTAINER, but only when the CONDITION function returns true. The CONDITION will be called with location that matches according to comparsion function used to construct container, and with a value.
Returns:
  • Instance of the same type as CONTAINER, without value at LOCATION
  • Modification status object.

Notes: This is the functional counterpart to the ERASE-IF! function.
PUT
Lambda List: (CONTAINER ITEM)
Arguments:
  • CONTAINER, A subclass of fundamental-container
  • ITEM, Object that should be added into CONTAINER

Description: Functional API. Inserts new the ITEM into a new version of the CONTAINER. Relevant to sets and sequences.
Returns: Modified container.
Notes: This is the functional counterpart to the PUT! function.
TAKE-OUT
Lambda List: (CONTAINER)
Arguments:
  • CONTAINER, Container that is about to be modified.

Description: Functional API. Removes one element from the CONTAINER. Relevant to sequences.
Returns:
  • New version of the container, without one element.
  • Modification status.

Notes: This is the functional counterpart to the TAKE-OUT! function.
Mutable modification API
Symbols in the package CL-DATA-STRUCTURES:
(SETF AT)
Lambda List: (NEW-VALUE CONTAINER LOCATION &REST MORE-LOCATIONS)
Arguments:
  • NEW-VALUE, Value that shall be inserted into the container.
  • CONTAINER, Container that shall be modified.
  • LOCATION, Location where container shall be modified.

Description: Destructively insert/replace a element in the CONTAINER at LOCATION with the NEW-VALUE.
Returns:
  • NEW-VALUE
  • modification-status object as second value.

Notes: This is the destructive counterpart to the INSERT function.
ADD!
Lambda List: (CONTAINER LOCATION NEW-VALUE)
Syntax: add! container location new-value => same-container status
Arguments:
  • CONTAINER, Instance that we intend to destructivly modify
  • LOCATION, Place in the CONTAINER that we intend to change
  • NEW-VALUE, Value that we intend to add into CONTAINER

Description: Destructively add the NEW-VALUE into the CONTAINER at the LOCATION. Will not replace a value at LOCATION if it was already occupied.
Returns:
  • CONTAINER
  • Modification status object

Side Effects: If item was not found in the CONTAINER, destructivly transform CONTAINER.
Notes: This is the destructive counterpart to the ADD function.
UPDATE!
Lambda List: (CONTAINER LOCATION NEW-VALUE)
Syntax: (update! container location new-value) -> same-container status
Arguments:
  • container, Container that shall be modified.
  • location, Location in the container that we want to transform.

Description: Mutable API: If the LOCATION is taken in the CONTAINER, destructivly update it with the NEW-VALUE
Returns:
  • CONTAINER
  • Modification status object

Notes: This is the destructive counterpart to the UPDATE function.
UPDATE-IF!
Lambda List: (CONTAINER LOCATION NEW-VALUE CONDITION-FN)
Syntax: update-if! container location new-value CONDITION-FN => container status
Arguments:
  • CONTAINER, The instance that shall be transformed.
  • LOCATION, The location in the container that we want to transform.
  • CONDITION-FN, Function used to check if update should happen.

Description: Mutable API: if there is a value at the LOCATION in the CONTAINER and the supplied CONDITION-FN returns true when called with the present value, set the LOCATION to the new value.
Returns:
  • CONTAINER
  • Modification status object

Notes: This is the destructive counterpart to the UPDATE-IF function.
ERASE!
Lambda List: (CONTAINER LOCATION)
Syntax: erase! container location => same-instance status
Arguments:
  • container, Instance that is intended to be destructivly modified.
  • location, Location in the container that we want to modify by removing value.

Description: Mutable API: destructively remove a element at the LOCATION from the CONTAINER.
Returns:
  • CONTAINER
  • Modification status object

Side Effects: If erase took place, destructivly transform CONTAINER.
Notes: This is the destrucive counterpart to the ERASE function.
ERASE-IF!
Lambda List: (CONTAINER LOCATION CONDITION-FN)
Syntax: erase-if! container location condition => same-instance status
Arguments:
  • CONTAINER, Container that shall be modified.
  • LOCATION, Designates place in returned instance that will be changed.
  • CONDITION, Function of two arguments, should return boolean.

Examples:
(LET* ((TABLE
        (CL-DATA-STRUCTURES.DICTS.HAMT:MAKE-MUTABLE-HAMT-DICTIONARY #'SXHASH
                                                                    #'EQ)))
  (SETF (CL-DATA-STRUCTURES:AT TABLE 'A) 5
        (CL-DATA-STRUCTURES:AT TABLE 'B) 6)
  (PROVE.TEST:DIAG "Running example for ERASE-IF!")
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT TABLE 'A) 5)
  (CL-DATA-STRUCTURES:MOD-BIND (ERASED-TABLE FOUND VALUE)
      (CL-DATA-STRUCTURES:ERASE-IF! TABLE 'A
                                    (LAMBDA (LOCATION VALUE)
                                      (DECLARE (IGNORE LOCATION))
                                      (EVENP VALUE)))
    (PROVE.TEST:OK (NULL FOUND))
    (PROVE.TEST:IS VALUE NIL)
    (PROVE.TEST:IS ERASED-TABLE TABLE)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT ERASED-TABLE 'A) 5))
  (CL-DATA-STRUCTURES:MOD-BIND (ERASED-TABLE FOUND VALUE)
      (CL-DATA-STRUCTURES:ERASE-IF! TABLE 'B
                                    (LAMBDA (LOCATION VALUE)
                                      (DECLARE (IGNORE LOCATION))
                                      (EVENP VALUE)))
    (PROVE.TEST:OK FOUND)
    (PROVE.TEST:IS VALUE 6)
    (PROVE.TEST:IS ERASED-TABLE TABLE)
    (PROVE.TEST:IS (CL-DATA-STRUCTURES:AT ERASED-TABLE 'B) NIL)))

Description: Functional API: destructively remove element at LOCATION from the CONTAINER, only when CONDITION function returns true. CONDITION will be called with location that matches according to comparsion function, and with value.
Returns:
  • CONTAINER
  • Modification status object.

Notes: This is the destructive counterpart to the ERASE-IF function.
PUT!
Lambda List: (CONTAINER ITEM)
Arguments:
  • CONTAINER, A subclass of fundamental-container
  • ITEM, Object that should be added into CONTAINER

Description: Destructive API. Inserts new the ITEM into the CONTAINER. Relevant to sets and sequences.
Returns: CONTAINER
Notes: This is the destructive counterpart to the PUT function.
TAKE-OUT!
Lambda List: (CONTAINER)
Arguments:
  • CONTAINER, Container that is about to be modified

Description: Destructive API: removes one element from the CONTAINER. Relevant to sequences.
Returns:
  • CONTAINER
  • Modification status.

Notes: This is the destructive counterpart to the TAKE-OUT function.
Variants API
Symbols in the package CL-DATA-STRUCTURES:
BECOME-FUNCTIONAL
Lambda List: (CONTAINER)
Syntax: become-functional container => functional-container
Arguments:
  • container, Container that we want to transform into functional container.

Description: Transforms CONTAINER into functional variant.
Returns: A instance implementing functional API. Content of returned instance is identical to the content of input CONTAINER.
Side Effects: May vary, depending on type of the CONTAINER. Also, some (or all) parts of a internal representation can be shared between both the CONTAINER and a returned instance. Side effects from the mutable CONTAINER may leak into a returned instance.
See also:
  • BECOME-TRANSACTIONAL
  • BECOME-MUTABLE

Notes:
  • Side effects from the destructive operations on the CONTAINER may leak into returned instance.
  • Not all containers implement this function.

BECOME-MUTABLE
Lambda List: (CONTAINER)
Syntax: become-mutable container => mutable-container
Arguments:
  • CONTAINER, Container that we want to transform into mutable container.

Description: Transforms the CONTAINER into a mutable variant.
Returns: An instance implementing mutable API. The content of the returned instance is identical to the content of the input CONTAINER.
Side Effects: May vary, depending on type of the CONTAINER. Also, some (or all) parts of a internal representation can be shared between both the CONTAINER and a returned instance. Side effects from the mutable CONTAINER may leak into the returned instance.
See also:
  • BECOME-TRANSACTIONAL
  • BECOME-FUNCTIONAL

Notes:
  • Side effects from destructive operations on CONTAINER may leak into returned instance.
  • Not all containers implement this function.

BECOME-TRANSACTIONAL
Lambda List: (CONTAINER)
Syntax: become-transactional container => transactional-container
Arguments:
  • CONTAINER, Container that we want to transform into the transactional container.

Description: Transforms CONTAINER into transactional variant.
Returns: instance implementing mutable API. Content of returned instance is identical to the content of the input CONTAINER.
Side Effects: May vary, depending on type of the CONTAINER. Also, some (or all) parts of internal representation can be shared between both the CONTAINER and a returned instance. Side effects from the mutable CONTAINER may leak into the returned instance.
See also:
  • BECOME-FUNCTIONAL
  • BECOME-MUTABLE
  • REPLICA

Notes:
  • Side effects from destructive operations on CONTAINER may leak into returned instance.
  • Not all containers implement this function.

REPLICA
Lambda List: (CONTAINER &OPTIONAL ISOLATE)
Syntax: replica transactioanl-container-container boolean => transactional-container
Arguments:
  • CONTAINER, Container that will be replicated.
  • ISOLATE, Should changes in the CONTAINER be prevented from leaking into result instances

Description: Creates a new instance of transactional container from the existing transactional CONTAINER. Therefore: behaves like BECOME-TRANSACTIONAL, but is implemented only for the transactional containers. Furthermore: when ISOLATE is true, prevents side effects from the original CONTAINER to leak into the new container.
Returns: instance implementing mutable API. Content of returned instance is identical to the content of the input CONTAINER.
Side Effects: May very, depending on the type of the CONTAINER.
See also:
  • BECOME-TRANSACTIONAL

Notes:
  • (replica container t) can be understood as a creation of two new transactional instances and discarding the original CONTAINER.
  • Because of the above, total cost of creating isolated replica and mutating both the original and the replica can eventually outgrow cost of simply creating the clone.
  • It is adviced to use replica for the sake explicitly when working with transactional instances.

BECOME-LAZY
Lambda List: (CONTAINER)
Syntax: become-lazy container => lazy-container
Arguments:
  • CONTAINER, Container that we want to transform into an lazy container.

Description: Transforms CONTAINER into lazy variant.
Returns: instance implementing functional, lazy API. Content of returned instance is identical to the content of input CONTAINER.
Side Effects: May vary, depending on type of the CONTAINER. Also, some (or all) parts of internal representation can be shared between both the CONTAINER and a returned instance. Side effects from the mutable CONTAINER may leak into the returned instance.
Notes:
  • Side effects from destructive operations on CONTAINER may leak into returned instance.
  • All containers that implement become-transactional, also implement become-lazy

Macros

Symbols in the package CL-DATA-STRUCTURES:
XPR
Lambda List: (ARGUMENTS &BODY BODY)
Syntax: xpr arguments => expression
Arguments:
  • ARGUMENTS, Lambda list of the expression, in the form of the plist
  • BODY, Body of the expression.

Examples:
(LET ((IOTA
       (CL-DATA-STRUCTURES:XPR (:I 0)
         (WHEN (< I 5) (CL-DATA-STRUCTURES:SEND-RECUR I :I (1+ I))))))
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:CONSUME-FRONT IOTA) 0)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:CONSUME-FRONT IOTA) 1)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:CONSUME-FRONT IOTA) 2)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:CONSUME-FRONT IOTA) 3)
  (PROVE.TEST:IS (CL-DATA-STRUCTURES:CONSUME-FRONT IOTA) 4))

Description: Constructs expression. Expression is a forward range build around the function closed over the state. State can be modified with SEND-RECUR and RECUR forms. SEND-RECUR modifies state and returns the value. RECUR modifies state but does not return the value.
Notes: Objects used as part of the state should be immutable to support RESET! and CLONE operations properly.
MOD-BIND
Lambda List: ((FIRST &OPTIONAL FOUND VALUE CHANGED) FORM &BODY BODY)
Syntax: mod-bind (first &optional found value) values-form body
Arguments:
  • FIRST, Symbol, will be bound to the first value returned by values-form.
  • FOUND, Symbol, this macro will construct symbol-macrolet that will expand to the call (found status)
  • VALUE, Symbol, this macro will construct symbol-macrolet that will expand to the call (value status)
  • CHANGED, Symbol, this macro will construct symbol-macrolet that will expand to the call (changed status)

Description: This macro attempts to mimic multiple-value-bind syntax for modification operations performed on the containers. All of those operations will return a secondary object representing operation status that shall be bound in the lexical environment. Next, symbol-macrolets will be established, inlining found, value and changed function calls on the operation status (like with-accessors).

Classes

Symbols in the package CL-DATA-STRUCTURES:
FUNDAMENTAL-CONTAINER
Inheritance
Description: The root class of the containers.
FUNDAMENTAL-MODIFICATION-OPERATION-STATUS
Inheritance
Description: The base class of all fundamental modification status classes.
FUNCTIONAL
Inheritance
Description: Object implements functional api.
MUTABLE
Inheritance
Description: Object implements mutable api.
TRANSACTIONAL
Inheritance
Description: Object implements mutable api in a transactional way.
LAZY
Inheritance
Description: Functional object, with lazy implementation.

Conditions

Cl-data-structures tries to signal only the well structured errors that are possible to interpret. In order to achieve this, the hierarchy of condition classes is introduced. Below there is documentation explaining it.

Symbols in the package CL-DATA-STRUCTURES:
TEXTUAL-ERROR
Inheritance
Description: Error with a human readable text description.
INVALID-ARGUMENT
Inheritance
Description: Error signaled if (for whatever reason) passed argument is invalid.
INITIALIZATION-ERROR
Inheritance
Description: Error signaled when the container can't be initialized.
UNEXPECTED-ARGUMENT
Inheritance
Description: Error signaled when passed argument was unexpected.
OUT-OF-BOUNDS
Inheritance
Description: Error signaled when a some value is out of the expected bounds.
ARGUMENT-VALUE-OUT-OF-BOUNDS
Inheritance
Description: Error signaled when passed the argument exceeds allowed bounds
INITIALIZATION-OUT-OF-BOUNDS
Inheritance
Description: Error signaled when the container can't be initialized with a value because it exceeds bounds.
NOT-IMPLEMENTED
Inheritance
Description: Error signaled when unimlemented functionality is accessed.