diff --git a/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt b/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt index 7cfd9eedb26..e0da1085ed9 100644 --- a/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt +++ b/Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt @@ -234,15 +234,16 @@ typedef CGAL::Combinatorial_map<3, Example_items_3> Example_custom_cmap3; \cgalModifBegin -\subsection ssecIndicesHandles Indices or Handles +\subsection ssecCMapIndicesHandles Indices or Handles -By default, descriptors used to access darts and attributes are handles, and the darts and attributes are stored in a `Compact_container`. +By default, descriptors used to access darts and attributes are handles, and the darts and attributes are stored in a `Compact_container`. To use the index version, you should define the type `Use_index` equal to `CGAL::Tag_true` in the item class like in the code below. You can also define the type `Index_type` used to store indices (std::uint32_t by default when this type is not defined). \code{.cpp} struct Items_with_indices { typedef CGAL::Tag_true Use_index; + typedef std::uint16_t Index_type; // Optional template struct Dart_wrapper { @@ -252,7 +253,9 @@ struct Items_with_indices }; typedef CGAL::Combinatorial_map<3, Items_with_indices> Cmap3_with_index; -TODO +\endcode + +The two main interests of the index version comparing to the handle ones are: (1)~it has a lower memory footprint than a 64-bit pointer based version; (2)~indices are contiguous, they can be used as index into vectors which store properties. The main interest of the handle version is the fact that handles can be dereferenced, which can simplify some code. \cgalModifEnd diff --git a/Combinatorial_map/include/CGAL/Combinatorial_map/internal/Combinatorial_map_utility.h b/Combinatorial_map/include/CGAL/Combinatorial_map/internal/Combinatorial_map_utility.h index 1967c3bb333..def9ea8e6c9 100644 --- a/Combinatorial_map/include/CGAL/Combinatorial_map/internal/Combinatorial_map_utility.h +++ b/Combinatorial_map/include/CGAL/Combinatorial_map/internal/Combinatorial_map_utility.h @@ -16,6 +16,7 @@ #include #include #include +#include #include #include @@ -78,7 +79,7 @@ namespace CGAL template::value > struct Get_index_type - { typedef unsigned int type; }; // By default use unsigned int for index type + { typedef std::uint32_t type; }; // By default use uint32_t for index type template struct Get_index_type { typedef typename T::Index_type type; }; diff --git a/Generalized_map/doc/Generalized_map/Generalized_map.txt b/Generalized_map/doc/Generalized_map/Generalized_map.txt index 3c8cea31e3d..50b75b04053 100644 --- a/Generalized_map/doc/Generalized_map/Generalized_map.txt +++ b/Generalized_map/doc/Generalized_map/Generalized_map.txt @@ -167,7 +167,11 @@ Considering these different advantages and drawbacks, you can choose to use gene The diagram in \cgalFigureRef{fig_gmap_diagramme_class} shows the different classes of the package. `Generalized_map` is the main class (see Section \ref ssecgeneralizedmap "Generalized Maps"). It allows to manage darts and attributes (see Section \ref ssecattributesgmap "Cell Attributes"). Users can customize a generalized map thanks to an items class (see Section \ref ssecitemgmap "Generalized Map Items"), which defines the information associated with darts and the attribute types. These types may be different for different dimensions, and they may also be void (note that the main concepts of `GenericMap`, `GenericMapItems` and `CellAttribute` are shared between combinatorial maps and generalized maps). -The darts and attributes are accessed through handles. A handle is a model of the `Handle` concept, thus supporting the two dereference operators `operator*` and `operator->`. All handles are model of `LessThanComparable` and `Hashable`, that is they can be used as keys in containers such as `std::map` and `boost::unordered_map`. +\cgalModifBegin + +The darts and attributes are accessed through descriptors (either Indices or Handles). A handle is a model of the `Handle` concept, thus supporting the two dereference operators `operator*` and `operator->`. All handles are model of `LessThanComparable` and `Hashable`, that is they can be used as keys in containers such as `std::map` and `boost::unordered_map`. An index is a model of the `Index` concept, which is mainly an integer which is convertible from and to std::size_t. As the indices are contiguous, they can be used as index into vectors which store properties. + +\cgalModifEnd \cgalFigureBegin{fig_gmap_diagramme_class,gmap_diagramme_class.svg} UML diagram of the main classes of the package. k is the number of non void attributes. @@ -177,9 +181,9 @@ UML diagram of the main classes of the package. k is the number of non void attr The class `Generalized_map` is a model of the `GeneralizedMap` concept which refines the generic concept of `GenericMap`. It has three template parameters standing for the dimension of the generalized map (an `unsigned int`), an items class (a model of the `GenericMapItems` concept), and an allocator which must be a model of the allocator concept of the \stl. %Default classes are provided for the items and the allocator classes. -The main role of the class `Generalized_map` is the storage and the management of darts. It allows to create or remove an isolated dart from the generalized map. The \link GenericMap::Dart_descriptor `Dart_descriptor`\endlink type defines a handle to the type of used darts (given in the items class). `Generalized_map` provides several ranges which allow to iterate over specific subsets of darts of the generalized map (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). It also defines several methods to link and to unlink darts by \f$ \alpha_i\f$s (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts"). We said that a dart d0 is i-free if \f$ \alpha_i\f$(d0)=d0. Finally, some high level operations are defined to update the generalized map (see Section \ref ssecoperationsgmap "Removal and Insertion Operations") +The main role of the class `Generalized_map` is the storage and the management of darts. It allows to create or remove an isolated dart from the generalized map. The \link GenericMap::Dart_descriptor `Dart_descriptor`\endlink type defines a descriptor to the type of used darts (given in the items class). `Generalized_map` provides several ranges which allow to iterate over specific subsets of darts of the generalized map (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). It also defines several methods to link and to unlink darts by \f$ \alpha_i\f$s (see Section \ref sseclinkdarts_gmap "Sewing Orbits and Linking Darts"). We said that a dart d0 is i-free if \f$ \alpha_i\f$(d0)=d0. Finally, some high level operations are defined to update the generalized map (see Section \ref ssecoperationsgmap "Removal and Insertion Operations") -The second role of the class `Generalized_map` is the storage and the management of attributes. It allows to create or remove an attribute, and provides methods to associate attributes and cells. A range is defined for each i-attribute allowing to iterate over all the i-attributes of the generalized map. Finally, `Generalized_map` defines several types allowing to manage the attributes. We can use \link GenericMap::Attribute_descriptor `Generalized_map::Attribute_descriptor::type`\endlink for a handle to the i-attributes (and the const version \link GenericMap::Attribute_const_descriptor `Generalized_map::Attribute_const_descriptor::type`\endlink) and \link GenericMap::Attribute_type `Generalized_map::Attribute_type::type`\endlink for the type of the i-attributes. +The second role of the class `Generalized_map` is the storage and the management of attributes. It allows to create or remove an attribute, and provides methods to associate attributes and cells. A range is defined for each i-attribute allowing to iterate over all the i-attributes of the generalized map. Finally, `Generalized_map` defines several types allowing to manage the attributes. We can use \link GenericMap::Attribute_descriptor `Generalized_map::Attribute_descriptor::type`\endlink for a descriptor to the i-attributes (and the const version \link GenericMap::Attribute_const_descriptor `Generalized_map::Attribute_const_descriptor::type`\endlink) and \link GenericMap::Attribute_type `Generalized_map::Attribute_type::type`\endlink for the type of the i-attributes. All information associated to darts (\f$ \alpha\f$ links and attributes) are accessed through member functions in `GeneralizedMap`. @@ -195,7 +199,7 @@ The class `Generic_map_min_items` is a model of the `GenericMapItems` concept wh \subsection ssecattributesgmap Cell Attributes -The class `Cell_attribute`, a model of the `CellAttribute` concept, represents an attribute associated with a cell of a generalized map. The template parameter `Map` must be a model of the `GenericMap` concept. The attribute stores a handle to one dart of its associated cell when the template parameter `Tag` is \link CGAL::Tag_true `Tag_true`\endlink. `Info_` is the type of information stored in the attribute. It may be `void`. `OnMerge` and `OnSplit` must be either `Null_functor`, or models of the `Binary Function` concept having two references to a model of `CellAttribute` as type of both parameters and `void` as return type. There are two default parameters for `OnMerge` and `OnSplit`, which are `Null_functor`, a default parameter for `Tag` which is `Tag_true`, and a default parameter for `Info_` which is `void`. +The class `Cell_attribute`, a model of the `CellAttribute` concept, represents an attribute associated with a cell of a generalized map. The template parameter `Map` must be a model of the `GenericMap` concept. The attribute stores a descriptor to one dart of its associated cell when the template parameter `Tag` is \link CGAL::Tag_true `Tag_true`\endlink. `Info_` is the type of information stored in the attribute. It may be `void`. `OnMerge` and `OnSplit` must be either `Null_functor`, or models of the `Binary Function` concept having two references to a model of `CellAttribute` as type of both parameters and `void` as return type. There are two default parameters for `OnMerge` and `OnSplit`, which are `Null_functor`, a default parameter for `Tag` which is `Tag_true`, and a default parameter for `Info_` which is `void`. If `Info_` is different from `void`, the class `Cell_attribute` contains two methods `info()` returning the information contained in the attribute (const and non const version). The information is returned by reference, thus the non const version allows the modification of the information. @@ -227,9 +231,36 @@ typedef CGAL::Generalized_map<3, Example_items_3> Example_custom_gmap3; \endcode +\cgalModifBegin + +\subsection ssecGMapIndicesHandles Indices or Handles + +By default, descriptors used to access darts and attributes are handles, and the darts and attributes are stored in a `Compact_container`. To use the index version, you should define the type `Use_index` equal to `CGAL::Tag_true` in the item class like in the code below. You can also define the type `Index_type` used to store indices (std::uint32_t by default when this type is not defined). + +\code{.cpp} + +struct Items_with_indices +{ + typedef CGAL::Tag_true Use_index; + typedef std::uint16_t Index_type; // Optional + template + struct Dart_wrapper + { + typedef CGAL::Cell_attribute Edge_attrib; + typedef std::tuple Attributes; + }; +}; +typedef CGAL::Generalized_map<3, Items_with_indices> Gmap3_with_index; + +\endcode + +The two main interests of the index version comparing to the handle ones are: (1)~it has a lower memory footprint than a 64-bit pointer based version; (2)~indices are contiguous, they can be used as index into vectors which store properties. The main interest of the handle version is the fact that handles can be dereferenced, which can simplify some code. + +\cgalModifEnd + \section Generalized_mapIteration Iteration and Creation Operations -An important operation in generalized maps consists in iterating over specific subsets of darts or over attributes. For that, several ranges are offered (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). A range is a model of the `Range` concept, thus supporting the two methods `begin()` and `end()` allowing to iterate over all the elements in the range. Several functions allow to create specific configurations of darts into a generalized map (see Section \ref ssecconstructiongmap "Construction Operations"). Darts can be marked during operations, for example when performing a breadth-first search traversal, thanks to Boolean marks (see Sections \ref ssecadvmarksgmap "Boolean Marks"). In the following, we denote by `dh0`, `dh1`, `dh2` the dart handles for the darts `d0`, `d1`, `d2`, respectively. That is `d0 == *dh0`. +An important operation in generalized maps consists in iterating over specific subsets of darts or over attributes. For that, several ranges are offered (see Section \ref ssecrange "Iterating over Orbits, Cells, and Attributes"). A range is a model of the `Range` concept, thus supporting the two methods `begin()` and `end()` allowing to iterate over all the elements in the range. Several functions allow to create specific configurations of darts into a generalized map (see Section \ref ssecconstructiongmap "Construction Operations"). Darts can be marked during operations, for example when performing a breadth-first search traversal, thanks to Boolean marks (see Sections \ref ssecadvmarksgmap "Boolean Marks"). \tred{In the following, we denote by `d0`, `d1`, `d2` for three dart descriptors.} \subsection ssecrangegmap Iterating over Orbits, Cells, and Attributes