From 7b940e25a82a213a00f35239b11ea4934bbf427e Mon Sep 17 00:00:00 2001 From: Andreas Fabri Date: Thu, 6 Dec 2012 12:39:09 +0100 Subject: [PATCH] doc_tex -> doxygen of the Kernel_d documentation --- Kernel_23/doc/Kernel_23/CGAL/intersections.h | 17 +++++++ Kernel_d/doc/Kernel_d/CGAL/intersections_d.h | 46 ++++++++++++------- .../Kernel_d/Concepts/Kernel--Intersect_d.h | 7 +-- Kernel_d/doc/Kernel_d/Kernel_d.txt | 46 +++++++++++-------- 4 files changed, 76 insertions(+), 40 deletions(-) diff --git a/Kernel_23/doc/Kernel_23/CGAL/intersections.h b/Kernel_23/doc/Kernel_23/CGAL/intersections.h index 7e5276bf725..7e9f6c729d0 100644 --- a/Kernel_23/doc/Kernel_23/CGAL/intersections.h +++ b/Kernel_23/doc/Kernel_23/CGAL/intersections.h @@ -168,6 +168,23 @@ bool do_intersect(Type1 obj1, Type2 obj2, Type /// @} + + +/*! +\addtogroup intersection + +The macro `CGAL_INTERSECTION_VERSION` can be used to configure +which version of the `intersection()` function should be used and +enables the corresponding APIs in other \cgal packages. It should be +defined before any \cgal header is included. + +- `CGAL_INTERSECTION_VERSION == 1` `intersection()` uses `Object` +- `CGAL_INTERSECTION_VERSION == 2` `intersection()` uses `boost::optional< boost::variant< T... > >` + +*/ + +#define CGAL_INTERSECTION_VERSION + /*! \addtogroup intersection diff --git a/Kernel_d/doc/Kernel_d/CGAL/intersections_d.h b/Kernel_d/doc/Kernel_d/CGAL/intersections_d.h index bbbb547f8ab..b8cb01e8a60 100644 --- a/Kernel_d/doc/Kernel_d/CGAL/intersections_d.h +++ b/Kernel_d/doc/Kernel_d/CGAL/intersections_d.h @@ -26,21 +26,19 @@ bool do_intersect(Type1 obj1, Type2 obj2); /*! \ingroup PkgKernelDFunctions -returns the intersection result of \f$ f1\f$ and \f$ f2\f$ by means of -the polymorphic wrapper type `Object`. The returned object can be -tested for the intersection result and assigned by means of the -`object_cast` function. - +returns the intersection result of \f$ f1\f$ and \f$ f2\f$. \pre The objects are of the same dimension. -The possible value for types `Type1` and `Type2` and -the possible return values wrapped in `Object` are the following: +The same functionality is also available through the functor `Kernel::Intersect_d`. + +The possible value for types `Type1` and `Type2` and +the value for `T...` in `boost::optional< boost::variant< T... > >` are the following:
- + @@ -126,21 +124,35 @@ The following example demonstrates the most common use of \code #include + +template +struct Intersection_visitor { + typedef result_type void; + void operator()(const Point_d& p) const { /* handle point */ } + void operator()(const Segment_d& s) const { /* handle segment */ } +}; + template void foo(Segment_d seg, Line_d lin) { - Object result = intersection(seg, lin); - if (const Point_d *ipnt = object_cast >(&result) ) { - // handle the point intersection case with *ipnt. - } else if (const Segment_d *iseg = object_cast >(&result) ) { - // handle the segment intersection case with *iseg. - } else { - // handle the no intersection case. - } + // with C++11 support + // auto result = intersection(seg, lin); + + // without C++11 support + typename boost::result_of, Line_d)>::type + result = intersection(seg, lin); + + if(result) { boost::apply_visitor(Intersection_visitor(), *result); } + else { // no intersection + } } \endcode -\sa `do_intersect`, \sa `Kernel_d::Intersect_d` +\sa `do_intersect` +\sa `Kernel_d::Intersect_d` +\sa `boost::optional` +\sa `boost::variant` +\sa `boost::result_of` */ Object intersection(Type1 f1, Type2 f2); diff --git a/Kernel_d/doc/Kernel_d/Concepts/Kernel--Intersect_d.h b/Kernel_d/doc/Kernel_d/Concepts/Kernel--Intersect_d.h index bbcfb4ff4ae..1895e7bfb94 100644 --- a/Kernel_d/doc/Kernel_d/Concepts/Kernel--Intersect_d.h +++ b/Kernel_d/doc/Kernel_d/Concepts/Kernel--Intersect_d.h @@ -15,14 +15,15 @@ public: /*! returns the result of the intersection of \f$ p\f$ and \f$ q\f$ in form of a -polymorphic object. `Kernel_object` may be any of +polymorphic object. `Type1` and `Type2` may be any of `Kernel_d::Segment_d`, `Kernel_d::Ray_d`, `Kernel_d::Line_d`, `Kernel_d::Hyperplane_d`. \pre `p` and `q` have the same dimension. */ -template Object -operator()(const Kernel_object& p, const Kernel_object& q); + template +boost::result_of::type +operator()(const Type1& p, const Type2& q); /// @} diff --git a/Kernel_d/doc/Kernel_d/Kernel_d.txt b/Kernel_d/doc/Kernel_d/Kernel_d.txt index 6d97316fdd2..837e7776f1e 100644 --- a/Kernel_d/doc/Kernel_d/Kernel_d.txt +++ b/Kernel_d/doc/Kernel_d/Kernel_d.txt @@ -429,24 +429,22 @@ always cheaper. defined, especially integer types and rationals. -\subsection Kernel_dIntersectionandPolymorphicReturn Intersection and Polymorphic Return Values +\subsection Kernel_dIntersections Intersections Intersections on kernel objects currently cover only those objects that are part of flats (`Segment_d`, `Ray_d`, `Line_c`, and `Hyperplane_d`). For any pair of objects \f$ o1\f$, \f$ o2\f$ of these types the operation `intersection(o1,o2)` -returns a polymorphic object that wraps the result of the intersection -operation. +returns a `boost::optional< boost::variant< T... > >` +where `T...` is a list of all possible resulting geometric objects. + +The exact result type of an intersection can be determined by using +`boost::result_of::type` +`where `Type1` and `Type2` are the types of the objects +used in the intersection query. See +`boost::result_of` +for more information about this mechanism. -The class `Object` provides the polymorphic abstraction. An -object `obj` of type `Object` can represent an arbitrary -class. The only operations it provides is to make copies and -assignments, so that you can put them in lists or arrays. Note that -`Object` is NOT a common base class for the elementary classes. -Therefore, there is no automatic conversion from these classes to -`Object` Rather this is done with the global function -`make_object()`. This encapsulation mechanism requires the use of -`object_cast` to unwrap the encapsulated class. \subsubsection Kernel_dExample Example @@ -455,17 +453,25 @@ the intersection computation, as there are possibly different return values. \code{.cpp} -typedef Point_d< Cartesian_d > Point; -typedef Segment_d< Cartesian_d > Segment; +typedef Cartesian_d K; +typedef Point_d Point; +typedef Segment_d Segment; Segment s1, s2; std::cin >> s1 >> s2; -Object obj = intersection(s1, s2); -if (const Point *p = object_cast(&obj) ) { -// do something with *p -} else if (const Segment *s = object_cast(&obj) ) { -// do something with *s + +boost::result_of::type + v = intersection(s1, s2); +if(v) { + // not empty + if (const Point *p = boost::get(&*v) ) { + // do something with *p + } else { + const Segment *s = boost::get(&*v) ) { + // do something with *s + } +} else { + // empty intersection } -// there was no intersection \endcode \subsection Kernel_dConstructivePredicates Constructive Predicates
Type1 Type2 Return Type `T...`
Line_d