Finalize doc + example.

Combinatorial_map/doc/Combinatorial_map/Combinatorial_map.txt

@@ -1129,6 +1129,7 @@ attributes.  In \cgalFigureRef{figexemplesew} (Left), if we call
 \f$ \beta_3\f$(1)=5 and \f$ \beta_3\f$(5)=1. This combinatorial map is
 no longer valid (for example dart 2 is 3-free and we should have \f$
 \beta_3\f$(2)=8).
+A call latter to \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink will correct the invalid non void attributes.
 \cgalAdvancedEnd
 
 \subsection ssecoperations Removal and Insertion Operations
@@ -1229,6 +1230,10 @@ dart `d5`, we obtain the initial combinatorial map.
 Some examples of use of these operations are given in Section \ref
 ssecexempleoperations "High Level Operations".
 
+\cgalAdvancedBegin
+If \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future insertion or removal operations will not update non void attributes. These attributes will be updated latter by the call to \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink. This can be useful to speed up an algorithm which uses several successive insertion and removal operations. See example \ref ssecAttributesManagement "Automatic attributes management".
+\cgalAdvancedEnd
+
 \section Combinatorial_mapExamples Examples
 
 \subsection ssecexample3DCM A 3D Combinatorial Map

Combinatorial_map/doc/Combinatorial_map/Concepts/CombinatorialMap.h

@@ -710,12 +710,12 @@ void set_automatic_attributes_management(bool update_attributes);
 
 /*!
 Correct the invalid attributes of the combinatorial map.
-We can have invalid attribute either if we have called \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to use some modification operations.
+We can have invalid attribute either if we have called \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to use some modification operations or if we have modified the combinatorial map by using low level operations.
 
 \f$ \forall i \f$, 0 \f$ \leq \f$ i \f$ \leq \f$ \ref CombinatorialMap::dimension "dimension" such that the i-attributes are non void, \f$ \forall \f$ d \f$ \in\f$`darts()`:
  - if there exists a dart `d2` in the same i-cell than `d` with a different i-attribute, then the i-attribute of `d2` is set to the i-attribute of `d`;
  - if there exists a dart `d2` in a different i-cell than `d` with the same i-attribute, then the i-attribute of all the darts in i-cell(`d`) is set to a new i-attribute (copy of the original attribute);
- - ensure that \link CombinatorialMap::dart_of_attribute `dart_of_attribute(d)`\endlink \f$ \in \f$ i-cell(`d`).
+ - ensures that \link CombinatorialMap::dart_of_attribute `dart_of_attribute(d)`\endlink \f$ \in \f$ i-cell(`d`).
 */
 void correct_invalid_attributes();
 

Linear_cell_complex/doc/Linear_cell_complex/CGAL/Linear_cell_complex.h

@@ -266,7 +266,7 @@ void set_vertex_attribute(Dart_handle dh, Vertex_attribute_handle vh);
 /// @{
 /*!
 Correct the invalid attributes of the linear cell complex.
-We can have invalid attribute either if we have called \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to use some modification operations.
+We can have invalid attribute either if we have called \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink before to use some modification operations or if we have modified the combinatorial map by using low level operations.
 
 The validation process of a linear cell complex validates its combinatorial map (cf. \link CombinatorialMap::correct_invalid_attributes `correct_invalid_attributes()`\endlink), and for each dart `d` having no vertex attribute, a new vertex attribute is created, with its Point initialized to `CGAL::Origin`, and all the darts of the 0-cell containing `d` are linked with the new attribute.
 */

Linear_cell_complex/doc/Linear_cell_complex/Linear_cell_complex.txt

@@ -225,6 +225,11 @@ The \ref CombinatorialMap::unsew "unsew<3>" operation
 has removed the four \f$ \beta_3\f$ links, and has duplicated the 0-attributes
 since vertices are split in two after the unsew operation.
 
+\cgalAdvancedBegin
+If \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future sew and unsew operations will not update non void attributes. These attributes will be updated latter by the call to \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink.
+\cgalAdvancedEnd
+
+
 \subsection Linear_cell_complexConstructionOperations Construction Operations
 \anchor ssecconstructionsop
 
@@ -301,6 +306,10 @@ Example of \ref Linear_cell_complex::insert_dangling_cell_1_in_cell_2 "insert_da
 Some examples of use of these operations are given in
 Section \ref ssec5dexample "A 4D Linear Cell Complex".
 
