Struct CMap3

pub struct CMap3<T: CoordsFloat> { /* private fields */ }

Main map object.

Implementations

impl<T: CoordsFloat> CMap3<T>

Dart-related methods

pub fn n_darts(&self) -> usize

Return the current number of darts.

pub fn n_unused_darts(&self) -> usize

Return the current number of unused darts.

pub fn add_free_dart(&mut self) -> DartIdType

Add a new free dart to the map.

Return

Returns the ID of the new dart.

pub fn add_free_darts(&mut self, n_darts: usize) -> DartIdType

Add n_darts new free darts to the map.

Return

Returns the ID of the first new dart. Other IDs are in the range ID..ID+n_darts.

pub fn insert_free_dart(&mut self) -> DartIdType

Insert a new free dart into the map.

This method attempts to reuse an unused dart slot if available; otherwise, it adds a new one.

Return

Returns the ID of the inserted dart.

pub fn remove_free_dart(&mut self, dart_id: DartIdType)

Remove a free dart from the map.

The removed dart identifier is added to the list of free darts. This way of proceeding is necessary as the structure relies on dart indexing for encoding data, making reordering of any sort extremely costly.

Arguments

• dart_id: DartIdType – Identifier of the dart to remove.

Panics

This method may panic if:

• the dart is not free for all i,
• the dart is already marked as unused.

impl<T: CoordsFloat> CMap3<T>

Beta-related methods

pub fn beta_transac<const I: u8>( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> StmClosureResult<DartIdType>

Return β_I(dart_id).

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

Panics

The method will panic if I is not 0, 1, 2, or 3.

pub fn beta_rt_transac( &self, trans: &mut Transaction, i: u8, dart_id: DartIdType, ) -> StmClosureResult<DartIdType>

Return β_i(dart_id).

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

Panics

The method will panic if i is not 0, 1, 2, or 3.

pub fn beta<const I: u8>(&self, dart_id: DartIdType) -> DartIdType

Return β_I(dart_id).

Panics

The method will panic if I is not 0, 1, 2, or 3.

pub fn beta_rt(&self, i: u8, dart_id: DartIdType) -> DartIdType

Return β_i(dart_id).

Panics

The method will panic if i is not 0, 1, 2, or 3.

pub fn is_i_free<const I: u8>(&self, dart_id: DartIdType) -> bool

Check if a given dart is I-free.

Return

The method returns:

• true if β_I(dart_id) = NULL_DART_ID,
• false otherwise.

Panics

The function will panic if I is not 0, 1, 2, or 3.

pub fn is_free(&self, dart_id: DartIdType) -> bool

Check if a given dart is free for all i.

Return

Returns true if the dart is 0-free, 1-free, 2-free, and 3-free.

impl<T: CoordsFloat> CMap3<T>

I-cell-related methods

pub fn vertex_id(&self, dart_id: DartIdType) -> VertexIdType

Compute the ID of the vertex a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 0-cell orbit.

pub fn vertex_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> Result<VertexIdType, StmError>

Compute the ID of the vertex a given dart is part of, transactionally.

This corresponds to the minimum dart ID among darts composing the 0-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn edge_id(&self, dart_id: DartIdType) -> EdgeIdType

Compute the ID of the edge a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 1-cell orbit.

pub fn edge_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> Result<EdgeIdType, StmError>

Compute the ID of the edge a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 1-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn face_id(&self, dart_id: DartIdType) -> FaceIdType

Compute the ID of the face a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 2-cell orbit.

pub fn face_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> Result<FaceIdType, StmError>

Compute the ID of the face a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 2-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn volume_id(&self, dart_id: DartIdType) -> VolumeIdType

Compute the ID of the volume a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 3-cell orbit.

pub fn volume_id_transac( &self, trans: &mut Transaction, dart_id: DartIdType, ) -> Result<VolumeIdType, StmError>

Compute the ID of the volume a given dart is part of.

This corresponds to the minimum dart ID among darts composing the 3-cell orbit.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

pub fn i_cell<const I: u8>(&self, dart_id: DartIdType) -> Orbit3<'_, T>

Return the orbit defined by a dart and its I-cell.

Usage

The Orbit3 can be iterated upon to retrieve all dart members of the cell. Note that the dart passed as an argument is included as the first element of the returned orbit.

Panics

The method will panic if I is not 0, 1, 2, or 3.

pub fn iter_vertices(&self) -> impl Iterator<Item = VertexIdType> + '_

Return an iterator over IDs of all the map’s vertices.

pub fn iter_edges(&self) -> impl Iterator<Item = EdgeIdType> + '_

Return an iterator over IDs of all the map’s edges.

pub fn iter_faces(&self) -> impl Iterator<Item = FaceIdType> + '_

Return an iterator over IDs of all the map’s faces.

pub fn iter_volumes(&self) -> impl Iterator<Item = VolumeIdType> + '_

Return an iterator over IDs of all the map’s volumes.

impl<T: CoordsFloat> CMap3<T>

Built-in vertex-related methods

pub fn n_vertices(&self) -> usize

Return the current number of vertices.

pub fn read_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, ) -> StmClosureResult<Option<Vertex3<T>>>

