The cl-bplustree Reference Manual

Table of Contents

The cl-bplustree Reference Manual

This is the cl-bplustree Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:05:53 2020 GMT+0.

1 Introduction

h1. cl-bplustree - A Common Lisp implementation of an in-memory B+ tree.

*cl-bplustree* is an implementation of a in-memory B+ tree data structure in Common Lisp.

B+ trees main characteristics:

* All the data is in the leaves, internal nodes hold only keys used for traversal, pointers between the leaves are kept, so range-retrieval is easy and efficient.
* It is a generalization of a binary tree but instead of having only two pointers per node  to other nodes it can have many more (this is called the order of the tree) because of this characteristic the tree has typically a large fanout and a small depth.

For more information about B+ trees, check "Wikipedia":http://en.wikipedia.org/wiki/B%2B_tree.

h2. Dependencies

None.

h2. Usage

h3. @(bplustree-new (order &key key comparer))@

Creates a new empty B+ tre of the given order and returns it.

The _key_ parameter expects a function used to grab the key values (used for sorting) on whatever you are stuffing into the tree, the function will be called with one parameter (a record to be inserted into the tree for example) and it should return the value that will be used as a key. It defaults to @#'identity@.

The _comparer_ parameter expects a function used when comparing keys against each other in the tree operations. This function has to take two parameters (keys of records) and return a value depending on the following conditions:

@(< a b)@ -> -1
@(= a b)@ ->  0
@(> a b)@ ->  1

The meaning of this of course is given by your particular keys and your particular applications, for string keys for example @string<@, @string>@, etc., could be used.

This parameter defaults to a function that implements the explained logic but for numerical keys. If your keys are numeric, you don't need to supply a comparison function.

Example:

bc. (defparameter *my-tree* (bplustree-new 4 :key (lambda (r) (parse-integer r))))

h3. @(bplustree-empty-p (tree))@

Returns true if the tree is empty.

Example:

bc. (bplustree-empty-p *my-tree*) -> T

h3. @(bplustree-insert (record tree &optional key))@

Inserts the given _record_ into the given _tree_, if the given key already exists in the tree, the value is updated. Returns the tree but is not needed to capture it and assign it,this call is not destructive on the tree itself, althought its internal elements are changed by it.

If _key_ is omitted, calls the _key_ function passed to bplustree-new on _record_. If _key_ is included, uses that directly as the key. This enables using a B+ tree as a key/value store instead of a sorted set.

Examples:

bc. (bplustree-insert "100" *my-tree*)
(bplustree-insert "100" *my-tree* 100)

h3. @(bplustree-insert-many (tree &rest items))@

Inserts all the records given into the _tree_. Returns the tree.

Example:

bc. (bplustree-insert-many *my-tree* "5" "10" "-1" "1337" "212" "32" "311" "52")

h3. @(bplustree-search (key tree))@

Searches the value stored in the given _key_ in the given _tree_.

Example:

bc. (bplustree-search 311 *my-tree*) -> "311"

h3. @(bplustree-search-range (from to tree))@

Searches the tree for all the records that exists between the given _from_ and _to_ keys and returns them in a list.

Example:

bc. (bplustree-search-range 0 1000 *my-tree*) -> ("5" "10" "32" "52" "100" "212" "311")

h3. @(bplustree-search-next (key tree))@

Returns the first key after the passed _key_. Passing NIL for the _key_ returns the first key in the tree. The passed _key_ need not be in the tree. Still returns the first key greater than that, which IS in the tree. Returns NIL when passed the last key.

The record corresponding to the key is returned as a second value. If the key was cached, T is returned as a third value.

Examples:

bc. (bplustree-search-next nil *my-tree*) -> (values -1 "-1")
(bplustree-search-next -1 *my-tree*) -> (values 5 "-5" t)
(bplustree-search-next 1337 *my-tree*) -> nil

h3. @(bplustree-search-prev (key tree))@

Returns the key before the passed _key_. Passing NIL for the _key_ returns the last key in the tree. The passed _key_ need not be in the tree. Still returns the first key less than that, which IS in the tree. Returns NIL when passed the first key.

The record corresponding to the key is returned as a second value. If the key was cached, T is returned as a third value.

Examples:

