Struct Node 

pub struct Node {
    pub type_name: String,
    pub id: String,
    pub fields: SmallVec<[Value; 4]>,
    pub children: Option<Box<BTreeMap<String, Vec<Node>>>>,
    pub child_count: u16,
}

A node in a matrix list.

Memory Layout Optimizations

Size reduced from ~120 bytes to ~80 bytes per node:

• fields: Uses SmallVec to inline up to 4 values (typical case)
• children: Lazy allocation - None until first child added (saves 24 bytes for leaf nodes)
• child_count: Uses u16 (2 bytes) with 0 = no hint (vs 16 bytes for Option<usize>)

For 10,000 nodes: ~400KB saved in struct overhead alone.

Fields

type_name: String

The type name (from schema). During parsing, this can be interned to share memory across all nodes of same type.

id: String

The node’s ID (first column value).

fields: SmallVec<[Value; 4]>

Field values (aligned with schema columns). SmallVec avoids heap allocation for ≤4 fields (common case: 90%+ of nodes).

children: Option<Box<BTreeMap<String, Vec<Node>>>>

Child nodes grouped by type (from NEST relationships). Lazy allocation - None until first child added. ~70% of nodes are leaves.

child_count: u16

Count of direct children (for LLM comprehension hints). 0 = no hint provided. Max 65,535 children (sufficient for all practical cases).

Implementations

impl Node

pub fn new( type_name: impl Into<String>, id: impl Into<String>, fields: Vec<Value>, ) -> Self

Create a new node.

pub fn get_field(&self, index: usize) -> Option<&Value>

Get a field value by column index.

pub fn add_child(&mut self, child_type: impl Into<String>, child: Node)

Add a child node. Uses lazy allocation - children BTreeMap is only created on first add.

pub fn set_child_count(&mut self, count: usize)

Set the child count hint (for LLM comprehension). Saturates at u16::MAX (65,535) if count exceeds.

pub fn get_child_count(&self) -> Option<usize>

Get the child count hint, if provided.

pub fn with_child_count( type_name: impl Into<String>, id: impl Into<String>, fields: Vec<Value>, child_count: usize, ) -> Self

Create a new node with a child count hint.

Arguments

• type_name: The type name from the schema
• fields: Field values where fields[0] MUST be the node ID (a string)
• child_count: Expected number of children (for LLM hints)

pub fn children(&self) -> Option<&BTreeMap<String, Vec<Node>>>

Get the children map, if any children have been added.

pub fn children_mut(&mut self) -> Option<&mut BTreeMap<String, Vec<Node>>>

Get mutable access to children map, if it exists.

Trait Implementations

impl Clone for Node

fn clone(&self) -> Node

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Node

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Node

fn default() -> Self

Returns the “default value” for a type.

impl PartialEq for Node

fn eq(&self, other: &Node) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Node