Struct CMap2

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

Main map object.

Structure used to model 2D combinatorial map. The structure implements basic operations as well as higher level abstractions that are useful to write meshing applications.

Definition of the structure and its logic can be found in the user guide. This documentation focuses on the implementation and its API.

This structure only implements Clone if the utils feature is enabled.

Fields

Fields are kept private in order to better define interfaces. The structure contains the following data:

• an array-based representation of the beta functions
• a storage structure for vertices making up the represented mesh
• a generic storage manager for user-defined attributes

Note that:

• we encode β₀ as the inverse function of β₁. This is extremely useful (read required) to implement correct and efficient i-cell computation. Additionally, while β₀ can be accessed using the Self::beta method, we do not define the 0-sew / 0-unsew operations.
• we chose a boundary-less representation of meshes (i.e. darts on the boundary are 2-free).

Generics

• T: CoordsFloat – Generic type for coordinates representation.

Example

The following example goes over multiple operations on the mesh in order to demonstrate general usage of the structure and its methods.

Note that:

• we create the map using its builder structure: CMapBuilder.
• the map we operate on has no boundaries. In addition to the different operations realized at each step, we insert a few assertions to demonstrate the progressive changes applied to the structure.

use honeycomb_core::prelude::{CMap2, CMapBuilder, Orbit2, OrbitPolicy, Vertex2};

// build a triangle
let mut map: CMap2<f64> = CMapBuilder::default().n_darts(3).build().unwrap(); // three darts
map.force_one_link(1, 2); // beta1(1) = 2 & beta0(2) = 1
map.force_one_link(2, 3); // beta1(2) = 3 & beta0(3) = 2
map.force_one_link(3, 1); // beta1(3) = 1 & beta0(1) = 3
map.force_write_vertex(1, (0.0, 0.0));
map.force_write_vertex(2, (1.0, 0.0));
map.force_write_vertex(3, (0.0, 1.0));

// we can go through the face using an orbit
let mut face = Orbit2::new(&map, OrbitPolicy::Face, 1);
assert_eq!(face.next(), Some(1));
assert_eq!(face.next(), Some(2));
assert_eq!(face.next(), Some(3));
assert_eq!(face.next(), None);

// build a second triangle
let first_added_dart_id = map.add_free_darts(3);
assert_eq!(first_added_dart_id, 4);
map.force_one_link(4, 5);
map.force_one_link(5, 6);
map.force_one_link(6, 4);
map.force_write_vertex(4, (0.0, 2.0));
map.force_write_vertex(5, (2.0, 0.0));
map.force_write_vertex(6, (1.0, 1.0));

// there should be two faces now
let faces = map.fetch_faces();
assert_eq!(&faces.identifiers, &[1, 4]);

// sew both triangles
map.force_two_sew(2, 4);

// there are 5 edges now, making up a square & its diagonal
let edges = map.fetch_edges();
assert_eq!(&edges.identifiers, &[1, 2, 3, 5, 6]);

// adjust bottom-right & top-left vertex position
// the returned values were the average of the sewn vertices
assert_eq!(
    map.force_write_vertex(2, Vertex2::from((1.0, 0.0))),
    Some(Vertex2(1.5, 0.0))
);
assert_eq!(
    map.force_write_vertex(3, Vertex2::from((0.0, 1.0))),
    Some(Vertex2(0.0, 1.5))
);

// separate the diagonal from the rest
map.force_one_unsew(1);
map.force_one_unsew(2);
map.force_one_unsew(6);
map.force_one_unsew(4);
// break up & remove the diagonal
map.force_two_unsew(2); // this makes dart 2 and 4 free
map.remove_free_dart(2);
map.remove_free_dart(4);
// sew the square back up
map.force_one_sew(1, 5);
map.force_one_sew(6, 3);

// there's only the square face left
let faces = map.fetch_faces();
assert_eq!(&faces.identifiers, &[1]);
// we can check the vertices
let vertices = map.fetch_vertices();
let mut value_iterator = vertices.identifiers.iter().map(|vertex_id| map.force_read_vertex(*vertex_id).unwrap());
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 0.0)))); // vertex ID 1
assert_eq!(value_iterator.next(), Some(Vertex2::from((0.0, 1.0)))); // vertex ID 3
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 0.0)))); // vertex ID 5
assert_eq!(value_iterator.next(), Some(Vertex2::from((1.0, 1.0)))); // vertex ID 6