Return the vertex associated to a given identifier.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

This method return a Option taking the following values:

• Some(v: Vertex3) if there is a vertex associated to this ID,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn write_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, vertex: impl Into<Vertex3<T>>, ) -> StmClosureResult<Option<Vertex3<T>>>

Replace the vertex associated to a given identifier and return its old value.

Arguments

• vertex_id: VertexIdentifier – Identifier of the vertex to replace.
• vertex: impl Into<Vertex3> – New Vertex3 value.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex3) if there was an old value,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn remove_vertex( &self, trans: &mut Transaction, vertex_id: VertexIdType, ) -> StmClosureResult<Option<Vertex3<T>>>

Remove the vertex associated to a given identifier and return it.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex3) if there was a value,
• None otherwise.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn force_read_vertex(&self, vertex_id: VertexIdType) -> Option<Vertex3<T>>

Read the vertex associated to a given identifier.

This variant is equivalent to read_vertex, but internally uses a transaction that will be retried until validated.

pub fn force_write_vertex( &self, vertex_id: VertexIdType, vertex: impl Into<Vertex3<T>>, ) -> Option<Vertex3<T>>

Write a vertex to a given identifier, and return its old value.

This variant is equivalent to write_vertex, but internally uses a transaction that will be retried until validated.

pub fn force_remove_vertex(&self, vertex_id: VertexIdType) -> Option<Vertex3<T>>

Remove the vertex associated to a given identifier and return it.

This variant is equivalent to remove_vertex, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat> CMap3<T>

Generic attribute-related methods

pub fn read_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, ) -> StmClosureResult<Option<A>>

Return the attribute A value associated to a given identifier.

The kind of cell A binds to is automatically deduced using its AttributeBind implementation.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

This method return a Option taking the following values:

• Some(a: A) if there is a value associated to this ID,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn write_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, val: A, ) -> StmClosureResult<Option<A>>

Replace the attribute A value associated to a given identifier and return its old value.

Arguments

• id: A::IdentifierType – Identifier of the cell’s value to replace.
• val: A – Attribute value.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(a: A) if there was an old value,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn remove_attribute<A: AttributeBind + AttributeUpdate>( &self, trans: &mut Transaction, id: A::IdentifierType, ) -> StmClosureResult<Option<A>>

Remove the attribute A value associated to a given identifier and return it.

Return / Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. Errors should not be processed manually, only processed via the ? operator.

The result contains an Option taking the following values:

• Some(a: A) if there was a value,
• None otherwise, or if there is no storage for this kind of attribute in the map.

Panics

The method may panic if:

• the index lands out of bounds,
• the index cannot be converted to usize.

pub fn force_read_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Return the attribute A value associated to a given identifier.

This variant is equivalent to read_attribute, but internally uses a transaction that will be retried until validated.

pub fn force_write_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, val: A, ) -> Option<A>

Replace the attribute A value associated to a given identifier and return its old value.

This variant is equivalent to write_attribute, but internally uses a transaction that will be retried until validated.

pub fn force_remove_attribute<A: AttributeBind + AttributeUpdate>( &self, id: A::IdentifierType, ) -> Option<A>

Remove the attribute A value associated to a given identifier and return it.

This variant is equivalent to remove_attribute, but internally uses a transaction that will be retried until validated.

pub fn remove_attribute_storage<A: AttributeBind + AttributeUpdate>(&mut self)

Remove the attribute A’s storage from the map.

This method is useful when implementing routines that use attributes to run; Those can then be removed before the final result is returned.

impl<T: CoordsFloat> CMap3<T>

Link operations