bc. (bplustree-search-prev nil *my-tree*) -> (values 1337 "1337")
(bplustree-search-prev 1337 *my-tree*) -> (values 311 "311" t)
(bplustree-search-prev -1 *my-tree*) -> nil

h3. @(bplustree-delete (key tree))@

Deletes the record stored in the given _key_ in the _tree_. Returns the tree but is not needed to capture it and assign it, this call is not destructive on the tree itself, althought its internal elements are changed by it.

Example:

bc. (bplustree-delete 32 *my-tree*)
(bplustree-search-range 0 1000 *my-tree*)
("5" "10" "52" "100" "212" "311")


h3. @(bplustree-traverse (tree fn))@

Traverses all records in the tree in order from smallest to largest. As the B+ trees store data sorted already this operation is not expensive.

Example:

bc. (bplustree-traverse *my-tree* 'print)
"-1"
"5"
"10"
"32"
"52"
"212"
"311"
"1337"


h3. @(bplustree-traverse-with-keys (tree fn))@

Traverses all records in the tree in order from smallest to largest, calling fn on each with two args: the key and the value. As the B+ trees store data sorted already this operation is not expensive.

Example:

bc. (bplustree-traverse-with-keys *my-tree* (lambda (k v) (print (list k v))))
(-1 "-1") 
(5 "5") 
(10 "10") 
(32 "32") 
(52 "52") 
(212 "212") 
(311 "311") 
(1337 "1337")


h2. Final remarks

I hope this code is useful to you in any sense, either for learning, reading or maybe actual practical use, I will be very glad if you can even modify it to suit your needs. If you have suggestions please send them my way. Be sure to read *COPYING* file as well.

2 Systems

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

2.1 cl-bplustree

Author

Francisco Soto <ebobby@ebobby.org>

License

BSD

Description

In-memory B+ tree

Source

cl-bplustree.asd (file)

Components

• packages.lisp (file)
• bplustree.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 cl-bplustree.asd

Location

cl-bplustree.asd

Systems

cl-bplustree (system)

3.1.2 cl-bplustree/packages.lisp

Parent

cl-bplustree (system)

Location

packages.lisp

Packages

org.ebobby.bplustree

3.1.3 cl-bplustree/bplustree.lisp

Dependency

packages.lisp (file)

Parent

cl-bplustree (system)

Location

bplustree.lisp

Exported Definitions

• bplustree-delete (function)
• bplustree-empty-p (function)
• bplustree-insert (function)
• bplustree-insert-many (function)
• bplustree-new (function)
• bplustree-search (function)
• bplustree-search-next (function)
• bplustree-search-prev (function)
• bplustree-search-range (function)
• bplustree-traverse (function)
• bplustree-traverse-with-keys (function)

Internal Definitions

• bplustree (structure)
• bplustree-cache (function)
• (setf bplustree-cache) (function)
• bplustree-comparer (function)
• (setf bplustree-comparer) (function)
• bplustree-depth (function)
• (setf bplustree-depth) (function)
• bplustree-key (function)
• (setf bplustree-key) (function)
• bplustree-order (function)
• (setf bplustree-order) (function)
• bplustree-p (function)
• bplustree-root (function)
• (setf bplustree-root) (function)
• bplustree-traverse-node (function)
• bplustree-traverse-node-with-keys (function)
• build-node (function)
• build-node-collection-accesors (macro)
• build-node-collection-transfer (macro)
• copy-bplustree (function)
• copy-node (function)
• find-leaf-node (function)
• find-node (function)
• find-record (function)
• make-bplustree (function)
• make-node (function)
• move-records-left (function)
• move-records-right (function)
• node (structure)
• node-internal-p (function)
• node-key (function)
• node-key-record-set (function)
• node-key-set (function)
• node-key-transfer (function)
• node-keys (function)
• (setf node-keys) (function)
• node-kind (function)
• (setf node-kind) (function)
• node-min-size (function)
• node-next-node (function)
• (setf node-next-node) (function)
• node-num-keys (function)
• node-order (function)
• (setf node-order) (function)
• node-overflow-p (function)
• node-p (function)
• node-prev-node (function)
• (setf node-prev-node) (function)
• node-record (function)
• node-record-set (function)
• node-record-transfer (function)
• node-records (function)
• (setf node-records) (function)
• node-size (function)
• (setf node-size) (function)
• node-underflow-p (function)
• promote-first-key (function)
• search-node-keys (function)
• with-comparer-function (macro)

4 Packages

Packages are listed by definition order.

4.1 org.ebobby.bplustree

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions

• bplustree-delete (function)
• bplustree-empty-p (function)
• bplustree-insert (function)
• bplustree-insert-many (function)
• bplustree-new (function)
• bplustree-search (function)
• bplustree-search-next (function)
• bplustree-search-prev (function)
• bplustree-search-range (function)
• bplustree-traverse (function)
• bplustree-traverse-with-keys (function)

Internal Definitions

• bplustree (structure)
• bplustree-cache (function)
• (setf bplustree-cache) (function)
• bplustree-comparer (function)
• (setf bplustree-comparer) (function)
• bplustree-depth (function)
• (setf bplustree-depth) (function)
• bplustree-key (function)
• (setf bplustree-key) (function)
• bplustree-order (function)
• (setf bplustree-order) (function)
• bplustree-p (function)
• bplustree-root (function)
• (setf bplustree-root) (function)
• bplustree-traverse-node (function)
• bplustree-traverse-node-with-keys (function)
• build-node (function)
• build-node-collection-accesors (macro)
• build-node-collection-transfer (macro)
• copy-bplustree (function)
• copy-node (function)
• find-leaf-node (function)
• find-node (function)
• find-record (function)
• make-bplustree (function)
• make-node (function)
• move-records-left (function)
• move-records-right (function)
• node (structure)
• node-internal-p (function)
• node-key (function)
• node-key-record-set (function)
• node-key-set (function)
• node-key-transfer (function)
• node-keys (function)
• (setf node-keys) (function)
• node-kind (function)
• (setf node-kind) (function)
• node-min-size (function)
• node-next-node (function)
• (setf node-next-node) (function)
• node-num-keys (function)
• node-order (function)
• (setf node-order) (function)
• node-overflow-p (function)
• node-p (function)
• node-prev-node (function)
• (setf node-prev-node) (function)
• node-record (function)
• node-record-set (function)
• node-record-transfer (function)
• node-records (function)
• (setf node-records) (function)
• node-size (function)
• (setf node-size) (function)
• node-underflow-p (function)
• promote-first-key (function)
• search-node-keys (function)
• with-comparer-function (macro)

5 Definitions

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

5.1 Exported definitions

5.1.1 Functions

Function: bplustree-delete KEY TREE

Deletes a record from the given tree using the given key. Returns the tree with the record deleted.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-empty-p TREE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-insert RECORD TREE &optional KEY

Insert a record into the given tree using the given key. Returns the tree with the new record inserted. If ‘key‘ is included, uses that instead of calling the key function on ‘record‘.
This enabled using the tree as a key/value store instead of a sorted set.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-insert-many TREE &rest ITEMS

Insert as many records given into the tree. Returns the tree with the new records inserted.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-new ORDER &key KEY COMPARER

Makes a new B+ tree with the given order.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-search KEY TREE

Search for a record in the given tree using the given key.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-search-next KEY TREE

Return the first key in ‘tree‘ after the passed ‘key‘. Return the record as a second value.
If the third values is true, then the key and value were cached.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-search-prev KEY TREE

Return the key in ‘tree‘ before the passed ‘key‘.
Return the record as a second value.
If the third values is true, then the key and value were cached.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-search-range FROM TO TREE

Search and return a range of records in the given tree between the given keys.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-traverse TREE FN

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-traverse-with-keys TREE FN

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

5.2 Internal definitions

5.2.1 Macros

Macro: build-node-collection-accesors COLUMN

Generates the getter/setter functions for the btreeplus-node internal collections, keys and records.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Macro: build-node-collection-transfer COLUMN

Generates functions to transfer elements from a node into another node.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Macro: with-comparer-function TREE-NAME &body BODY

Wrap code inside a block that will create a dynamic variable that holds the comparer function.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

5.2.2 Functions

Function: bplustree-cache INSTANCE

Function: (setf bplustree-cache) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-comparer INSTANCE

Function: (setf bplustree-comparer) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-depth INSTANCE

Function: (setf bplustree-depth) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-key INSTANCE

Function: (setf bplustree-key) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-order INSTANCE

Function: (setf bplustree-order) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-p OBJECT

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-root INSTANCE

Function: (setf bplustree-root) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-traverse-node NODE FN

Call ‘fn‘ on each leaf record in ‘node‘.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: bplustree-traverse-node-with-keys NODE FN

Call ‘fn‘ with key and record for each leaf of ‘node‘.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: build-node ORDER &optional KIND

Makes an empty B+ tree node with the given order and the optional type (:leaf or :internal).

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: copy-bplustree INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: copy-node INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: find-leaf-node NODE KEY

Find the proper leaf node for the given key.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: find-node NODE KEY

Get the next node using the given key in the given node.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: find-record NODE KEY

Get the record with the given key in the given node, nil if none.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: make-bplustree &key (ROOT ROOT) (DEPTH DEPTH) (ORDER ORDER) (KEY KEY) (COMPARER COMPARER) (CACHE CACHE)

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: make-node &key (KIND KIND) (ORDER ORDER) (SIZE SIZE) (KEYS KEYS) (RECORDS RECORDS) (PREV-NODE PREV-NODE) (NEXT-NODE NEXT-NODE)

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: move-records-left NODE INDEX

Move the keys and records going left to right from given starting point.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: move-records-right NODE INDEX

Move the keys and records from the given starting point to the right.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-internal-p NODE

Is the node an internal node?

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-key NODE I

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-key-record-set NODE N KEY RECORD

Sets both the key and record at the given index to the given B+ node.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-key-set NODE I VALUE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-key-transfer SOURCE DESTINATION I-SOURCE I-DESTINATION &key SET-SOURCE-NIL

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-keys INSTANCE

Function: (setf node-keys) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-kind INSTANCE

Function: (setf node-kind) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-min-size NODE

Returns the minimum size a node can have (except root).

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-next-node INSTANCE

Function: (setf node-next-node) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-num-keys NODE

Get the number of keys based on the node size and node type.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-order INSTANCE

Function: (setf node-order) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-overflow-p NODE

Does the node have more records than it should?

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-p OBJECT

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-prev-node INSTANCE

Function: (setf node-prev-node) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-record NODE I

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-record-set NODE I VALUE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-record-transfer SOURCE DESTINATION I-SOURCE I-DESTINATION &key SET-SOURCE-NIL

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-records INSTANCE

Function: (setf node-records) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-size INSTANCE

Function: (setf node-size) VALUE INSTANCE

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: node-underflow-p NODE

Does the node have less records than it should?

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: promote-first-key NODE &key NO-SHIFT

Promotes the first key in the node, if its a leaf it simply returns it, if its an internal node it returns it but shifts the other keys to the left.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Function: search-node-keys NODE KEY &key RECORD-SEARCH

Search the given node keys vector using binary search.
Keys assumed to be sorted. Optional mix and max define the search space. The keyword record-search indicates if you are looking for a record or a node.

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

5.2.3 Structures

Structure: bplustree ()

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

print-object (method)

Direct slots

Slot: root

Readers

bplustree-root (function)

Writers

(setf bplustree-root) (function)

Slot: depth

Readers

bplustree-depth (function)

Writers

(setf bplustree-depth) (function)

Slot: order

Readers

bplustree-order (function)

Writers

(setf bplustree-order) (function)

Slot: key

Readers

bplustree-key (function)

Writers

(setf bplustree-key) (function)

Slot: comparer

Readers

bplustree-comparer (function)

Writers

(setf bplustree-comparer) (function)

Slot: cache

Readers

bplustree-cache (function)

Writers

(setf bplustree-cache) (function)

Structure: node ()

Package

org.ebobby.bplustree

Source

bplustree.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: kind

Readers

node-kind (function)

Writers

(setf node-kind) (function)

Slot: order

Readers

node-order (function)

Writers

(setf node-order) (function)

Slot: size

Readers

node-size (function)

Writers

(setf node-size) (function)

Slot: keys

Readers

node-keys (function)

Writers

(setf node-keys) (function)

Slot: records

Readers

node-records (function)

Writers

(setf node-records) (function)

Slot: prev-node

Readers

node-prev-node (function)

Writers

(setf node-prev-node) (function)

Slot: next-node

Readers

node-next-node (function)

Writers

(setf node-next-node) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types