Implementations

impl<T: CoordsFloat> CMap2<T>

Dart-related methods

pub fn n_darts(&self) -> usize

Return information about the current number of darts.

pub fn n_unused_darts(&self) -> usize

Return information about the current number of unused darts.

pub fn add_free_dart(&mut self) -> DartIdType

Add a new free dart to the combinatorial map.

The dart is i-free for all i and is pushed to the list of existing darts, effectively making its identifier equal to the total number of darts (post-push).

Return

Return the ID of the created dart to allow for direct operations.

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

Add multiple new free darts to the combinatorial map.

All darts are i-free for all i and are pushed to the end of the list of existing darts.

Arguments

• n_darts: usize – Number of darts to have.

Return

Return the ID of the first created dart to allow for direct operations. Darts are positioned on range ID..ID+n_darts.

pub fn insert_free_dart(&mut self) -> DartIdType

Insert a new free dart to the combinatorial map.

The dart is i-free for all i and may be inserted into an unused spot in the existing dart list. If no free spots exist, it will be pushed to the end of the list.

Return

Return the ID of the created dart to allow for direct operations.

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

Remove a free dart from the combinatorial map.

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

By keeping track of free spots in the dart arrays, we can prevent too much memory waste, although at the cost of locality of reference.

Arguments

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

Panics

This method may panic if:

• The dart is not i-free for all i.
• The dart is already marked as unused (Refer to Self::remove_vertex documentation for a detailed breakdown of this choice).

impl<T: CoordsFloat> CMap2<T>

Beta-related methods

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

Compute the value of the i-th beta function of a given dart.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Generics

• const I: u8 – Index of the beta function. I should be 0, 1 or 2 for a 2D map.

Return

Return the identifier of the dart d such that d = β_i(dart). If the returned value is the null dart (i.e. a dart ID equal to 0), this means that the dart is i-free.

Panics

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

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

Compute the value of the i-th beta function of a given dart.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.
• i: u8 – Index of the beta function. i should be 0, 1 or 2 for a 2D map.

Return

Return the identifier of the dart d such that d = β_i(dart). If the returned value is the null dart (i.e. a dart ID equal to 0), this means that the dart is i-free.

Panics

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

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

Check if a given dart is i-free.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Generics

• const I: u8 – Index of the beta function. I should be 0, 1 or 2 for a 2D map.

Return

Return a boolean indicating if the dart is i-free, i.e. β_i(dart) = NULL_DART_ID.

Panics

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

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

Check if a given dart is i-free, for all i.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Return

Return a boolean indicating if the dart is 0-free, 1-free and 2-free.

impl<T: CoordsFloat> CMap2<T>

I-cell-related methods

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

Fetch vertex identifier associated to a given dart.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Return

Return the identifier of the associated vertex.

Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

• A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
• Cell IDs are not affected by the order of traversal of the map.
• Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

1. a BFS to compute a given orbit
2. a minimum computation on the IDs composing the orbit

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

Fetch edge associated to a given dart.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Return

Return the identifier of the associated edge.

Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

• A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
• Cell IDs are not affected by the order of traversal of the map.
• Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

1. a BFS to compute a given orbit
2. a minimum computation on the IDs composing the orbit

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

Fetch face associated to a given dart.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Return

Return the identifier of the associated face.

Note on cell identifiers

Cells identifiers are defined as the smallest identifier among the darts that make up the cell. This definition has three interesting properties:

• A given cell ID can be computed from any dart of the cell, i.e. all darts have an associated cell ID.
• Cell IDs are not affected by the order of traversal of the map.
• Because the ID is computed in real time, there is no need to store cell IDs and ensure that the storage is consistent / up to date.

These properties come at the literal cost of the computation routine, which is:

1. a BFS to compute a given orbit
2. a minimum computation on the IDs composing the orbit

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

Return an Orbit2 object that can be used to iterate over darts of an i-cell.

Arguments

• dart_id: DartIdentifier – Identifier of a given dart.

Generics

• const I: u8 – Dimension of the cell of interest. I should be 0 (vertex), 1 (edge) or 2 (face) for a 2D map.

Return

Returns an Orbit2 that can be iterated upon to retrieve all dart member 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 or 2.

pub fn fetch_vertices(&self) -> VertexCollection<'_, T>

