Struct KeyBuilder 

pub struct KeyBuilder { /* private fields */ }

Assembles one key by appending sub-keys at successive bit offsets.

This is the composition operation a tree needs: a node’s key is its own local key followed by each child’s key, so key(node) = local ++ key(c1) ++ key(c2) ++ .... Appending at a known bit offset costs one pass over the pushed key’s limbs, so composing a tree is linear in total width rather than quadratic as a multiply-based mixed-radix composition would be.

The result equals what FlatIndexer::encode produces for the concatenated multi-index, so a composed key and a directly encoded one are interchangeable as map keys.

Examples

use tensor4all_core::index_key::{FlatIndexer, KeyBuilder};
let local = FlatIndexer::try_new(&[3, 2]).unwrap();
let child = FlatIndexer::try_new(&[4]).unwrap();
let whole = FlatIndexer::try_new(&[3, 2, 4]).unwrap();

let mut builder = KeyBuilder::with_capacity_bits(whole.width_bits()).unwrap();
builder.push(&local.encode(&[2, 1]).unwrap()).unwrap();
builder.push(&child.encode(&[3]).unwrap()).unwrap();

assert_eq!(builder.finish(), whole.encode(&[2, 1, 3]).unwrap());

Implementations

impl KeyBuilder

pub fn with_capacity_bits(width_bits: u64) -> Result<Self, IndexKeyError>

Creates a builder able to hold width_bits of appended sub-keys.

Errors

Returns IndexKeyError::WidthOverflow when the width cannot be allocated on this platform.

Examples

use tensor4all_core::index_key::KeyBuilder;
assert!(KeyBuilder::with_capacity_bits(0).is_ok());
assert!(KeyBuilder::with_capacity_bits(4096).is_ok());

pub fn width_bits(&self) -> u64

Total bits appended so far.

pub fn push(&mut self, key: &IndexKey) -> Result<(), IndexKeyError>

Appends key at the current offset, advancing by the key’s own width.

The width comes from the key itself, so a sub-key can never be placed under a width that disagrees with its contents – which would overwrite the following field and silently break injectivity.

Errors

Returns IndexKeyError::WidthOverflow when the append would exceed the declared capacity, rather than truncating the key.

Examples

use tensor4all_core::index_key::{FlatIndexer, KeyBuilder};
let indexer = FlatIndexer::try_new(&[2, 2]).unwrap();
let key = indexer.encode(&[1, 1]).unwrap();
let mut builder = KeyBuilder::with_capacity_bits(2).unwrap();
assert!(builder.push(&key).is_ok());
assert!(builder.push(&key).is_err());

pub fn finish(self) -> IndexKey

Produces the key for the bits actually appended.

The arm is selected from the appended width, not from the declared capacity, so a composed key equals the same value from FlatIndexer::encode even when the builder was given more capacity than it ended up using.

Examples

use tensor4all_core::index_key::{FlatIndexer, KeyBuilder};
let indexer = FlatIndexer::try_new(&[2, 2]).unwrap();
let key = indexer.encode(&[1, 0]).unwrap();

// Over-declared capacity does not change the composed key.
let mut tight = KeyBuilder::with_capacity_bits(2).unwrap();
tight.push(&key).unwrap();
let mut loose = KeyBuilder::with_capacity_bits(600).unwrap();
loose.push(&key).unwrap();
let composed = tight.finish();
assert_eq!(composed, loose.finish());
assert_eq!(composed, key);

let empty = KeyBuilder::with_capacity_bits(8).unwrap();
assert_eq!(empty.finish().width_bits(), 0);

Trait Implementations

impl Clone for KeyBuilder

fn clone(&self) -> KeyBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for KeyBuilder

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

Formats the value using the given formatter.