[Small Feature] Rename import functions with deprecation and add alias tests

Lab/demo/Lab/Plugins/IO/lcc_io_plugin.cpp

@@ -47,7 +47,7 @@ public:
     QString ext = fileinfo.suffix();
     bool res = true;
     if(ext == "off")
-      CGAL::import_from_polyhedron_3_flux < Scene_lcc_item::LCC > (lcc, ifs);
+      CGAL::polyhedron_3_flux_to_lcc < Scene_lcc_item::LCC > (lcc, ifs);
     else
     {
       res = CGAL::load_combinatorial_map(ifs, lcc);

Linear_cell_complex/demo/Linear_cell_complex/MainWindow.cpp

@@ -375,7 +375,7 @@ void MainWindow::load_off (const QString & fileName, bool clear)
 
   std::ifstream ifs (qPrintable (fileName));
 
-  CGAL::import_from_polyhedron_3_flux < LCC > (*scene.lcc, ifs);
+  CGAL::polyhedron_3_flux_to_lcc < LCC > (*scene.lcc, ifs);
 
 #ifdef CGAL_PROFILE_LCC_DEMO
   timer.stop();
@@ -415,7 +415,7 @@ void MainWindow::load_3DTDS (const QString & fileName, bool clear)
   T.insert (std::istream_iterator < Point_3 >(ifs),
             std::istream_iterator < Point_3 >() );
 
-  CGAL::import_from_triangulation_3 < LCC, Triangulation >(*scene.lcc, T);
+  CGAL::triangulation_3_to_lcc < LCC, Triangulation >(*scene.lcc, T);
 
 #ifdef CGAL_PROFILE_LCC_DEMO
   timer.stop();
@@ -673,7 +673,7 @@ void MainWindow::on_actionCompute_Voronoi_3D_triggered ()
   std::map<Triangulation::Cell_handle,
       LCC::Dart_descriptor > vol_to_dart;
 
-  dh = CGAL::import_from_triangulation_3 < LCC, Triangulation >
+  dh = CGAL::triangulation_3_to_lcc < LCC, Triangulation >
       (delaunay_lcc, T, &vol_to_dart);
 
   Dart_descriptor ddh=delaunay_lcc.dual(*scene.lcc, dh);

Linear_cell_complex/doc/Linear_cell_complex/CGAL/Linear_cell_complex_constructors.h

@@ -24,13 +24,21 @@ Here a small example:
 <B>Middle</B>: the 2D linear cell complex reconstructed if combinatorial maps are the combinatorial data-structure.
 <B>Right</B>: the 2D linear cell complex reconstructed if generalized maps are the combinatorial data-structure.
 
-\sa `CGAL::import_from_triangulation_3<LCC,Triangulation>`
-\sa `CGAL::import_from_polyhedron_3<LCC,Polyhedron>`
+\sa `CGAL::triangulation_3_to_lcc<LCC,Triangulation>` (formerly `import_from_triangulation_3`)
+\sa `CGAL::polyhedron_3_to_lcc<LCC,Polyhedron>` (formerly `import_from_polyhedron_3`)
 
 */
 template<class LCC>
-typename LCC::Dart_descriptor import_from_plane_graph(LCC& lcc,
+typename LCC::Dart_descriptor plane_graph_to_lcc(LCC& lcc,
 std::istream& ais);
 
+/*!
+\ingroup PkgLinearCellComplexConstructions
+\deprecated Use `plane_graph_to_lcc()` instead.
+*/
+template<class LCC>
+[[deprecated("Use plane_graph_to_lcc instead")]]
+typename LCC::Dart_descriptor import_from_plane_graph(LCC& lcc, std::istream& ais);
+
 } /* namespace CGAL */
 

Linear_cell_complex/doc/Linear_cell_complex/CGAL/Polyhedron_3_to_lcc.h

@@ -5,10 +5,10 @@ namespace CGAL{
 Imports `apoly` (a `Polyhedron_3`) into `lcc`, a model of the `LinearCellComplex` concept. Objects are added in `lcc`, existing darts are not modified. Returns a dart created during the import.
 \pre \link GenericMap::dimension `LCC::dimension`\endlink \f$ \geq\f$ 2 and \link LinearCellComplex::ambient_dimension `LCC::ambient_dimension`\endlink==3.
 
-\sa `CGAL::import_from_plane_graph<LCC>`
-\sa `CGAL::import_from_triangulation_3<LCC,Triangulation>`
+\sa `CGAL::plane_graph_to_lcc<LCC>` (formerly `import_from_plane_graph`)
+\sa `CGAL::triangulation_3_to_lcc<LCC,Triangulation>` (formerly `import_from_triangulation_3`)
 */
 template<class LCC,class Polyhedron>
-typename LCC::Dart_descriptor import_from_polyhedron_3(LCC& lcc,
+typename LCC::Dart_descriptor polyhedron_3_to_lcc(LCC& lcc,
 const Polyhedron &apoly);
 }

Linear_cell_complex/doc/Linear_cell_complex/CGAL/Triangulation_3_to_lcc.h

@@ -3,13 +3,24 @@ namespace CGAL{
 /*!
 \ingroup PkgLinearCellComplexConstructions
 
-Imports `atr` (a `Triangulation_3`) into `lcc`, a model of the `LinearCellComplex` concept. Objects are added in `lcc`, existing darts are not modified. Returns a dart created during the import.
-\pre \link GenericMap::dimension `LCC::dimension`\endlink \f$ \geq\f$ 3 and \link LinearCellComplex::ambient_dimension `LCC::ambient_dimension`\endlink==3.
+Imports `atr` (a `Triangulation_3`) into `lcc`, a model of the `LinearCellComplex` concept.
+Objects are added in `lcc`, existing darts are not modified. Returns a dart created during the import.
+\pre \link GenericMap::dimension `LCC::dimension`\endlink \f$ \geq\f$ 3 and
+      \link LinearCellComplex::ambient_dimension `LCC::ambient_dimension`\endlink==3.
 
-\sa `CGAL::import_from_plane_graph<LCC>`
-\sa `CGAL::import_from_polyhedron_3<LCC,Polyhedron>`
+\sa `CGAL::triangulation_3_to_lcc<LCC,Triangulation>` (formerly `import_from_triangulation_3`)
+\sa `CGAL::plane_graph_to_lcc<LCC>` (formerly `import_from_plane_graph`)
+/// \sa `CGAL::polyhedron_3_to_lcc<LCC,Polyhedron>` (formerly `import_from_polyhedron_3`)
 */
+
 template <class LCC,class Triangulation_>
-typename LCC::Dart_descriptor import_from_triangulation_3(LCC& lcc,
-const Triangulation_&atr);
+typename LCC::Dart_descriptor triangulation_3_to_lcc(LCC& lcc, const Triangulation_&atr);
+
+template <class LCC, class Triangulation_>
+[[deprecated("Use triangulation_3_to_lcc instead")]]
+typename LCC::Dart_descriptor import_from_triangulation_3(LCC& lcc, const Triangulation_& atr)
+{
+  return triangulation_3_to_lcc(lcc, atr);
+}
+
 }

Linear_cell_complex/doc/Linear_cell_complex/Concepts/LinearCellComplexTraits.h

@@ -64,8 +64,7 @@ which constructs a vector as the difference of points `p2-p1`, and
 \link LinearCellComplexTraits::Vector ` Vector `\endlink `operator() (const CGAL::Origin&, const ` \link Point ` Point`\endlink`& p)`
 which constructs a vector as the difference of point `p` and a point at the origin
 (used in \link CGAL::barycenter `barycenter`\endlink
-and `CGAL::import_from_plane_graph`).
-*/
+and `CGAL::plane_graph_to_lcc`, formerly `import_from_plane_graph`).
 typedef unspecified_type Construct_vector;
 
 /*!
@@ -104,7 +103,7 @@ a model of \link Kernel::Direction_2 `Direction_2`\endlink.
 typedef unspecified_type Direction_2;
 
 /*!
-a model of \link Kernel::ConstructDirection_2 `ConstructDirection_2`\endlink (used in `CGAL::import_from_plane_graph`).
+a model of \link Kernel::ConstructDirection_2 `ConstructDirection_2`\endlink (used in `CGAL::plane_graph_to_lcc`, formerly `import_from_plane_graph`).
 */
 typedef unspecified_type Construct_direction_2;
 

Linear_cell_complex/doc/Linear_cell_complex/Linear_cell_complex.txt

@@ -105,11 +105,11 @@ There are several member functions allowing to insert specific configurations of
 
 There are two functions allowing to build a linear cell complex from two other \cgal data types:
 <UL>
-<LI>\link ::import_from_triangulation_3 `import_from_triangulation_3(lcc,atr)`\endlink: adds in `lcc` all the tetrahedra present in `atr`, a \link CGAL::Triangulation_3 `Triangulation_3`\endlink;
-<LI>\link ::import_from_polyhedron_3 `import_from_polyhedron_3(lcc,ap)`\endlink: adds in `lcc` all the cells present in `ap`, a `Polyhedron_3`.
+<LI>\link ::triangulation_3_to_lcc `triangulation_3_to_lcc(lcc,atr)`\endlink: adds in `lcc` all the tetrahedra present in `atr`, a \link CGAL::Triangulation_3 `Triangulation_3`\endlink; (formerly `import_from_triangulation_3`)
+<LI>\link ::polyhedron_3_to_lcc `polyhedron_3_to_lcc(lcc,ap)`\endlink: adds in `lcc` all the cells present in `ap`, a `Polyhedron_3`. (formerly `import_from_polyhedron_3`)
 </UL>
 
-Lastly, the function \link ::import_from_plane_graph `import_from_plane_graph(lcc,ais)`\endlink adds in `lcc` all the cells reconstructed from the planar graph read in `ais`, a `std::istream` (see the  \link ::import_from_plane_graph `reference manual`\endlink for the file format).
+Lastly, the function \link ::plane_graph_to_lcc `plane_graph_to_lcc(lcc,ais)`\endlink (formerly `import_from_plane_graph`) adds in `lcc` all the cells reconstructed from the planar graph read in `ais`, a `std::istream` (see the \link ::plane_graph_to_lcc `reference manual`\endlink for the file format).
 
 \subsection Linear_cell_complexModificationOperations Modification Operations
 \anchor ssecmodifop

Linear_cell_complex/doc/Linear_cell_complex/PackageDescription.txt

@@ -62,9 +62,10 @@
 
 \cgalCRPSection{Global Functions}
 \cgalCRPSubsection{Constructions for Linear Cell Complex}
-- `CGAL::import_from_plane_graph<LCC>`
-- `CGAL::import_from_triangulation_3<LCC,Triangulation>`
-- `CGAL::import_from_polyhedron_3<LCC,Polyhedron>`
+- `CGAL::plane_graph_to_lcc<LCC>` (formerly `import_from_plane_graph`)
+- `CGAL::triangulation_3_to_lcc<LCC,Triangulation>` (formerly `import_from_triangulation_3`)
+- `CGAL::polyhedron_3_to_lcc<LCC,Polyhedron>` (formerly `import_from_polyhedron_3`)
+- `CGAL::polyhedron_3_flux_to_lcc<LCC>` (formerly `import_from_polyhedron_3_flux`)
 
 \cgalCRPSubsection{Operations for Linear Cell Complex}
 - `CGAL::compute_normal_of_cell_0<LCC>`

Linear_cell_complex/examples/Linear_cell_complex/plane_graph_to_lcc_2.cpp

@@ -42,7 +42,7 @@ int main(int narg, char** argv)
 
   std::ifstream is(filename.c_str());
   std::cout<<"Import plane graph from "<<filename<<std::endl;
-  CGAL::import_from_plane_graph(lcc, is);
+  CGAL::plane_graph_to_lcc(lcc, is);
 
   // Display the lcc characteristics.
   std::cout<<"LCC characteristics:"<<std::endl<<"  ";

Linear_cell_complex/examples/Linear_cell_complex/voronoi_3.cpp

@@ -134,7 +134,7 @@ int main(int narg, char** argv)
   std::map<Triangulation::Cell_handle,
            LCC_3::Dart_descriptor > vol_to_dart;
 
-  Dart_descriptor d=CGAL::import_from_triangulation_3<LCC_3, Triangulation>
+  Dart_descriptor d=CGAL::triangulation_3_to_lcc<LCC_3, Triangulation>
     (lcc, T, &vol_to_dart);
 
   std::cout<<"Delaunay triangulation :"<<std::endl<<"  ";

Linear_cell_complex/include/CGAL/Linear_cell_complex_constructors.h

@@ -36,7 +36,7 @@ namespace CGAL {
    * Imports a plane-embedded graph from a list of points and edges represented as pairs of vertex indices
    */
   template< class LCC >
-  typename LCC::Dart_descriptor import_from_plane_graph(LCC& alcc,
+  typename LCC::Dart_descriptor plane_graph_to_lcc(LCC& alcc,
                                                    const std::vector<typename LCC::Point>& vertices,
                                                    const std::vector<size_t>& edge_indices)
   {
@@ -130,6 +130,16 @@ namespace CGAL {
     return first;
   }
 
+template< class LCC >
+[[deprecated("Use plane_graph_to_lcc instead")]]
+typename LCC::Dart_descriptor
+import_from_plane_graph(LCC& alcc,
+                        const std::vector<typename LCC::Point>& vertices,
+                        const std::vector<size_t>& edge_indices)
+{
+  return plane_graph_to_lcc(alcc, vertices, edge_indices);
+}
+
   /**
    * Imports a plane-embedded graph from a file into a LinearCellComplex.
    *
@@ -138,7 +148,7 @@ namespace CGAL {
    * @return A dart created during the conversion.
    */
   template< class LCC >
-  typename LCC::Dart_descriptor import_from_plane_graph(LCC& alcc,
+  typename LCC::Dart_descriptor plane_graph_to_lcc(LCC& alcc,
                                                     std::istream& ais)
   {
     using FT = typename LCC::FT;
@@ -185,18 +195,36 @@ namespace CGAL {
       edge_indices.push_back(v2);
     }
 
-    return import_from_plane_graph(alcc, vertices, edge_indices);
+    return plane_graph_to_lcc(alcc, vertices, edge_indices);
   }
 
+template <class LCC>
+[[deprecated("Use plane_graph_to_lcc instead")]]
+typename LCC::Dart_descriptor
+import_from_plane_graph(LCC& alcc, std::istream& ais)
+{
+  return plane_graph_to_lcc(alcc, ais);
+}
+
   template < class LCC >
   typename LCC::Dart_descriptor
-  import_from_plane_graph(LCC& alcc, const char* filename)
+  iplane_graph_to_lcc(LCC& alcc, const char* filename)
   {
     std::ifstream input(filename);
     if (!input.is_open()) return alcc.null_descriptor;
-    return import_from_plane_graph(alcc, input);
+    return plane_graph_to_lcc(alcc, input);
   }
 
+template <class LCC>
+[[deprecated("Use plane_graph_to_lcc instead")]]
+typename LCC::Dart_descriptor
+import_from_plane_graph(LCC& alcc, const char* filename)
+{
+  std::ifstream input(filename);
+  if (!input.is_open()) return alcc.null_descriptor;
+  return plane_graph_to_lcc(alcc, input); 
+}
+
   template < class LCC >
   bool load_off(LCC& alcc, std::istream& in)
   {

Linear_cell_complex/test/Linear_cell_complex/CMakeLists.txt

@@ -15,6 +15,9 @@ create_single_source_cgal_program(Linear_cell_complex_3_test.cpp ${hfiles})
 create_single_source_cgal_program(Linear_cell_complex_4_test.cpp ${hfiles})
 create_single_source_cgal_program(Linear_cell_complex_copy_test.cpp ${hfiles})
 create_single_source_cgal_program(LCC_3_incremental_builder_test.cpp ${hfiles})
+create_single_source_cgal_program(test_triangulation_alias.cpp ${hfiles})
+create_single_source_cgal_program(test_polyhedron_3_alias.cpp ${hfiles})
+create_single_source_cgal_program(test_plane_graph_alias.cpp ${hfiles})
 
 # Same targets, defining USE_COMPACT_CONTAINER_WITH_INDEX to test index version
 add_executable(Linear_cell_complex_2_test_index Linear_cell_complex_2_test.cpp ${hfiles})

Linear_cell_complex/test/Linear_cell_complex/Linear_cell_complex_2_test.h

@@ -382,7 +382,7 @@ bool test_LCC_2()
       std::cout<<"Error: impossible to open 'data/graph.txt'"<<std::endl;
       return false;
     }
-    CGAL::import_from_plane_graph<LCC>(lcc,in);
+    CGAL::plane_graph_to_lcc<LCC>(lcc,in);
     if ( !check_number_of_cells_2(lcc, 66, 166, 104, 2) )
       return false;
     lcc.clear();
@@ -431,7 +431,7 @@ struct Test_change_orientation_LCC_2<LCC, CGAL::Combinatorial_map_tag>
       std::cout<<"Error: impossible to open 'data/graph.txt'"<<std::endl;
       return false;
     }
-    CGAL::import_from_plane_graph<LCC>(lcc,in);
+    CGAL::plane_graph_to_lcc<LCC>(lcc,in);
 
     trace_test_begin();
 

Linear_cell_complex/test/Linear_cell_complex/Linear_cell_complex_3_test.h

@@ -997,7 +997,7 @@ bool test_LCC_3()
     }
     in >> P;
 
-    CGAL::import_from_polyhedron_3<LCC>(lcc,P);
+    CGAL::polyhedron_3_flux_to_lcc<LCC>(lcc,P);
     if ( !check_number_of_cells_3(lcc, 1539, 4434, 2894, 2, 2) )
       return false;
 
@@ -1029,7 +1029,7 @@ bool test_LCC_3()
     }
     T.insert ( std::istream_iterator < Point >(in),
                std::istream_iterator < Point >() );
-    CGAL::import_from_triangulation_3<LCC>(lcc,T);
+    CGAL::triangulation_3_to_lcc<LCC>(lcc,T);
     if ( !lcc.is_valid() )
       return false;
 

Linear_cell_complex/test/Linear_cell_complex/test_plane_graph_alias.cpp

@@ -0,0 +1,29 @@
+#include <CGAL/Linear_cell_complex_for_combinatorial_map.h>
+#include <CGAL/Linear_cell_complex_constructors.h>
+#include <cassert>
+#include <sstream>
+
+typedef CGAL::Linear_cell_complex_for_combinatorial_map<2> LCC;
+
+int main()
+{
+  LCC lcc1, lcc2;
+
+  // Planar graph with 3 vertices and 3 edges (triangle)
+  std::stringstream input;
+  input << "3 3\n0.0 0.0\n1.0 0.0\n0.0 1.0\n0 1\n1 2\n2 0\n";
+
+  // Test new function
+  auto d1 = CGAL::plane_graph_to_lcc(lcc1, input);
+  assert(d1 != LCC::null_descriptor);
+
+  // Rewind input stream for second test
+  input.clear();
+  input.seekg(0, std::ios::beg);
+
+  // Test deprecated function
+  auto d2 = CGAL::import_from_plane_graph(lcc2, input);
+  assert(d2 != LCC::null_descriptor);
+
+  return 0;
+}

Linear_cell_complex/test/Linear_cell_complex/test_polyhedron_3_alias.cpp

@@ -0,0 +1,26 @@
+#include <CGAL/Linear_cell_complex_for_combinatorial_map.h>
+#include <CGAL/Polyhedron_3.h>
+#include <CGAL/Polyhedron_3_to_lcc.h> 
+#include <sstream>
+#include <cassert>
+
+typedef CGAL::Linear_cell_complex_for_combinatorial_map<3> LCC;
+typedef CGAL::Polyhedron_3<LCC::Traits> Polyhedron;
+
+int main()
+{
+  std::stringstream ss("OFF\n0 0 0\n");
+
+  Polyhedron P;
+  ss >> P;
+
+  LCC lcc1, lcc2;
+
+  auto d1 = CGAL::polyhedron_3_to_lcc(lcc1, P); 
+  assert(d1 == LCC::null_descriptor);
+
+  auto d2 = CGAL::import_from_polyhedron_3<LCC>(lcc2, P); 
+  assert(d2 == LCC::null_descriptor);
+
+  return 0;
+}

Linear_cell_complex/test/Linear_cell_complex/test_triangulation_alias.cpp

@@ -0,0 +1,23 @@
+#include <CGAL/Linear_cell_complex_for_combinatorial_map.h>
+#include <CGAL/Delaunay_triangulation_3.h>
+#include <CGAL/Triangulation_3_to_lcc.h>
+#include <cassert>
+
+typedef CGAL::Linear_cell_complex_for_combinatorial_map<3> LCC_3;
+typedef CGAL::Delaunay_triangulation_3<LCC_3::Traits> Triangulation;
+
+int main()
+{
+  LCC_3 lcc1, lcc2;
+  Triangulation T;
+
+  assert(T.dimension() == -1);
+
+  auto d1 = CGAL::triangulation_3_to_lcc(lcc1, T);
+  assert(d1 == LCC_3::null_descriptor);
+
+  auto d2 = CGAL::import_from_triangulation_3(lcc2, T);
+  assert(d2 == LCC_3::null_descriptor);
+
+  return 0;
+}

Polyhedron/include/CGAL/Polyhedron_3_to_lcc.h

@@ -30,7 +30,7 @@ namespace CGAL {
    * @return A dart created during the conversion.
    */
   template< class LCC, class Polyhedron >
-  typename LCC::Dart_descriptor import_from_polyhedron_3(LCC& alcc,
+  typename LCC::Dart_descriptor polyhedron_3_to_lcc(LCC& alcc,
                                                      const Polyhedron &apoly)
   {
     static_assert( LCC::dimension>=2 && LCC::ambient_dimension==3 );
@@ -94,6 +94,14 @@ namespace CGAL {
     return firstAll;
   }
 
+template< class LCC, class Polyhedron >
+[[deprecated("Use polyhedron_3_to_lcc instead")]]
+typename LCC::Dart_descriptor
+import_from_polyhedron_3(LCC& alcc, const Polyhedron &apoly)
+{
+  return polyhedron_3_to_lcc<LCC, Polyhedron>(alcc, apoly);
+}
+
   /** Convert a Polyhedron_3 read into a flux into 3D linear cell complex.
    * @param alcc the linear cell complex where Polyhedron_3 will be converted.
    * @param ais the istream where read the Polyhedron_3.
@@ -101,7 +109,7 @@ namespace CGAL {
    */
   template < class LCC >
   typename LCC::Dart_descriptor
-  import_from_polyhedron_3_flux(LCC& alcc, std::istream& ais)
+  polyhedron_3_flux_to_lcc(LCC& alcc, std::istream& ais)
   {
     if (!ais.good())
     {
@@ -110,10 +118,18 @@ namespace CGAL {
     }
     CGAL::Polyhedron_3<typename LCC::Traits> P;
     ais >> P;
-    return import_from_polyhedron_3<LCC, CGAL::Polyhedron_3
+    return polyhedron_3_to_lcc<LCC, CGAL::Polyhedron_3
                                     <typename LCC::Traits> > (alcc, P);
   }
 
+template < class LCC >
+[[deprecated("Use polyhedron_3_flux_to_lcc instead")]]
+typename LCC::Dart_descriptor
+import_from_polyhedron_3_flux(LCC& alcc, std::istream& ais)
+{
+  return polyhedron_3_flux_to_lcc(alcc, ais);
+}
+
 } // namespace CGAL
 
 #endif // CGAL_IMPORT_FROM_POLYHEDRON_3_H

Triangulation_3/include/CGAL/Triangulation_3_to_lcc.h

@@ -47,7 +47,7 @@ namespace CGAL {
    * @return A dart incident to the infinite vertex.
    */
   template < class LCC, class Triangulation >
-  typename LCC::Dart_descriptor import_from_triangulation_3
+  typename LCC::Dart_descriptor triangulation_3_to_lcc
   (LCC& alcc, const Triangulation &atr,
    std::map<typename Triangulation::Cell_handle,
             typename LCC::Dart_descriptor >* avol_to_dart=nullptr)
@@ -149,6 +149,16 @@ namespace CGAL {
     return dart;
   }
 
+  template < class LCC, class Triangulation >
+[[deprecated("Use triangulation_3_to_lcc instead")]]
+typename LCC::Dart_descriptor import_from_triangulation_3
+(LCC& alcc, const Triangulation &atr,
+ std::map<typename Triangulation::Cell_handle,
+          typename LCC::Dart_descriptor >* avol_to_dart=nullptr)
+{
+  return triangulation_3_to_lcc(alcc, atr, avol_to_dart);
+}
+
 } // namespace CGAL
 
 #endif // CGAL_TRIANGULATION_3_TO_LCC_H