qubed — Core Library

The qubed crate provides the core Qube data structure, Coordinates types, compression, selection, serialization, and datacube conversion.

Cargo.toml:

[dependencies]
qubed = { path = "qubed" }

Qube

The central type. A Qube is a slot-map-backed tree where each node has a dimension name, a set of coordinate values, and children grouped by dimension.

Construction

Example — from ASCII:

#![allow(unused)]
fn main() {
use qubed::Qube;

let q = Qube::from_ascii(r#"root
├── class=od
│   ├── expver=0001, param=1/2
│   └── expver=0002, param=1/2
└── class=rd
    ├── expver=0001, param=1/2/3
    └── expver=0002, param=1/2"#).unwrap();
}

Example — from nested JSON:

#![allow(unused)]
fn main() {
use qubed::Qube;
use serde_json::json;

let q = Qube::from_json(json!({
    "class=od": {
        "expver=0001/0002": { "param=1/2": {} }
    },
    "class=rd": {
        "expver=0001": { "param=1/2/3": {} },
        "expver=0002": { "param=1/2": {} }
    }
})).unwrap();
}

Tree Modification

Example — building programmatically:

#![allow(unused)]
fn main() {
use qubed::{Qube, Coordinates};

let mut q = Qube::new();
let root = q.root();

let class = q.create_child("class", root,
    Some(Coordinates::from_string("od"))).unwrap();
let expver = q.create_child("expver", class,
    Some(Coordinates::from_string("0001/0002"))).unwrap();
q.create_child("param", expver,
    Some(Coordinates::from_string("1/2"))).unwrap();
}

Example — union:

#![allow(unused)]
fn main() {
let mut a = Qube::from_ascii("root\n└── class=od, param=1").unwrap();
let mut b = Qube::from_ascii("root\n└── class=rd, param=2").unwrap();
a.append(&mut b);
// a now contains both branches, compressed; b is empty
}

Example — drop:

#![allow(unused)]
fn main() {
let mut q = Qube::from_ascii(r#"root
└── class=1
    ├── expver=0001
    │   └── param=1/2
    └── expver=0002
        └── param=1/2"#).unwrap();

q.drop(vec!["expver"]).unwrap();
// expver is removed; param nodes are re-parented under class
}

Example — squeeze:

#![allow(unused)]
fn main() {
let mut q = Qube::from_ascii(r#"root
└── class=1
    ├── expver=0001
    │   └── param=1/2
    └── expver=0002
        └── param=1/2"#).unwrap();

q.squeeze().unwrap();
// class=1 is the only value for that dimension, so it is dropped
}

Compression

#![allow(unused)]
fn main() {
fn compress(&mut self)
}

Compress the tree in-place. Three phases:

1. Recursive merge — bottom-up, siblings with the same structural hash have their coordinates merged.
2. Prune — nodes with Coordinates::Empty are removed.
3. Dedup — structurally identical siblings are collapsed.

Called automatically by append and append_many.

Selection

#![allow(unused)]
fn main() {
fn select<C>(&self, selection: &[(&str, C)], mode: SelectMode) -> Result<Qube, String>
where C: Into<Coordinates> + Clone
}

Returns a new Qube containing only identifiers matching the constraints. C can be &[i32], Coordinates, or other Into<Coordinates> types.

#![allow(unused)]
fn main() {
fn prune(&mut self, node_id: NodeIdx, has_none_of: HashSet<&str>)
}

Remove branches that don’t contain all of the specified dimensions.

SelectMode:

• Default — keep branches with at least one matching value per constrained dimension.
• Prune — additionally remove branches missing any selected dimension entirely.

Serialization

Arena JSON node record:

{ "dim": "class", "coords": "od/rd", "parent": null, "children": [1, 2] }

Iteration & Inspection

NodeRef

Read-only reference to a node in the Qube tree.

Coordinates

A typed, ordered set of coordinate values.

Variants

Construction

Leading zero preservation: tokens with length > 1 that start with '0' followed by a digit are stored as String to preserve formatting (e.g. "0001" stays "0001", not 1).

Modification

Query

Set Operations

Datacube

A flat HashMap<String, Coordinates> representing one dense datacube.

Key Types Summary