+\cgalAdvancedBegin
+If \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink is called, all the future insertion or removal operations will not update non void attributes. These attributes will be updated latter by the call to \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(true)`\endlink. This can be useful to speed up an algorithm which uses several successive insertion and removal operations. See example \ref ssecAttributesManagement "Automatic attributes management".
+\cgalAdvancedEnd
+
 \section Linear_cell_complexExamples Examples
 
 \subsection Linear_cell_complexA3DLinearCellComplex A 3D Linear Cell Complex
@@ -424,6 +433,15 @@ set its color manually by using the result of
 \ref Linear_cell_complex::insert_barycenter_in_cell "insert_barycenter_in_cell<2>" which is a dart incident to the
 new vertex.
 
+\subsection Linear_cell_complexAutomaticAttributesManagement Automatic attributes management
+\anchor ssecAttributesManagement
+
+The following example illustrates the use of the automatic attributes management for a linear cell complex. An off file is loaded into a 2D linear cell complex embedded in 3D. Then, a certain percentage of edges is removed from the linear cell complex. The same method is applied twice: the first time by using the automatic attributes management (which is the default behaviour) and the second time by calling first  \link CombinatorialMap::set_automatic_attributes_management `set_automatic_attributes_management(false)`\endlink to disable the automatic updating of attributes.
+
+We can observe that the second run is faster than the first one. Indeed, updating attribute for each edge removal give a bigger complexity. Moreover, the gain increases when the percentage of removed edges increases.
+
+\cgalExample{Linear_cell_complex/linear_cell_complex_3_attributes_management.cpp}
+
 \section Linear_cell_complexDesign Design and Implementation History
 
 This package was developed by Guillaume Damiand, with the help of

Linear_cell_complex/examples/Linear_cell_complex/linear_cell_complex_3_attributes_management.cpp

@@ -10,7 +10,7 @@ typedef LCC_3::Dart_handle             Dart_handle;
 typedef LCC_3::Point                   Point;
 typedef LCC_3::FT                      FT;
 
-void load_and_simplify_off(LCC_3& lcc, std::string& filename,
+void load_and_simplify_off(LCC_3& lcc, const std::string& filename,
                            bool updateattribs, int percent)
 {
   std::ifstream ifile(filename.c_str());
@@ -20,20 +20,19 @@ void load_and_simplify_off(LCC_3& lcc, std::string& filename,
     CGAL::Timer timer;
     Dart_handle dh;
     std::size_t nb=(lcc.number_of_darts()*percent)/200;
-    timer.start();  
+    timer.start();
+
+    if (!updateattribs) lcc.set_automatic_attributes_management(false);
     for (LCC_3::Dart_range::iterator it=lcc.darts().begin(),
            itend=lcc.darts().end(); it!=itend && nb>0; )
     {
       dh=it++;
-      // if ( dh < lcc.beta<2>(dh) )
+      if ( it!=itend && it==lcc.beta<2>(dh) ) ++it;
-      // {
+      CGAL::remove_cell<LCC_3, 1>(lcc, dh);
-        if ( it!=itend && it==lcc.beta<2>(dh) ) ++it;      
+      --nb;
-        CGAL::remove_cell<LCC_3, 1>(lcc, dh, updateattribs);
-        --nb;
-      // }
     }
-    if ( !updateattribs ) lcc.correct_invalid_attributes();
+    if ( !updateattribs ) lcc.set_automatic_attributes_management(true);
-    
+
     timer.stop();
     lcc.display_characteristics(std::cout);
     std::cout<<", valid="<< lcc.is_valid()
@@ -48,31 +47,26 @@ int main(int narg, char** argv)
     std::cout<<"Usage: a.out file.off [percentage]"<<std::endl;
     return EXIT_FAILURE;
   }
-  
+
   std::string filename;
   if ( narg==1 )
   {
     filename=std::string("data/armadillo.off");
     std::cout<<"No filename given: use data/armadillo.off by default."<<std::endl;
   }
-  else
+  else filename=std::string(argv[1]);
-    filename=std::string(argv[1]);
 
-  int percent = 30; // remove 30 percent of edges 
+  int percent = 30; // remove 30 percent of edges
   if ( narg>2 ) { percent = atoi(argv[2]); }
   std::cout<<percent<<"% edges to remove."<<std::endl;
 
-  {
+  LCC_3 lcc;
-    LCC_3 lcc;
+  std::cout<<"Update attribute DURING operations: ";
-    std::cout<<"Update attribute DURING operations: ";
+  load_and_simplify_off(lcc, filename, true, percent);
-    load_and_simplify_off(lcc, filename, true, percent);
-  }
 
-  {
+  LCC_3 lcc2;
-    LCC_3 lcc2;
+  std::cout<<"Update attribute AFTER operations: ";
-    std::cout<<"Update attribute AFTER operations: ";
+  load_and_simplify_off(lcc2, filename, false, percent);
-    load_and_simplify_off(lcc2, filename, false, percent);
-  }
 
   return EXIT_SUCCESS;
 }