The champ-lite Reference Manual

This is the champ-lite Reference Manual, version 1.0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Fri May 15 11:40:21 2026 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 champ-lite

A lightweight implementation of persistent functional maps and iteration-safe mutable tables using Michael Steindorfer’s CHAMP data structure.

Author

Scott L. Burson

License

Unlicense

Version

1.0.1

Source

champ-lite.asd.

Child Component

src (module).


3 Modules

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


3.1 champ-lite/src

Source

champ-lite.asd.

Parent Component

champ-lite (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 champ-lite/champ-lite.asd

Source

champ-lite.asd.

Parent Component

champ-lite (system).

ASDF Systems

champ-lite.


4.1.2 champ-lite/src/defs.lisp

Source

champ-lite.asd.

Parent Component

src (module).

Packages

com.sympoiesis.champ.


4.1.3 champ-lite/src/macros.lisp

Dependency

defs.lisp (file).

Source

champ-lite.asd.

Parent Component

src (module).

Public Interface

do-map (macro).

Internals

4.1.4 champ-lite/src/champ.lisp

Dependency

macros.lisp (file).

Source

champ-lite.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.5 champ-lite/src/tests.lisp

Dependency

champ.lisp (file).

Source

champ-lite.asd.

Parent Component

src (module).

Internals

5 Packages

Packages are listed by definition order.


5.1 com.sympoiesis.champ

Source

defs.lisp.

Nickname

champ

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Macros

Macro: do-map ((key-var value-var map &optional value) &body body)
Package

com.sympoiesis.champ.

Source

macros.lisp.


6.1.2 Ordinary functions

Function: make-map-iterator (map)

Returns an iterator for ‘map’ implemented as a closure. Invoking it on ‘:get’, if the iterator has pairs left, returns the next pair as two values, key and value. Invoking it on ‘:done?’ will return true iff the iterator is exhausted; on ‘:more?’, true iff the iterator has pairs left.

Package

com.sympoiesis.champ.

Source

champ.lisp.


6.1.3 Standalone methods

Method: print-object ((object champ-map) stream)
Source

champ.lisp.

Method: print-object ((object champ-table) stream)
Source

champ.lisp.


6.2 Internals


6.2.1 Constants

Constant: hash-bits-per-level
Package

com.sympoiesis.champ.

Source

champ.lisp.

Constant: hash-level-mask
Package

com.sympoiesis.champ.

Source

champ.lisp.

Constant: map-node-header-size
Package

com.sympoiesis.champ.

Source

champ.lisp.

Constant: node-radix
Package

com.sympoiesis.champ.

Source

champ.lisp.


6.2.2 Special variables

Special Variable: *vector-of-symbols*
Package

com.sympoiesis.champ.

Source

tests.lisp.


6.2.3 Macros

Macro: do-bit-indices ((idx-var val &optional result) &body body)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: do-table ((key-var value-var table &optional value) &body body)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: hash-mix (&rest args)

Returns the "mix" of the values, where "mix" is a commutative and associative operation with an inverse. All values MUST be fixnums; the result is a fixnum.

Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: hash-mixf (place &rest args)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: hash-unmix (hash &rest to-unmix)

Returns the result of "unmixing" each of ‘to-unmix’ from ‘hash’. All values MUST be fixnums; the result is a fixnum.

Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: hash-unmixf (place hash &rest to-unmix)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: hush (&body body)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: logandc2f (place arg-2)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: logiorf (place &rest args)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Macro: with-lock ((lock &key wait?) &body body)
Package

com.sympoiesis.champ.

Source

macros.lisp.


6.2.4 Ordinary functions

Function: 1-bits-below (idx mask)

The number of 1 bits in ‘mask’ at bit positions (strictly) less than ‘idx’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: bit-indices (mask)

A list of the indices of the 1 bits of ‘mask’, in ascending order.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Reader: champ-map-contents (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

contents.

Reader: champ-map-hash-fn (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

hash-fn.

Function: champ-map-p (object)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Reader: champ-map-test (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

test.

Reader: champ-table-contents (instance)
Writer: (setf champ-table-contents) (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

contents.

Reader: champ-table-hash-fn (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

hash-fn.

Reader: champ-table-lock (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

lock.

Function: champ-table-p (object)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Reader: champ-table-test (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Target Slot

test.

Function: copy-champ-map (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: copy-champ-table (instance)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: copy-map-node (sequence)

Return a copy of SEQUENCE which is EQUAL to SEQUENCE but not EQ.

Package

com.sympoiesis.champ.

Alias for

copy-seq.

Function: int-torture-hash (x)
Package

com.sympoiesis.champ.

Source

tests.lisp.

Function: make-lock (&optional name)
Package

com.sympoiesis.champ.

Source

macros.lisp.

Function: make-map (hash-fn test)

Creates a persistent functional map with the given ‘hash-fn’ and ‘test’. The ‘hash-fn’ must return fixnums; negative fixnums are okay. The ‘test’ is called on two key values, and returns true iff they are to be considered equal; it must be an equivalence relation. If two keys are equal, ‘hash-fn’ must return the same value for them.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: make-map-node (&key entry-mask subnode-mask size)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: make-map-tree-iterator-internal (tree)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: make-table (hash-fn test &key synchronized?)

Creates a mutable CHAMP table. If ‘synchronized?‘ is true, writes (via ‘table-put’) will be locked, preventing loss of data from concurrent writes. The ‘hash-fn’ must return fixnums; negative fixnums are okay. The ‘test’ is called on two key values, and returns true iff they are to be considered equal; it must be an equivalence relation. If two keys are equal, ‘hash-fn’ must return the same value for them.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: make-table-iterator (table)

Returns an iterator for ‘table’ implemented as a closure. Invoking it on ‘:get’, if the iterator has pairs left, returns the next pair as two values, key and value. Invoking it on ‘:done?’ will return true iff the iterator is exhausted; on ‘:more?’, true iff the iterator has pairs left. Once the iterator is created, subsequent ‘table-put’ operations will have no effect on its behavior.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-empty? (map)

Returns true iff ‘map’ has no entries.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-less (map key)

Returns a new map which has all the entries of ‘map’ except the one for ‘key’, if any.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-lookup (map key)

If ‘map’ has an entry for ‘key’, returns the associated value and a true second value; otherwise returns ‘nil’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-entry-key (node ientry)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-entry-mask (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: (setf map-node-entry-mask) (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-entry-value (node ientry)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-size (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: (setf map-node-size) (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-subnode (node isubnode)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-node-subnode-mask (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: (setf map-node-subnode-mask) (structure)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-size (map)

Returns the number of entries in ‘map’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-iterator-canonicalize (iter)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-iterator-done? (iter)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-iterator-get (iter)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-less (tree key hash-fn test)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-lookup (tree key hash-fn test)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-size (tree)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-verify (tree key-hash-fn)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-tree-with (tree key value hash-fn test)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: map-verify (map)
Package

com.sympoiesis.champ.

Source

tests.lisp.

Function: map-with (map key value)

Returns a new map which has all the entries of ‘map’, except that an entry has been added or updated associating ‘key’ with ‘value’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: print-map (map stream level)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: print-table (table stream level)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: raw-make-champ-map (contents hash-fn test)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: raw-make-champ-table (contents hash-fn test lock)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-empty? (table)

Returns true iff ‘table’ has no entries.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-get (table key)

If ‘map’ has an entry for ‘key’, returns the associated value and a true second value; otherwise returns ‘nil’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-put (table key value)

Adds an entry to ‘table’ or updates an existing entry, so that ‘key’ maps to ‘value’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-remove (table key)

Removes any entry for ‘key’ from ‘table’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-size (table)

The number of entries in ‘table’.

Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: table-verify (table)
Package

com.sympoiesis.champ.

Source

tests.lisp.

Function: test-champ-maps (n-iterations)
Package

com.sympoiesis.champ.

Source

tests.lisp.

Function: vector-ins-2-rem-1 (vec ins-idx ins-0 ins-1 rem-idx)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: vector-insert-2 (vec idx ins-0 ins-1)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: vector-rem-2-ins-1 (vec rem-idx ins-idx ins-val)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: vector-remove-2 (vec idx)
Package

com.sympoiesis.champ.

Source

champ.lisp.

Function: vector-update (vec idx val)

Returns a new vector like ‘vec’ but with ‘val’ at ‘idx’.

Package

com.sympoiesis.champ.

Source

champ.lisp.


6.2.5 Structures

Structure: champ-map
Package

com.sympoiesis.champ.

Source

champ.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: contents
Type

com.sympoiesis.champ::map-tree

Readers

champ-map-contents.

Writers

This slot is read-only.

Slot: hash-fn
Type

function

Readers

champ-map-hash-fn.

Writers

This slot is read-only.

Slot: test
Type

function

Readers

champ-map-test.

Writers

This slot is read-only.

Structure: champ-table
Package

com.sympoiesis.champ.

Source

champ.lisp.

Direct superclasses

structure-object.

Direct methods

print-object.

Direct slots
Slot: contents
Type

com.sympoiesis.champ::map-tree

Readers

champ-table-contents.

Writers

(setf champ-table-contents).

Slot: hash-fn
Type

function

Readers

champ-table-hash-fn.

Writers

This slot is read-only.

Slot: test
Type

function

Readers

champ-table-test.

Writers

This slot is read-only.

Slot: lock
Readers

champ-table-lock.

Writers

This slot is read-only.


6.2.6 Types

Type: bit-index ()
Package

com.sympoiesis.champ.

Source

champ.lisp.

Type: map-tree ()
Package

com.sympoiesis.champ.

Source

champ.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (   1  
B   C   D   F   H   I   L   M   P   R   T   V   W  
Index Entry  Section

(
(setf champ-table-contents): Private ordinary functions
(setf map-node-entry-mask): Private ordinary functions
(setf map-node-size): Private ordinary functions
(setf map-node-subnode-mask): Private ordinary functions

1
1-bits-below: Private ordinary functions

B
bit-indices: Private ordinary functions

C
champ-map-contents: Private ordinary functions
champ-map-hash-fn: Private ordinary functions
champ-map-p: Private ordinary functions
champ-map-test: Private ordinary functions
champ-table-contents: Private ordinary functions
champ-table-hash-fn: Private ordinary functions
champ-table-lock: Private ordinary functions
champ-table-p: Private ordinary functions
champ-table-test: Private ordinary functions
copy-champ-map: Private ordinary functions
copy-champ-table: Private ordinary functions
copy-map-node: Private ordinary functions

D
do-bit-indices: Private macros
do-map: Public macros
do-table: Private macros

F
Function, (setf champ-table-contents): Private ordinary functions
Function, (setf map-node-entry-mask): Private ordinary functions
Function, (setf map-node-size): Private ordinary functions
Function, (setf map-node-subnode-mask): Private ordinary functions
Function, 1-bits-below: Private ordinary functions
Function, bit-indices: Private ordinary functions
Function, champ-map-contents: Private ordinary functions
Function, champ-map-hash-fn: Private ordinary functions
Function, champ-map-p: Private ordinary functions
Function, champ-map-test: Private ordinary functions
Function, champ-table-contents: Private ordinary functions
Function, champ-table-hash-fn: Private ordinary functions
Function, champ-table-lock: Private ordinary functions
Function, champ-table-p: Private ordinary functions
Function, champ-table-test: Private ordinary functions
Function, copy-champ-map: Private ordinary functions
Function, copy-champ-table: Private ordinary functions
Function, copy-map-node: Private ordinary functions
Function, int-torture-hash: Private ordinary functions
Function, make-lock: Private ordinary functions
Function, make-map: Private ordinary functions
Function, make-map-iterator: Public ordinary functions
Function, make-map-node: Private ordinary functions
Function, make-map-tree-iterator-internal: Private ordinary functions
Function, make-table: Private ordinary functions
Function, make-table-iterator: Private ordinary functions
Function, map-empty?: Private ordinary functions
Function, map-less: Private ordinary functions
Function, map-lookup: Private ordinary functions
Function, map-node-entry-key: Private ordinary functions
Function, map-node-entry-mask: Private ordinary functions
Function, map-node-entry-value: Private ordinary functions
Function, map-node-size: Private ordinary functions
Function, map-node-subnode: Private ordinary functions
Function, map-node-subnode-mask: Private ordinary functions
Function, map-size: Private ordinary functions
Function, map-tree-iterator-canonicalize: Private ordinary functions
Function, map-tree-iterator-done?: Private ordinary functions
Function, map-tree-iterator-get: Private ordinary functions
Function, map-tree-less: Private ordinary functions
Function, map-tree-lookup: Private ordinary functions
Function, map-tree-size: Private ordinary functions
Function, map-tree-verify: Private ordinary functions
Function, map-tree-with: Private ordinary functions
Function, map-verify: Private ordinary functions
Function, map-with: Private ordinary functions
Function, print-map: Private ordinary functions
Function, print-table: Private ordinary functions
Function, raw-make-champ-map: Private ordinary functions
Function, raw-make-champ-table: Private ordinary functions
Function, table-empty?: Private ordinary functions
Function, table-get: Private ordinary functions
Function, table-put: Private ordinary functions
Function, table-remove: Private ordinary functions
Function, table-size: Private ordinary functions
Function, table-verify: Private ordinary functions
Function, test-champ-maps: Private ordinary functions
Function, vector-ins-2-rem-1: Private ordinary functions
Function, vector-insert-2: Private ordinary functions
Function, vector-rem-2-ins-1: Private ordinary functions
Function, vector-remove-2: Private ordinary functions
Function, vector-update: Private ordinary functions

H
hash-mix: Private macros
hash-mixf: Private macros
hash-unmix: Private macros
hash-unmixf: Private macros
hush: Private macros

I
int-torture-hash: Private ordinary functions

L
logandc2f: Private macros
logiorf: Private macros

M
Macro, do-bit-indices: Private macros
Macro, do-map: Public macros
Macro, do-table: Private macros
Macro, hash-mix: Private macros
Macro, hash-mixf: Private macros
Macro, hash-unmix: Private macros
Macro, hash-unmixf: Private macros
Macro, hush: Private macros
Macro, logandc2f: Private macros
Macro, logiorf: Private macros
Macro, with-lock: Private macros
make-lock: Private ordinary functions
make-map: Private ordinary functions
make-map-iterator: Public ordinary functions
make-map-node: Private ordinary functions
make-map-tree-iterator-internal: Private ordinary functions
make-table: Private ordinary functions
make-table-iterator: Private ordinary functions
map-empty?: Private ordinary functions
map-less: Private ordinary functions
map-lookup: Private ordinary functions
map-node-entry-key: Private ordinary functions
map-node-entry-mask: Private ordinary functions
map-node-entry-value: Private ordinary functions
map-node-size: Private ordinary functions
map-node-subnode: Private ordinary functions
map-node-subnode-mask: Private ordinary functions
map-size: Private ordinary functions
map-tree-iterator-canonicalize: Private ordinary functions
map-tree-iterator-done?: Private ordinary functions
map-tree-iterator-get: Private ordinary functions
map-tree-less: Private ordinary functions
map-tree-lookup: Private ordinary functions
map-tree-size: Private ordinary functions
map-tree-verify: Private ordinary functions
map-tree-with: Private ordinary functions
map-verify: Private ordinary functions
map-with: Private ordinary functions
Method, print-object: Public standalone methods
Method, print-object: Public standalone methods

P
print-map: Private ordinary functions
print-object: Public standalone methods
print-object: Public standalone methods
print-table: Private ordinary functions

R
raw-make-champ-map: Private ordinary functions
raw-make-champ-table: Private ordinary functions

T
table-empty?: Private ordinary functions
table-get: Private ordinary functions
table-put: Private ordinary functions
table-remove: Private ordinary functions
table-size: Private ordinary functions
table-verify: Private ordinary functions
test-champ-maps: Private ordinary functions

V
vector-ins-2-rem-1: Private ordinary functions
vector-insert-2: Private ordinary functions
vector-rem-2-ins-1: Private ordinary functions
vector-remove-2: Private ordinary functions
vector-update: Private ordinary functions

W
with-lock: Private macros