Struct ProvenanceTable 

pub struct ProvenanceTable { /* private fields */ }

Assigns EntityIds and remembers what each one came from.

One per document. Cloning it clones the whole history, which is what a rebuild-with-rollback needs.

An entry can be forgotten (ProvenanceTable::forget, ProvenanceTable::retain): its id stays issued, so no later entity takes it, and asking for it answers None as for an id from another document.

Implementations

impl ProvenanceTable

pub const fn new() -> Self

An empty table.

pub const fn len(&self) -> usize

Number of identities issued, forgotten ones included: the next recorded entity is this plus one.

pub const fn is_empty(&self) -> bool

Whether no identity has been issued.

pub fn record(&mut self, provenance: Provenance) -> EntityId

Record an entity’s provenance and return its identity.

Panics

If more than u64::MAX - 1 entities are recorded. Not reachable.

pub fn primitive(&mut self, op: OpId, role: Role) -> EntityId

Convenience for Provenance::Primitive.

pub fn derived( &mut self, op: OpId, from: impl IntoIterator<Item = EntityId>, role: Role, ) -> EntityId

Convenience for Provenance::Derived.

pub fn get(&self, id: EntityId) -> Option<&Provenance>

The provenance of id, or None if it belongs to another document or its entry was forgotten.

pub fn forget(&mut self, id: EntityId) -> bool

Drop id’s entry and keep its id issued.

For a document that keeps only what its shapes can still reach: an entity no shape carries and no kept entry derives from answers nothing a reference could ask. Returns whether there was an entry to drop.

pub fn retain(&mut self, keep: impl FnMut(EntityId, &Provenance) -> bool)

Keep the entries keep answers true for and forget the rest, as ProvenanceTable::forget does each one. What is forgotten stops costing memory.

pub fn roots(&self, id: EntityId) -> Vec<EntityId>

Walk id’s derivation back to the entities it ultimately came from.

Returns the roots: entities that are Primitive or Imported. This is how a stale reference is resolved after a rebuild: find what the user originally picked, then find what that became.

Cycles cannot occur, because an entity can only be derived from ids that already existed when it was recorded. The visited set guards against a table assembled by hand or deserialized from a corrupt file.

pub fn iter(&self) -> impl Iterator<Item = (EntityId, &Provenance)>

Every entity with an entry, in the order its identity was issued; forgotten entries are skipped.

For writing a document out: the table is the record of what every entity is, and a file that dropped it would come back as a model whose every reference had to be rebuilt from scratch.

Trait Implementations

impl Clone for ProvenanceTable

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for ProvenanceTable

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

Formats the value using the given formatter.

impl Default for ProvenanceTable

fn default() -> Self

Returns the “default value” for a type.