Return a collection of all the map’s vertices.

Return

Return a VertexCollection object containing a list of vertex identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

pub fn fetch_edges(&self) -> EdgeCollection<'_, T>

Return a collection of all the map’s edges.

Return

Return an EdgeCollection object containing a list of edge identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

pub fn fetch_faces(&self) -> FaceCollection<'_, T>

Return a collection of all the map’s faces.

Return

Return a FaceCollection object containing a list of face identifiers, whose validity is ensured through an implicit lifetime condition on the structure and original map.

impl<T: CoordsFloat> CMap2<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, ) -> StmResult<Option<Vertex2<T>>>

Read vertex associated to a given identifier.

Arguments

• vertex_id: VertexIdentifier – Identifier of the given vertex.

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. The result should not be processed manually, only used via the ? operator.

This method return a Option taking the following values:

• Some(v: Vertex2) 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<Vertex2<T>>, ) -> StmResult<Option<Vertex2<T>>>

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

This method can be interpreted as giving a value to the vertex of a specific ID. Vertices implicitly exist through topology, but their spatial representation is not automatically created at first.

Arguments

• vertex_id: VertexIdentifier – Vertex identifier to attribute a value to.
• vertex: impl Into<Vertex2> – Value used to create a Vertex2 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. The result should not be processed manually, only used via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex2) – The old value was successfull replaced & returned
• None – The value was successfully set

Panics

The method may panic if:

• there is already a vertex associated to the specified index
• the index lands out of bounds
• the index cannot be converted to usize

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

Remove vertex associated to a given identifier and return it.

Arguments

• vertex_id: VertexIdentifier – Identifier of the vertex to remove.

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. The result should not be processed manually, only used via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex2) – The vertex was successfully removed & its value was returned
• None – The vertex was not found in the internal storage

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<Vertex2<T>>

Read 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<Vertex2<T>>, ) -> Option<Vertex2<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<Vertex2<T>>

Remove 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> CMap2<T>

Generic attribute-related methods

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

Read a given attribute’s value associated to a given identifier.

Arguments

• index: A::IdentifierType – Cell index.

Generic

• A: AttributeBind + AttributeUpdate – Attribute to read.

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. The result should not be processed manually, only used via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex2) – The old value was successfull replaced & returned
• None – The value was successfully set

Panics

The method:

• should panic if the index lands out of bounds
• may panic if the index cannot be converted to usize

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

Write a given attribute’s value to a given identifier, and return its old value.

Arguments

• index: A::IdentifierType – Cell index.
• val: A – Attribute value.

Generic

• A: AttributeBind + AttributeUpdate – Attribute to edit.

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. The result should not be processed manually, only used via the ? operator.

The result contains an Option taking the following values:

• Some(v: Vertex2) – The old value was successfull replaced & returned
• None – The value was successfully set

Panics

The method:

• should panic if the index lands out of bounds
• may panic if the index cannot be converted to usize

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

Remove a given attribute’s value from the storage and return it.

Arguments

• index: A::IdentifierType – Cell index.

Generic

• A: AttributeBind + AttributeUpdate – Attribute to edit.

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. The result should not be processed manually, only used via the ? operator.

The result contains an Option taking the following values:

• Some(val: A) – The vertex was successfully removed & its value was returned
• None – The vertex was not found in the internal storage

Panics

The method:

• may panic if the index lands out of bounds
• may panic if the index cannot be converted to usize

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

Read a given attribute’s 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>

Write a given attribute’s value 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 a given attribute’s value from the storage 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 an entire attribute storage from the map.

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

Generic

• A: AttributeBind + AttributeUpdate – Attribute stored by the fetched storage.

impl<T: CoordsFloat> CMap2<T>

1-links

pub fn one_link( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> StmResult<()>

1-link operation.

This operation corresponds to linking two darts via the β₁ function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s). The β₀ function is also updated.

Arguments

• lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
• rhs_dart_id: DartIdentifier – ID of the second dart to be linked.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

Panics

This method may panic if lhs_dart_id isn’t 1-free or rhs_dart_id isn’t 0-free.

