Node

Class Node.

class Node

Represents a node in a B-tree data structure, supporting internal and leaf nodes, file-backed storage, and caching for efficient access. Provides methods for reading, writing, splitting, and managing child nodes and records.

Constants

NODE_PTR_SIZE

public const NODE_PTR_SIZE = 4

Properties

ptr

Pointer to the node's position in the file.

public int $ptr

Type: int

length

Length of the node data in bytes.

public int $length

Type: int

slotSize

Size of each node slot in bytes.

public int $slotSize

Type: int

keySize

Maximum size of each key in bytes.

public int $keySize

Type: int

childSize

Size of each child node entry in bytes.

public int $childSize

Type: int

cacheSize

Maximum number of records to cache for this node.

public int $cacheSize = 128

Type: int

children

public array $children

Type: array

nodeType

Type of the node (internal or leaf).

public NodeType $nodeType

Type: Hazaar\Util\BTree\NodeType

file

public mixed $file

Type: mixed

nodeCache

Cache for nodes to avoid excessive file reads.

private array $nodeCache

Type: array

recordCache

Cache for records to avoid multiple reads from the file.

private array $recordCache

Type: array

This is a static property to allow sharing across instances.

parentNode

public self $parentNode

Type: self

Methods

__construct

public __construct(mixed $file, ?int $ptr, int $slotSize = 16, int $keySize = 32): void

Parameters

Parameter	Type	Description
$file	mixed
$ptr	int
$slotSize	int
$keySize	int

resetCache

Resets the static caches for nodes and records.

public resetCache(): void

Returns: void

This method clears both the node cache and the record cache by setting their respective static arrays to empty. Use this to ensure that cached data is discarded and fresh data will be loaded on subsequent accesses.

create

Create a new Node instance with initialized children slots.

public create(mixed $file, NodeType $type = 'NodeType::INTERNAL', int $slotSize = 16, int $keySize = 32): Node

Returns: Hazaar\Util\BTree\Node

Parameters

Parameter	Type	Description
$file	mixed	The file resource where the BTree is stored
$type	Hazaar\Util\BTree\NodeType
$slotSize	int
$keySize	int

read

Reads the node data from the file at the specified pointer.

public read(?int $ptr): bool

Returns: bool

Parameters

Parameter	Type	Description
$ptr	int	The pointer to the node in the file. If null, uses the current node's pointer.

write

Writes the node data to the file at the specified pointer.

public write(?int $ptr): bool

Returns: bool

Parameters

Parameter	Type	Description
$ptr	int	The pointer to write the node in the file. If null, writes to the end of the file.

add

Adds a new key-value pair to the B-tree node.

public add(string $key, mixed $value): bool

Returns: bool

This method creates a new leaf node, sets the provided key and value, and adds the node as a child to the current node. Only internal nodes can have children; attempting to add a record to a non-leaf node will throw a RuntimeException.

Parameters

Parameter	Type	Description
$key	string	the key to add to the node
$value	mixed	the value associated with the key

set

Sets the value for the specified key in the node.

public set(string $key, mixed $value): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to set
$value	mixed	the value to associate with the key

get

Gets the value for the specified key from the node.

public get(string $key): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$key	string	the key to get

has

Checks if the specified key exists in the node.

public has(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to check

remove

Removes the specified key from the node.

public remove(string $key): bool

Returns: bool

Parameters

Parameter	Type	Description
$key	string	the key to remove

addNode

Adds a child node to the current node.

public addNode(self $node): void

Returns: void

Parameters

Parameter	Type	Description
$node	self	the node to add as a child

addRecord

Adds a record to the current node.

public addRecord(Record $record): bool

Returns: bool

Parameters

Parameter	Type	Description
$record	Hazaar\Util\BTree\Record	the record to add

verifyTree

Verifies the integrity of the B-Tree from this node downwards.

public verifyTree(?Node $node, ?string $minKey, ?string $maxKey): bool

Returns: bool

Parameters

Parameter	Type	Description
$node	Hazaar\Util\BTree\Node	The node to verify. If null, starts from the current node.
$minKey	string	the minimum key value for the current node
$maxKey	string	the maximum key value for the current node

countRecords

Counts the total number of child nodes in the subtree rooted at this node.

public countRecords(): int

Returns: int

If the node is a leaf, returns the number of its children directly. Otherwise, recursively counts the children of all descendant nodes.

lookupLeafNode

Looks up the child node that should contain the specified key.

public lookupLeafNode(string $key): ?Node

Returns: Hazaar\Util\BTree\Node

Parameters

Parameter	Type	Description
$key	string	the key to look up

leaf

Returns a generator that yields all leaf nodes in the subtree rooted at this node.

public leaf(): \Generator

Returns: Generator

This method traverses the B-tree and yields each leaf node it encounters. It can be used to iterate over all leaf nodes in the B-tree.

split

Splits the current node into two nodes when it becomes full.

private split(): void

Returns: void

This method is called when the number of children in the current node exceeds its slot size. It divides the children into two halves, creates a new node to store the first half, and keeps the second half in the current node. The median key is then promoted to the parent node. If the current node is the root, a new root is created.

cacheNode

Caches the specified node.

private cacheNode(self $node): void

Returns: void

Parameters

Parameter	Type	Description
$node	self	the node to cache

---

Generated by Hazaar API Doc Generator on Fri, 04 Sep 2026 23:32:17 +0000