pub fn link<const I: u8>( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> TransactionClosureResult<(), LinkError>

I-link operator.

Description

This operation corresponds to coherently linking two darts via their β images. Unlike sewing, this does not alter associated attributes. For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Link dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• lhs_dart_id: DartIdType – First dart ID.
• rhs_dart_id: DartIdType – Second dart ID.

Errors

This method should be called in a transactional context. The Result is then used to validate the transaction; Errors should not be processed manually, only processed via the ? operator. The policy in case of failure can be defined when creating the transaction, using Transaction::with_control.

Panics

The method may panic if:

• I >= 4 or I == 0,
• the two darts are not I-linkable.

pub fn unlink<const I: u8>( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> TransactionClosureResult<(), LinkError>

I-unlink operator.

Description

This operation corresponds to unlinking two darts by resetting their β images. Unlike unsewing, this does not alter associated attributes. For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Unlink dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• lhs_dart_id: DartIdType – First dart ID.

The second dart ID is fetched using I and lhs_dart_id.

Errors

This method should be called in a transactional context. The Result is then used to validate the transaction; Errors should not be processed manually, only processed via the ? operator. The policy in case of failure can be defined when creating the transaction, using Transaction::with_control.

Panics

The method may panic if:

• I >= 4 or I == 0,
• lhs_dart_id is already I-free.

pub fn force_link<const I: u8>( &self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> Result<(), LinkError>

I-link operator.

This variant is equivalent to link, but internally uses a transaction that will be retried until validated.

pub fn force_unlink<const I: u8>( &self, lhs_dart_id: DartIdType, ) -> Result<(), LinkError>

I-unlink operator.

This variant is equivalent to unlink, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat> CMap3<T>

Serialization methods

pub fn serialize(&self, writer: impl Write)

Serialize the map under a custom format.

The format specification is described in the user guide.

impl<T: CoordsFloat> CMap3<T>

Sew operations

pub fn sew<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, rd: DartIdType, ) -> TransactionClosureResult<(), SewError>

I-sew operator.

Description

This operation corresponds to:

• coherently linking two darts via their β images,
• merging the attributes associated to their respective original I-cells.

For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Sew dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.
• rd: DartIdType – Second dart ID.

Errors

This variant will abort the sew operation and raise an error if:

• the transaction cannot be completed,
• one (or more) attribute merge fails,
• for I == 3: orientation is inconsistent.

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose to retry or abort as he wishes using Transaction::with_control.

Panics

The method may panic if:

• I >= 4 or I == 0,
• the two darts are not I-sewable.

pub fn unsew<const I: u8>( &self, trans: &mut Transaction, ld: DartIdType, ) -> TransactionClosureResult<(), SewError>

I-unsew operator.

Description

This operation corresponds to:

• unlinking two darts by resetting their β images,
• splitting the attributes associated to the original I-cell.

For a thorough explanation of this operation, its hypothesis & consequences, refer to the user guide.

Arguments

• const I: u8 – Unsew dimension.
• trans: &mut Transaction – Transaction associated to the operation.
• ld: DartIdType – First dart ID.

The second dart ID is fetched using I and ld.

Errors

This variant will abort the unsew operation and raise an error if:

• the transaction cannot be completed,
• one (or more) attribute split fails.

The returned error can be used in conjunction with transaction control to avoid any modifications in case of failure at attribute level. The user can then choose to retry or abort as he wishes using Transaction::with_control.

Panics

The method may panic if:

• I >= 4 or I == 0,
• ld is already I-free.

pub fn force_sew<const I: u8>( &self, ld: DartIdType, rd: DartIdType, ) -> Result<(), SewError>

I-sew operator.

This variant is equivalent to sew, but internally uses a transaction that will be retried until validated.

pub fn force_unsew<const I: u8>(&self, ld: DartIdType) -> Result<(), SewError>

I-unsew operator.

This variant is equivalent to unsew, but internally uses a transaction that will be retried until validated.

impl<T: CoordsFloat> CMap3<T>

Utilities

pub fn set_beta<const I: u8>(&self, dart_id: DartIdType, val: DartIdType)

Set the value of the specified beta function of a dart.

Arguments

• const I: u8 – Beta function to edit.
• dart_id: DartIdType – ID of the dart of interest.
• val: DartIdType – New value of β_I(dart_id).

pub fn set_betas(&self, dart_id: DartIdType, [b0, b1, b2, b3]: [DartIdType; 4])

Set the values of the beta functions of a dart.

Arguments

• dart_id: DartIdType – ID of the dart of interest.
• betas: [DartIdType; 4] – New values of [β₀(dart), β₁(dart), β₂(dart), β₃(dart)]

Trait Implementations

impl<T: CoordsFloat> Send for CMap3<T>

impl<T: CoordsFloat> Sync for CMap3<T>