pub fn force_one_link(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

1-link operation.

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

impl<T: CoordsFloat> CMap2<T>

1-unlinks

pub fn one_unlink( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> StmResult<()>

1-unlink operation.

This operation corresponds to unlinking two darts that are linked via the β₁ function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s). The β₀ function is also updated.

Arguments

• lhs_dart_id: DartIdentifier – ID of the dart to unlink.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

Panics

This method may panic if one of lhs_dart_id is already 1-free.

pub fn force_one_unlink(&self, lhs_dart_id: DartIdType)

1-unlink operation.

This operation corresponds to unlinking two darts that are linked via the β₁ function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s). The β₀ function is also updated.

Arguments

• lhs_dart_id: DartIdentifier – ID of the dart to unlink.

Panics

This method may panic if one of lhs_dart_id is already 1-free.

impl<T: CoordsFloat> CMap2<T>

2-links

pub fn two_link( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> StmResult<()>

2-link operation.

This operation corresponds to linking two darts via the β₂ function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s).

Arguments

• lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
• rhs_dart_id: DartIdentifier – ID of the second dart to be linked.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

Panics

This method may panic if one of lhs_dart_id or rhs_dart_id isn’t 2-free.

pub fn force_two_link(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

2-link operation.

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

impl<T: CoordsFloat> CMap2<T>

2-unlinks

pub fn two_unlink( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> StmResult<()>

2-unlink operation.

This operation corresponds to unlinking two darts that are linked via the β₂ function. Unlike its sewing counterpart, this method does not contain any code to update the attributes or geometrical data of the affected cell(s).

Arguments

• lhs_dart_id: DartIdentifier – ID of the dart to unlink.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

Panics

This method may panic if one of lhs_dart_id is already 2-free.

pub fn force_two_unlink(&self, lhs_dart_id: DartIdType)

2-unlink operation.

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

impl<T: CoordsFloat> CMap2<T>

1-sews

pub fn one_sew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> StmResult<()>

1-sew operation.

This operation corresponds to coherently linking two darts via the β₁ function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

Arguments

• lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
• rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
• policy: SewPolicy – Geometrical sewing policy to follow.

After the sewing operation, these darts will verify β₁(lhs_dart) = rhs_dart. The β₀ function is also updated.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

The policy in case of failure can be defined through the transaction, using Transaction::with_control for construction.

Panics

The method may panic if the two darts are not 1-sewable.

pub fn force_one_sew(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

1-sew two darts.

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

pub fn try_one_sew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> CMapResult<()>

Attempt to 1-sew two darts.

Errors

This method will fail, returning an error, if:

• the transaction cannot be completed
• one (or more) attribute merge 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, through its transaction control policy, to retry or abort as he wishes.

impl<T: CoordsFloat> CMap2<T>

1-unsews

pub fn one_unsew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> StmResult<()>

1-unsew operation.

This operation corresponds to coherently separating two darts linked via the β₁ function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

Arguments

• lhs_dart_id: DartIdentifier – ID of the dart to separate.
• policy: UnsewPolicy – Geometrical unsewing policy to follow.

Note that we do not need to take two darts as arguments since the second dart can be obtained through the β₁ function. The β₀ function is also updated.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

The policy in case of failure can be defined through the transaction, using Transaction::with_control for construction.

Panics

The method may panic if there’s a missing attribute at the splitting step. While the implementation could fall back to a simple unlink operation, it probably should have been called by the user, instead of unsew, in the first place.

pub fn force_one_unsew(&self, lhs_dart_id: DartIdType)

1-unsew two darts.

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

pub fn try_one_unsew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> CMapResult<()>

Attempt to 1-unsew two darts.

Errors

This method will fail, returning an error, if:

• the transaction cannot be completed
• one (or more) attribute merge 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, through its transaction control policy, to retry or abort as he wishes.

impl<T: CoordsFloat> CMap2<T>

2-sews

pub fn two_sew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> StmResult<()>

2-sew operation.

This operation corresponds to coherently linking two darts via the β₂ function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

Arguments

• lhs_dart_id: DartIdentifier – ID of the first dart to be linked.
• rhs_dart_id: DartIdentifier – ID of the second dart to be linked.
• policy: SewPolicy – Geometrical sewing policy to follow.

After the sewing operation, these darts will verify β₂(lhs_dart) = rhs_dart and β₂(rhs_dart) = lhs_dart.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

The policy in case of failure can be defined through the transaction, using Transaction::with_control for construction.

Panics

The method may panic if:

• the two darts are not 2-sewable,
• the method cannot resolve orientation issues.

pub fn force_two_sew(&self, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType)

2-sew two darts.

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

pub fn try_two_sew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, rhs_dart_id: DartIdType, ) -> CMapResult<()>

Attempt to 2-sew two darts.

Errors

This method will fail, returning an error, if:

• the transaction cannot be completed
• one (or more) attribute merge 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, through its transaction control policy, to retry or abort as he wishes.

impl<T: CoordsFloat> CMap2<T>

2-unsews

pub fn two_unsew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> StmResult<()>

2-unsew operation.

This operation corresponds to coherently separating two darts linked via the β₂ function. For a thorough explanation of this operation (and implied hypothesis & consequences), refer to the user guide.

Arguments

• lhs_dart_id: DartIdentifier – ID of the dart to separate.
• policy: UnsewPolicy – Geometrical unsewing policy to follow.

Note that we do not need to take two darts as arguments since the second dart can be obtained through the β₂ function.

Errors

This method is meant to be called in a context where the returned Result is used to validate the transaction passed as argument. The result should not be processed manually.

The policy in case of failure can be defined through the transaction, using Transaction::with_control for construction.

Panics

The method may panic if there’s a missing attribute at the splitting step. While the implementation could fall back to a simple unlink operation, it probably should have been called by the user, instead of unsew, in the first place.

pub fn force_two_unsew(&self, lhs_dart_id: DartIdType)

2-unsew two darts.

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

pub fn try_two_unsew( &self, trans: &mut Transaction, lhs_dart_id: DartIdType, ) -> CMapResult<()>

Attempt to 2-unsew two darts.

Errors

This method will fail, returning an error, if:

• the transaction cannot be completed
• one (or more) attribute merge 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, through its transaction control policy, to retry or abort as he wishes.

impl<T: CoordsFloat + 'static> CMap2<T>

Serializing methods

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

Available on crate feature io only.

Generate a legacy VTK file from the map.

Panics

This function may panic if the internal writing routine fails, i.e.: - Vertex coordinates cannot be cast to f32 or f64 - A vertex cannot be found

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

Available on crate feature io only.

Generate a legacy VTK file from the map.

Panics

This function may panic if the internal writing routine fails, i.e.: - Vertex coordinates cannot be cast to f32 or f64 - A vertex cannot be found

impl<T: CoordsFloat> CMap2<T>

Utilities

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

Available on crate feature utils only.

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

Arguments

• dart_id: DartIdentifier – ID of the dart of interest.
• val: DartIdentifier – Value of the image of dart_id through the beta I function.

Generic

• const I: u8 – Beta function to edit.

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

Available on crate feature utils only.

Set the values of the beta functions of a dart.

Arguments

• dart_id: DartIdentifier – ID of the dart of interest.
• betas: [DartIdentifier; 3] – Value of the images as [β₀(dart), β₁(dart), β₂(dart)]

pub fn allocated_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the total allocated space dedicated to the map.

Arguments

• rootname: &str – root of the filename used to save results.

Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

Errors

The method will return an error if:

• the file cannot be created,
• at any point, the program cannot write into the output file.

pub fn effective_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the total used space dedicated to the map.

Arguments

• rootname: &str – root of the filename used to save results.

Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

Errors

The method will return an error if:

• the file cannot be created,
• at any point, the program cannot write into the output file.

pub fn used_size(&self, rootname: &str) -> Result<(), Error>

Available on crate feature utils only.

Computes the actual used space dedicated to the map.

Actual used space refers to the total used space minus empty spots in the structure.

Arguments

• rootname: &str – root of the filename used to save results.

Return / Panic

The results of this method is saved as a csv file named <rootname>_allocated.csv. The csv file is structured as follows:

key, memory (bytes)
cat1_member1, val
cat1_member2, val
cat1_total, val
cat2_member1, val
cat2_member2, val
cat2_member3, val
cat2_total, val
cat3_member1, val
cat3_total, val

It is mainly designed to be used in dedicated scripts for plotting & analysis.

The metod may panic if, for any reason, it is unable to write to the file.

Example

An example going over all three size methods is provided in the honeycomb-utils crate. You can run it using the following command:

cargo run --example memory_usage

The output data can be visualized using the memory_usage.py script.

Errors

The method will return an error if:

• the file cannot be created,
• at any point, the program cannot write into the output file.

Trait Implementations

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

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