From 96c5d90243bc3a19eb119279a5c5d63fdd99464b Mon Sep 17 00:00:00 2001 From: Simon Giraudot Date: Mon, 31 Aug 2020 11:13:22 +0200 Subject: [PATCH] Update BSO documentation with polyline traits selection --- .../Boolean_set_operations_2.txt | 30 +- .../CGAL/Boolean_set_operations_2.h | 446 +++++++++++++++--- 2 files changed, 421 insertions(+), 55 deletions(-) diff --git a/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt b/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt index 9529d732022..606e9c32a45 100644 --- a/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt +++ b/Boolean_set_operations_2/doc/Boolean_set_operations_2/Boolean_set_operations_2.txt @@ -518,6 +518,35 @@ Polygon_set_2 S; S.join (begin, end); \endcode +\subsection bso_ssectraits_sel Traits Selection + +When calling boolean set operations on `Polygon_2` or +`Polygon_with_holes_2` objects, a `General_polygon_set_2` is +instantiated internally. This polygon set is templated by a traits +class that is automatically deduced from the polygon type and that can +either be based on: + +- `Arr_polyline_traits_2`: in that case, the polygon is first +decomposed into a set of \f$ x\f$-monotone polylines. This is the +default behavior. + +- `Arr_segment_traits_2`: in that case, every edge of the polygon is +considered as a single \f$ x\f$-monotone curve. + +The traits are selected via a template parameter `UsePolylineTraits` +which is `CGAL::Tag_true` by default: the polyline version is +generally significantly faster than the segment version as considering +\f$ x\f$-monotone polylines reduces the number of events of the +sweep-line algorithm. + +Nevertheless, in some specific cases, users can find the segment +version to be faster: if a \f$ x\f$-monotone polyline from an input +polygon intersects many times another \f$ x\f$-monotone polyline from +another input polygon, then it becomes counter-productive to consider +polylines instead of segments. In that case, users can fallback to the +segment variant by using `CGAL::Tag_false` for the `UsePolylineTraits` +template parameter. + \section bso_secbso_gen Boolean Set-Operations on General Polygons \image html general_polygon.png @@ -781,4 +810,3 @@ line. */ } /* namespace CGAL */ - diff --git a/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h b/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h index 4f1ed78e348..bf32cd00813 100644 --- a/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h +++ b/Boolean_set_operations_2/doc/Boolean_set_operations_2/CGAL/Boolean_set_operations_2.h @@ -27,9 +27,16 @@ the `complement function` writes them into an output iterator /*! writes the complement of the polygon `pgn` into the polygon with holes `res`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template -void complement(const Polygon_2 & pgn, Polygon_with_holes_2 & res); +template +void complement(const Polygon_2 & pgn, Polygon_with_holes_2 & res, + UsePolylineTraits = UsePolylineTraits()); /*! writes the complement of the general polygon `pgn` into the general polygon with holes `res`. @@ -40,9 +47,16 @@ void complement(const General_polygon_2 & pgn, General_polygon_with_hole /*! writes the complement of the polygon with holes `pgn` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template -OutputIterator complement(const Polygon_with_holes_2 & pgn, OutputIterator oi); +template +OutputIterator complement(const Polygon_with_holes_2 & pgn, OutputIterator oi, + UsePolylineTraits = UsePolylineTraits()); /*! writes the complement of the general polygon with holes `pgn` into the output iterator `oi`. @@ -102,38 +116,62 @@ The types of the parameters of the `difference()` function are any of the follow /*! writes the difference of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator difference(const Polygon_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the difference of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator difference(const Polygon_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the difference of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator difference(const Polygon_with_holes_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the difference of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator difference(const Polygon_with_holes_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the difference of the general polygons `p1` and `p2` into the output iterator `oi`. @@ -220,33 +258,60 @@ The types of the parameters of the \link ref_bso_do_intersect `do_intersect()` \ /*! returns `true` if the polygons `p1` and `p2` intersect in their interior. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool do_intersect(const Polygon_2 & p1, - const Polygon_2 & p2); + const Polygon_2 & p2, + UsePolylineTraits = UsePolylineTraits()); /*! returns `true` if the polygons `p1` and `p2` intersect in their interior. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool do_intersect(const Polygon_2 & p1, - const Polygon_with_holes_2 & p2); + const Polygon_with_holes_2 & p2, + UsePolylineTraits = UsePolylineTraits()); /*! returns `true` if the polygons `p1` and `p2` intersect in their interior. returns `true` if the interior of polygons `p1` and `p2` intersect. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool do_intersect(const Polygon_with_holes_2 & p1, - const Polygon_2 & p2); + const Polygon_2 & p2, + UsePolylineTraits = UsePolylineTraits()); /*! returns `true` if the polygons `p1` and `p2` intersect in their interior. + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool do_intersect(const Polygon_with_holes_2 & p1, - const Polygon_with_holes_2 & p2); + const Polygon_with_holes_2 & p2, + UsePolylineTraits = UsePolylineTraits()); /*! returns `true` if the general polygons `p1` and `p2` intersect in their interior. @@ -286,6 +351,22 @@ bool do_intersect(const General_polygon_with_holes_2 & p1, template bool do_intersect(InputIterator begin, InputIterator end); + /*! + returns `true`, if the set of `Polygon_2` (or + `Polygon_with_holes_2`) in the given range intersect in their + interior, and `false` otherwise. (The value type of the input + iterator is used to distinguish between the two). + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. + */ +template +bool do_intersect(InputIterator begin, InputIterator end, + UsePolylineTraits = UsePolylineTraits()); + /*! returns `true`, if the set of general polygons and general polygons with holes in the given two ranges respectively intersect in @@ -296,6 +377,24 @@ bool do_intersect(InputIterator1 pgn_begin1, InputIterator1 pgn_end1, InputIterator2 pgn_begin2, InputIterator2 pgn_end2); + + /*! + returns `true`, if the set of `Polygon_2` and + `Polygon_with_holes_2` in the given two ranges respectively + intersect in their interior, and `false` otherwise. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. + */ +template +bool do_intersect(InputIterator1 pgn_begin1, + InputIterator1 pgn_end1, + InputIterator2 pgn_begin2, + InputIterator2 pgn_end2, + UsePolylineTraits = UsePolylineTraits()); /// @} } /* namespace CGAL */ @@ -359,38 +458,62 @@ OutputIterator intersection(const Type1 & p1, const Type2 & p2, /*! writes the intersection of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator intersection(const Polygon_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the intersection of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator intersection(const Polygon_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the intersection of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator intersection(const Polygon_with_holes_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the intersection of the polygons `p1` and `p2` into the output iterator `oi`. The value type of `oi` is `Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template OutputIterator intersection(const Polygon_with_holes_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); /*! writes the intersection of the general polygons `p1` and `p2` into the output iterator `oi`. @@ -441,6 +564,25 @@ template OutputIterator intersection(InputIterator begin, InputIterator end, OutputIterator oi); +/*! + computes the intersection of the `Polygon_2` objects (or + `Polygon_with_holes_2` objects) in the given range. (The value type + of the input iterator is used to distinguish between the two.) The + result, represented by a set of general polygon with holes, is + written into the output iterator `oi`. The output iterator is + returned. The value type of the `OutputIterator` is + `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template +OutputIterator intersection(InputIterator begin, InputIterator end, + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); + /*! computes the intersection of the general polygons and general polygons with holes in the given two ranges. The result, represented by a set @@ -456,6 +598,29 @@ InputIterator2 pgn_begin2, InputIterator2 pgn_end2, OutputIterator oi); +/*! + computes the intersection of the `Polygon_2` objects and + `Polygon_with_holes_2` object in the given two ranges. The result, + represented by a set of general polygon with holes, is written into + the output iterator `oi`. The output iterator is returned. The + value type of the `OutputIterator` is + `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template +OutputIterator intersection(InputIterator1 pgn_begin1, +InputIterator1 pgn_end1, +InputIterator2 pgn_begin2, +InputIterator2 pgn_end2, +OutputIterator oi, +UsePolylineTraits = UsePolylineTraits()); + /// @} } /* namespace CGAL */ @@ -507,41 +672,69 @@ The types of the parameters of the `join()` function are any of the following co /*! writes the union of the polygons `p1` and `p2` into the polygon with holes `res`. Returns `true` if the two given polygons overlap. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool join(const Polygon_2 & p1, const Polygon_2 & p2, - General_polygon_with_holes_2 > & res); + General_polygon_with_holes_2 > & res, + UsePolylineTraits = UsePolylineTraits()); /*! writes the union of the polygons `p1` and `p2` into the polygon with holes `res`. Returns `true` if the two given polygons overlap. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool join(const Polygon_2 & p1, const Polygon_with_holes_2 & p2, - General_polygon_with_holes_2 > & res); + General_polygon_with_holes_2 > & res, + UsePolylineTraits = UsePolylineTraits()); /*! writes the union of the polygons `p1` and `p2` into the polygon with holes `res`. Returns `true` if the two given polygons overlap. - */ -template + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template bool join(const Polygon_with_holes_2 & p2, const Polygon_2 & p1, - General_polygon_with_holes_2 > & res); + General_polygon_with_holes_2 > & res, + UsePolylineTraits = UsePolylineTraits()); /*! writes the union of the polygons `p1` and `p2` into the polygon with holes `res`. Returns `true` if the two given polygons overlap. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. */ -template +template bool join(const Polygon_with_holes_2 & p2, const Polygon_with_holes_2 & p1, - General_polygon_with_holes_2 > & res); + General_polygon_with_holes_2 > & res, + UsePolylineTraits = UsePolylineTraits()); /*! @@ -597,6 +790,25 @@ template OutputIterator join(InputIterator begin, InputIterator end, OutputIterator oi); +/*! + computes the union of the `Polygon_2` objects (or + `Polygon_with_holes_2` objects) in the given range. (The value type + of the input iterator is used to distinguish between the two.) The + result, represented by a set of general polygon with holes, is + written into the output iterator `oi`. The output iterator is + returned. The value type of the `OutputIterator` is + `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template +OutputIterator join(InputIterator begin, InputIterator end, +OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); + /*! computes the union of the general polygons and general polygons with holes in the given two ranges. The result, represented by a set @@ -611,6 +823,26 @@ OutputIterator join(InputIterator1 pgn_begin1, InputIterator1 pgn_end1, InputIterator2 pgn_begin2, InputIterator2 pgn_end2, OutputIterator oi); + /*! + computes the union of the `Polygon_2` objects and + `Polygon_with_holes_2` objects in the given two ranges. The + result, represented by a set of general polygon with holes, is + written into the output iterator `oi`. The output iterator is + returned. The value type of the `OutputIterator` is + `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. + */ +template +OutputIterator join(InputIterator1 pgn_begin1, InputIterator1 pgn_end1, +InputIterator2 pgn_begin2, InputIterator2 pgn_end2, +OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); + /// @} } /* namespace CGAL */ @@ -654,24 +886,57 @@ The types of the parameters of the `oriented_side()` function are any of the fol /// @{ -template + +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template Oriented_side oriented_side(const Polygon_2 & p1, - const Polygon_2 & p2); + const Polygon_2 & p2, + UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template Oriented_side oriented_side(const Polygon_2 & p1, - const Polygon_with_holes_2 & p2); + const Polygon_with_holes_2 & p2, + UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template Oriented_side oriented_side(const Polygon_with_holes_2 & p1, - const Polygon_2 & p2); + const Polygon_2 & p2, + UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template Oriented_side oriented_side(const Polygon_with_holes_2 & p1, - const Polygon_with_holes_2 & p2); + const Polygon_with_holes_2 & p2, + UsePolylineTraits = UsePolylineTraits()); template @@ -745,30 +1010,59 @@ OutputIterator symmetric_difference(const Type1 & p1, const Type2 & p2, OutputIterator oi); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template OutputIterator symmetric_difference(const Polygon_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, + UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template OutputIterator symmetric_difference(const Polygon_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template OutputIterator symmetric_difference(const Polygon_with_holes_2 & p1, const Polygon_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); -template +/*! + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. +*/ +template OutputIterator symmetric_difference(const Polygon_with_holes_2 & p1, const Polygon_with_holes_2 & p2, - OutputIterator oi); + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); template @@ -812,6 +1106,27 @@ template OutputIterator symmetric_difference(InputIterator begin, InputIterator end, OutputIterator oi); + /*! + computes the symmetric difference of the `Polygon_2` objects (or + `Polygon_with_holes_2` objects) in the given range. A point is + contained in the symmetric difference, if and only if it is + contained in an odd number of input polygons. (The value type of + the input iterator is used to distinguish between the two.) The + result, represented by a set of general polygon with holes, is + inserted into an output container through a given output iterator + `oi`. The output iterator is returned. The value type of the + `OutputIterator` is `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. + */ +template +OutputIterator symmetric_difference(InputIterator begin, InputIterator end, + OutputIterator oi, UsePolylineTraits = UsePolylineTraits()); + /*! computes the symmetric difference of the general polygons and general polygons with holes in the given two ranges. A point is contained in the @@ -827,7 +1142,30 @@ OutputIterator symmetric_difference(InputIterator1 pgn_begin1, InputIterator2 pgn_begin2, InputIterator2 pgn_end2, OutputIterator oi); + + /*! + computes the symmetric difference of the general polygons and general polygons + with holes in the given two ranges. A point is contained in the + symmetric difference, if and only if it is contained in an odd number of + input polygons. The result, represented by a set of general polygon with + holes, is inserted into an output container through a given output + iterator `oi`. The output iterator is returned. The value type of + the `OutputIterator` is `Traits::Polygon_with_holes_2`. + + \tparam UsePolylineTraits if set to `CGAL::Tag_true`, the internal + `General_polygon_set_2` is instantiated with polyline traits. If set + to `CGAL::Tag_false`, it uses segment traits instead. Default value is + `CGAL::Tag_true`. Please refer to \ref bso_ssectraits_sel for more + information. + */ +template +OutputIterator symmetric_difference(InputIterator1 pgn_begin1, + InputIterator1 pgn_end1, + InputIterator2 pgn_begin2, + InputIterator2 pgn_end2, + OutputIterator oi, + UsePolylineTraits = UsePolylineTraits()); /// @} } /* namespace CGAL */ -