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 e17668a7816..d4e89bc8905 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 @@ -11,6 +11,8 @@ namespace CGAL { * `complement()` function template inserts the resulting poylgons with holes * into a container via an output iterator. * + * \cgalHeading{Parameters} + * * \param pgn The input polygon. Its type must be convertible to one of the * types `Polygon_2`, `General_polygon_2`, `Polygon_with_holes_2`, or * `General_polygon_with_holes_2`. @@ -24,7 +26,7 @@ namespace CGAL { /// @{ -// Traits-less +//////// Traits-less /*! Computes the complement of a polygon. * \param pgn the input polygon. @@ -41,8 +43,9 @@ void complement(const Polygon_2& pgn, * `ArrangementDirectionalXMonotoneTraits_2`. */ template -void complement(const General_polygon_2& pgn, - General_polygon_with_holes_2 >& res); +void +complement(const General_polygon_2& pgn, + General_polygon_with_holes_2 >& res); /*! Computes the complement of a polygon with holes. * \param pgn the input polygon. @@ -65,10 +68,11 @@ OutputIterator complement(const Polygon_with_holes_2& pgn, * `ArrangementDirectionalXMonotoneTraits_2`. */ template -OutputIterator complement(const General_polygon_with_holes_2 >& pgn, - OutputIterator oi); +OutputIterator +complement(const General_polygon_with_holes_2 >& pgn, + OutputIterator oi); -// With Traits +//////// With Traits /*! Computes the complement of a polygon. * \param pgn the input polygon. @@ -90,9 +94,10 @@ void complement(const Polygon_2& pgn, * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. */ template -void complement(const General_polygon_2& pgn, - General_polygon_with_holes_2 >& res, - const GpsTraits& traits); +void +complement(const General_polygon_2& pgn, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); /*! Computes the complement of a polygon with holes. * \param pgn the input polygon. @@ -136,18 +141,19 @@ namespace CGAL { * \anchor ref_bso_difference * * There are several overloaded function templates called `difference()` that - * computes the \e difference between two polygons `pgn1` and `pgn2` and inserts - * the resulting polygons with holes into a container via the output iterator - * `oi`. + * compute the \e difference between two polygons and insert the resulting + * polygons with holes into a container via an output iterator. * - * \param oi the output iterator for the result. - * - * A function template in this subgroup has one of the two following signatures: + * A function template in this group has one of the two following signatures: * - `OutputIterator difference(const Type1& pgn1, const Type2& pgn2, * OutputIterator oi);` * - `OutputIterator difference(const Type1& pgn1, const Type2& pgn2, * OutputIterator oi, const GpsTraits& traits);` * + * \cgalHeading{Parameters} + * + * \param oi the output iterator for the result. + * * The types `Type1` and `Type2` of the parameters must be convertible to the * types specified in a row in the table below, respectively. The 3rd column * specifies the corresponding dereference type of the output iterator. @@ -166,6 +172,7 @@ namespace CGAL { * * * + * \sa \link boolean_complement `CGAL::complement()` \endlink * \sa \link boolean_do_intersect `CGAL::do_intersect()` \endlink * \sa \link boolean_intersection `CGAL::intersection()` \endlink * \sa \link boolean_join `CGAL::join()` \endlink @@ -259,9 +266,10 @@ OutputIterator difference(const General_polygon_2& pgn1, * `ArrangementDirectionalXMonotoneTraits_2`. */ template -OutputIterator difference(const General_polygon_with_holes_2 >& pgn1, - const General_polygon_2& pgn2, - OutputIterator oi); +OutputIterator +difference(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + OutputIterator oi); /*! computes the difference of two polygons and inserts the resulting * general polygons with holes into a container via an output iterator. @@ -275,9 +283,10 @@ OutputIterator difference(const General_polygon_with_holes_2 -OutputIterator difference(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2, - OutputIterator oi); +OutputIterator +difference(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + OutputIterator oi); /*! computes the difference of two general polygons with holes and inserts the * resulting general polygons with holes into a container via an output @@ -307,7 +316,8 @@ OutputIterator difference(const General_polygon_with_holes_2& pgn1, * \return the past-the-end iterator of the output container. * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. */ - template +template OutputIterator difference(const Polygon_2& pgn1, const Polygon_2& pgn2, OutputIterator oi, @@ -324,7 +334,8 @@ OutputIterator difference(const Polygon_2& pgn1, * \return the past-the-end iterator of the output container. * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. */ -template +template OutputIterator difference(const Polygon_2& pgn1, const Polygon_with_holes_2& pgn2, OutputIterator oi, @@ -341,7 +352,8 @@ OutputIterator difference(const Polygon_2& pgn1, * \return the past-the-end iterator of the output container. * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. */ -template +template OutputIterator difference(const Polygon_with_holes_2& pgn1, const Polygon_2& pgn2, OutputIterator oi, @@ -358,7 +370,8 @@ OutputIterator difference(const Polygon_with_holes_2& pgn1, * \return the past-the-end iterator of the output container. * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. */ -template +template OutputIterator difference(const Polygon_with_holes_2& pgn1, const Polygon_with_holes_2& pgn2, OutputIterator oi, @@ -397,10 +410,11 @@ OutputIterator difference(const General_polygon_2& pgn1, * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. */ template -OutputIterator difference(const General_polygon_with_holes_2 >& pgn1, - const General_polygon_2& pgn2, - OutputIterator oi, - const GpsTraits& traits); +OutputIterator +difference(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); /*! computes the difference of two general polygons and inserts the resulting * general polygons with holes into a container via an output iterator. @@ -416,10 +430,11 @@ OutputIterator difference(const General_polygon_with_holes_2 -OutputIterator difference(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2, - OutputIterator oi, - const GpsTraits& traits); +OutputIterator +difference(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + OutputIterator oi, + const GpsTraits& traits); /*! computes the difference of two general polygons and inserts the resulting * general polygons with holes into a container via an output iterator. @@ -447,16 +462,19 @@ namespace CGAL { * \ingroup PkgBooleanSetOperations2Ref * \anchor ref_bso_do_intersect * - * Each one of these functions computes if the interior of two given - * polygons `pgn1` and `pgn2` intersect. + * There are several overloaded function templates called `do_intersect()` + * that determine whether the interior of two or more polygons intersect. * - * The signature of the function is: + * A function template in this group that accepts two input polygons has one of + * the two following signatures: * - `bool do_intersect(const Type1& pgn1, const Type2& pgn2);` + * - `bool do_intersect(const Type1& pgn1, const Type2& pgn2, + const GpsTraits& traits);` * * \cgalHeading{Parameters} * - * The types of the parameters of the \link ref_bso_do_intersect - * `do_intersect()` \endlink function are any of the following combinations. + * The types `Type1` and `Type2` of the parameters must be convertible to the + * types specified in a row in the table below, respectively. * *
* @@ -472,6 +490,7 @@ namespace CGAL { *
*
* + * \sa \link boolean_complement `CGAL::complement()` \endlink * \sa \link boolean_intersection `CGAL::intersection()` \endlink * \sa \link boolean_join `CGAL::join()` \endlink * \sa \link boolean_difference `CGAL::difference()` \endlink @@ -480,6 +499,8 @@ namespace CGAL { /// @{ +//////// Traits-less + /*! determines whether two polygons intersect in their interior. * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. @@ -525,6 +546,8 @@ bool do_intersect(const Polygon_with_holes_2& pgn1, * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` * otherwise. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template bool do_intersect(const General_polygon_2& pgn1, @@ -535,16 +558,21 @@ bool do_intersect(const General_polygon_2& pgn1, * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` * otherwise. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -bool do_intersect(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2); +bool +do_intersect(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2); /*! determines whether two general polygons intersect in their interior. * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` * otherwise. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template bool do_intersect(const General_polygon_with_holes_2 >& pgn1, @@ -599,6 +627,166 @@ bool do_intersect(InputIterator1 begin1, InputIterator1 end1, InputIterator2 begin2, InputIterator2 end2); + +//////// With Traits + +/*! determines whether two polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(const Polygon_2& pgn1, + const Polygon_2& pgn2, + const GpsTraits& traits); + +/*! determines whether two polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(const Polygon_2& pgn1, + const Polygon_with_holes_2& pgn2, + const GpsTraits& traits, + const GpsTraits& traits); + +/*! determines whether two polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(const Polygon_with_holes_2& pgn1, + const Polygon_2& pgn2, + const GpsTraits& traits); + +/*! determines whether two polygons with holes intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(const Polygon_with_holes_2& pgn1, + const Polygon_with_holes_2& pgn2, + const GpsTraits& traits); + +/*! determines whether two general polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + */ +template +bool do_intersect(const General_polygon_2& pgn1, + const General_polygon_2& pgn2, + const GpsTraits& traits); + +/*! determines whether two general polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + */ +template +bool +do_intersect(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + const GpsTraits& traits); + +/*! determines whether two general polygons intersect in their interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + */ +template +bool +do_intersect(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + const GpsTraits& traits); + +/*! determines whether two general polygons with holes intersect in their + * interior. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param traits a traits object. + * \return `true` if `pgn1` and `pgn2` intersect in their interiro and `false` + * otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(const General_polygon_with_holes_2& pgn1, + const General_polygon_with_holes_2& pgn2, + const GpsTraits& traits); + +/*! Given a range of polygons or a range of polygons with holes (resp. a range + * of general polygons or a range of general polygons with holes) determines + * whether the open polygons (resp. general polygons) in the range have a common + * point. + * \param begin the first iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param end the past-the-end iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param traits a traits object. + * \return `true` if the pairwise intersections of all open polygons or polygons + * with holes (resp. general polygons or general polygons with holes) in + * the range [*begin,*end) overlap, and `false` otherwise. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool do_intersect(InputIterator begin, InputIterator end, + const GpsTraits& traits); + +/*! Given a range of polygons (resp. general polygons) and a range of polygons + * with holes (resp. general polygons with holes) determines whether the open + * polygons (resp. general polygons) in the two ranges have a common point. + * \param begin1 the first iterator of the 1st input range. It's value type is + * Polygon_2 (resp. General_polygon_2). + * \param end1 the past-the-end iterator of the 1st input range. It's value + * type is Polygon_2 (resp. General_polygon_2). + * \param begin2 the first iterator of the 2nd input range. It's value type + * is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param end2 the past-the-end iterator of the 2nd input range. It's value + * type is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param traits a traits object. + * \return `true` if the pairwise intersections of all open polygons (resp. + * general polygons) and polygons with holes (resp. general polygons with + * holes) in the ranges [*begin1,*end1) and [*begin2,*end2), + * respectively, overlap, and `false` otherwise. + */ +template +bool do_intersect(InputIterator1 begin1, InputIterator1 end1, + InputIterator2 begin2, InputIterator2 end2, + const GpsTraits& traits); + /// @} } /* namespace CGAL */ @@ -608,41 +796,44 @@ namespace CGAL { * \ingroup PkgBooleanSetOperations2Ref * \anchor ref_bso_intersection * - * Each one of these functions computes the intersection of two given - * polygons `pgn1` and `pgn2`, inserts the resulting polygons with - * holes into an output container through a given output iterator - * `oi`, and returns the output iterator. The value type of the - * `OutputIterator` is either `Polygon_with_holes_2` or - * `General_polygon_with_holes_2`. + * There are several overloaded function templates called `intersection()` that + * compute the \e intersection of two or more polygons and insert the resulting + * polygons with holes into a container via an output iterator. * - * The signature of the function is: - * - `%OutputIterator %intersection(const Type1& pgn1, const Type2& pgn2, - * %OutputIterator oi);` + * A function template in this group that accepts two input polygons has one of + * the two following signatures: + * - `OutputIterator %intersection(const Type1& pgn1, const Type2& pgn2, + * OutputIterator oi);` + * - `OutputIterator %intersection(const Type1& pgn1, const Type2& pgn2, + * OutputIterator oi, const GpsTraits& traits);` * * \cgalHeading{Parameters} * - * The types of the parameters of the `intersection()` function are any of the - * following combinations. + * \param oi the output iterator for the result. + * + * The types `Type1` and `Type2` of the parameters must be convertible to the + * types specified in a row in the table below, respectively. The 3rd column + * specifies the corresponding dereference type of the output iterator. * *
* - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * *
Type1 Type2
Polygon_2 Polygon_2
Polygon_2 Polygon_with_holes_2
Polygon_with_holes_2 Polygon_2
Polygon_with_holes_2 Polygon_with_holes_2
General_polygon_2 General_polygon_2
General_polygon_2 General_polygon_with_holes_2
General_polygon_with_holes_2General_polygon_2
General_polygon_with_holes_2General_polygon_with_holes_2
`Type1` `Type2` %Dereference Type of `oi`
`Polygon_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`General_polygon_2` `General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_2` `General_polygon_with_holes_2``General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_with_holes_2``General_polygon_with_holes_2`
*
* + * \sa \link boolean_complement `CGAL::complement()` \endlink * \sa \link boolean_do_intersect `CGAL::do_intersect()` \endlink * \sa \link boolean_join `CGAL::join()` \endlink * \sa \link boolean_difference `CGAL::difference()` \endlink * \sa \link boolean_symmetric_difference `CGAL::symmetric_difference()` \endlink - * */ /// @{ @@ -711,6 +902,8 @@ OutputIterator intersection(const Polygon_with_holes_2& pgn1, * Its dereference type must be convertible to * `General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template OutputIterator intersection(const General_polygon_2& pgn1, @@ -725,11 +918,14 @@ OutputIterator intersection(const General_polygon_2& pgn1, * Its dereference type must be convertible to * `General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -OutputIterator intersection(const General_polygon_with_holes_2 >& pgn1, - const General_polygon_2& pgn2, - OutputIterator oi); +OutputIterator +intersection(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + OutputIterator oi); /*! computes the intersection of two general polygons and inserts the resulting * general polygons with holes into a container via an output iterator. @@ -739,11 +935,14 @@ OutputIterator intersection(const General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -OutputIterator intersection(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2, - OutputIterator oi); +OutputIterator +intersection(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + OutputIterator oi); /*! computes the intersection of two general polygons with holes and inserts the * resulting general polygons with holes into a container via an output iterator. @@ -816,31 +1015,34 @@ namespace CGAL { * \ingroup PkgBooleanSetOperations2Ref * \anchor ref_bso_union * - * Each one of these functions computes the union of two given polygons `pgn1` and - * `pgn2`. If the two given polygons overlap, it returns `true`, and places the - * resulting polygon in `p`. Otherwise, it returns `false`. + * There are several overloaded function templates called `join()` that + * compute the \e union of two polygons. * - * The signature of the function is: - * - `bool join(const Type1& pgn1, const Type2& pgn2, General_polygon_with_holes_2& res);` + * A function template in this group has one of the two following signatures: + * - `bool join(const Type1& pgn1, const Type2& pgn2, Type3& res);` + * - `bool join(const Type1& pgn1, const Type2& pgn2, Type3& res, + * const GpsTraits& traits);` * * \cgalHeading{Parameters} * - * The types of the parameters of the `join()` function are any of the following combinations. + * The types `Type1`, `Type2`, and `Type3, of the parameters must be convertible + * to the types specified in a row in the table below, respectively. * *
* - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * *
Type1 Type2
Polygon_2 Polygon_2
Polygon_2 polygon_with_holes_2
Polygon_with_holes_2 Polygon_2
Polygon_with_holes_2 Polygon_with_holes_2
General_polygon_2 General_polygon_2
General_polygon_2 General_polygon_with_holes_2
General_polygon_with_holes_2General_polygon_2
General_polygon_with_holes_2General_polygon_with_holes_2
`Type1` `Type2` `Type3`
`Polygon_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`General_polygon_2` `General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_2` `General_polygon_with_holes_2``General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_with_holes_2``General_polygon_with_holes_2`
*
* + * \sa \link boolean_complement `CGAL::complement()` \endlink * \sa \link boolean_do_intersect `CGAL::do_intersect()` \endlink * \sa \link boolean_intersection `CGAL::intersection()` \endlink * \sa \link boolean_difference `CGAL::difference()` \endlink @@ -849,8 +1051,13 @@ namespace CGAL { /// @{ -/*! computes the union of the polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +//////// Traits-less + +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. */ template bool join(const Polygon_2& pgn1, @@ -858,8 +1065,11 @@ bool join(const Polygon_2& pgn1, General_polygon_with_holes_2 >& res); -/*! computes the union of the polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. */ template bool join(const Polygon_2& pgn1, @@ -867,8 +1077,11 @@ bool join(const Polygon_2& pgn1, General_polygon_with_holes_2 >& res); -/*! computes the union of the polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. */ template bool join(const Polygon_with_holes_2& pgn2, @@ -876,8 +1089,11 @@ bool join(const Polygon_with_holes_2& pgn2, General_polygon_with_holes_2 >& res); -/*! computes the union of the polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two polygons with holes. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. */ template bool join(const Polygon_with_holes_2& pgn2, @@ -885,8 +1101,13 @@ bool join(const Polygon_with_holes_2& pgn2, General_polygon_with_holes_2 >& res); -/*! computes the union of the general polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template bool join(const General_polygon_2& pgn1, @@ -894,54 +1115,268 @@ bool join(const General_polygon_2& pgn1, General_polygon_with_holes_2 >& res); -/*! computes the union of the polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -bool join(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2, - General_polygon_with_holes_2 >& res); +bool +join(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + General_polygon_with_holes_2 >& res); -/*! computes the union of the general polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -bool join(const General_polygon_with_holes_2 >& pgn2, - const General_polygon_2& pgn1, - General_polygon_with_holes_2 >& res); +bool +join(const General_polygon_with_holes_2 >& pgn2, + const General_polygon_2& pgn1, + General_polygon_with_holes_2 >& res); -/*! computes the union of the general polygons `pgn1` and `pgn2` into the polygon with holes `res`. - * Returns `true` if the two given polygons overlap. +/*! computes the union of two general polygons with holes. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \return `true` if the two input polygons overlap. */ template bool join(const General_polygon_with_holes_2& pgn1, const General_polygon_with_holes_2& pgn2, - Traits::Polygon_with_holes_2& res); + General_polygon_with_holes_2& res); -/*! computes the union of the general polygons (or general polygons with holes) - * 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`. +/*! Given a range of polygons (resp. general polygons) or a range of general + * polygons with holes (resp. general polygons with holes) computes the + * union of all polygons in the range and inserts the resulting polygons + * with holes (resp. general polygons with holes) into a container via an output + * iterator. + * \param begin the first iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param end the past-the-end iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \return the past-the-end iterator of the output container. */ template OutputIterator join(InputIterator begin, InputIterator end, OutputIterator oi); -/*! computes the union of the general polygons and general polygons with holes - * 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`. +/*! Given a range of polygons (resp. general polygons) and a range of general + * polygons with holes (resp. general polygons with holes) computes the + * union of all polygons in the two ranges and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. + * \param begin1 the first iterator of the 1st input range. It's value type is + * Polygon_2 (resp. General_polygon_2). + * \param end1 the past-the-end iterator of the 1st input range. It's value + * type is Polygon_2 (resp. General_polygon_2). + * \param begin2 the first iterator of the 2nd input range. It's value type + * is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param end2 the past-the-end iterator of the 2nd input range. It's value + * type is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \return the past-the-end iterator of the output container. */ -template -OutputIterator join(InputIterator1 pgn_begin1, InputIterator1 pgn_end1, - InputIterator2 pgn_begin2, InputIterator2 pgn_end2, +template +OutputIterator join(InputIterator1 begin1, InputIterator1 end1, + InputIterator2 begin2, InputIterator2 end2, OutputIterator oi); +//////// With Traits + +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const Polygon_2& pgn1, + const Polygon_2& pgn2, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const Polygon_2& pgn1, + const Polygon_with_holes_2& pgn2, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const Polygon_with_holes_2& pgn2, + const Polygon_2& pgn1, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two polygons with holes. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const Polygon_with_holes_2& pgn2, + const Polygon_with_holes_2& pgn1, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const General_polygon_2& pgn1, + const General_polygon_2& pgn2, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool +join(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two general polygons. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const General_polygon_with_holes_2 >& pgn2, + const General_polygon_2& pgn1, + General_polygon_with_holes_2 >& res, + const GpsTraits& traits); + + +/*! computes the union of two general polygons with holes. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param res the resulting union of \p pgn1 and \p pgn2. + * \param traits a traits object. + * \return `true` if the two input polygons overlap. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +bool join(const General_polygon_with_holes_2& pgn1, + const General_polygon_with_holes_2& pgn2, + General_polygon_with_holes_2& res, + const GpsTraits& traits); + +/*! Given a range of polygons (resp. general polygons) or a range of general + * polygons with holes (resp. general polygons with holes) computes the + * union of all polygons in the range and inserts the resulting polygons + * with holes (resp. general polygons with holes) into a container via an output + * iterator. + * \param begin the first iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param end the past-the-end iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator join(InputIterator begin, InputIterator end, + OutputIterator oi, + const GpsTraits& traits); + +/*! Given a range of polygons (resp. general polygons) and a range of general + * polygons with holes (resp. general polygons with holes) computes the + * union of all polygons in the two ranges and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. + * \param begin1 the first iterator of the 1st input range. It's value type is + * Polygon_2 (resp. General_polygon_2). + * \param end1 the past-the-end iterator of the 1st input range. It's value + * type is Polygon_2 (resp. General_polygon_2). + * \param begin2 the first iterator of the 2nd input range. It's value type + * is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param end2 the past-the-end iterator of the 2nd input range. It's value + * type is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator join(InputIterator1 begin1, InputIterator1 end1, + InputIterator2 begin2, InputIterator2 end2, + OutputIterator oi, + const GpsTraits& traits); + /// @} } /* namespace CGAL */ @@ -951,7 +1386,7 @@ namespace CGAL { * \anchor ref_bso_oriented_side * * There are several overloaded function templatess called `Oriented_side()` - * that computes the relative position of either (i) two polygons or (ii) a + * that compute the relative position of either (i) two polygons or (ii) a * point and a polygon. This group of function templates is divided into two * subgroups. * @@ -1020,8 +1455,9 @@ Oriented_side oriented_side(const Polygon_2& pgn1, * \param pgn2 the 2nd input polygon. */ template -Oriented_side oriented_side(const Polygon_2& pgn1, - const Polygon_with_holes_2& pgn2); +Oriented_side +oriented_side(const Polygon_2& pgn1, + const Polygon_with_holes_2& pgn2); /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. @@ -1036,13 +1472,15 @@ Oriented_side oriented_side(const Polygon_with_holes_2& pgn1, * \param pgn2 the 2nd input polygon. */ template -Oriented_side oriented_side(const Polygon_with_holes_2& pgn1, - const Polygon_with_holes_2& pgn2); +Oriented_side +oriented_side(const Polygon_with_holes_2& pgn1, + const Polygon_with_holes_2& pgn2); /*! computes the relative position of two polygons. * \param pgn1 1st the input polygon. * \param pgn2 the 2nd input polygon. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template Oriented_side oriented_side(const General_polygon_2& pgn1, @@ -1051,20 +1489,24 @@ Oriented_side oriented_side(const General_polygon_2& pgn1, /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -Oriented_side oriented_side(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2); +Oriented_side +oriented_side(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2); /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template -Oriented_side oriented_side(const General_polygon_with_holes_2 >& pgn1, - const General_polygon_2& pgn2); +Oriented_side +oriented_side(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2); /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. @@ -1074,7 +1516,7 @@ template Oriented_side oriented_side(const General_polygon_with_holes_2& pgn1, const General_polygon_with_holes_2& pgn2); -// Polygon--Polygon With Traits +//////// Polygon--Polygon With Traits /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. @@ -1124,7 +1566,8 @@ Oriented_side oriented_side(const Polygon_with_holes_2& pgn1, * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. * */ @@ -1137,27 +1580,31 @@ Oriented_side oriented_side(const General_polygon_2& pgn1, * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. * */ template -Oriented_side oriented_side(const General_polygon_2& pgn1, - const General_polygon_with_holes_2 >& pgn2, - const GpsTraits& traits); +Oriented_side +oriented_side(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + const GpsTraits& traits); /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. * \param pgn2 the 2nd input polygon. * \param traits a traits object. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. * */ template -Oriented_side oriented_side(const General_polygon_with_holes_2 >& pgn1, - const General_polygon_2& pgn2, - const GpsTraits& traits); +Oriented_side +oriented_side(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + const GpsTraits& traits); /*! computes the relative position of two polygons. * \param pgn1 the 1st input polygon. @@ -1191,7 +1638,8 @@ Oriented_side oriented_side(const Point_2& p, /*! computes the relative position of a point and a polygon. * \param p the input point. * \param pgn the input polygon. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template Oriented_side oriented_side(const Point_2& p, @@ -1205,7 +1653,7 @@ template Oriented_side oriented_side(const Point_2& p, const General_polygon_with_holes_2& pgn); -// Point--Polygon With Traits +//////// Point--Polygon With Traits /*! computes the relative position of a point and a polygon. * \param p the input point. @@ -1233,7 +1681,8 @@ Oriented_side oriented_side(const Point_2& p, * \param p the input point. * \param pgn the input polygon. * \param traits a traits object. - * \pre `%ArrTraits` must be a model of the concept `ArrangementDirectionalXMonotoneTraits_2`. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. * \pre `GpsTraits` must be a model of the concept `GeneralPolygonSetTraits_2`. */ template @@ -1261,34 +1710,46 @@ namespace CGAL { * \ingroup PkgBooleanSetOperations2Ref * \anchor ref_bso_symmetric_difference * - * Each one of these functions computes the symmetric difference between - * two given polygons `pgn1` and `pgn2`, and inserts the resulting - * polygons with holes into an output container through the output - * iterator `oi`. The value type of the `OutputIterator` is either - * `Polygon_with_holes_2` or - * `General_polygon_with_holes_2`. + * There are several overloaded function templates called + * `symmetric_difference()` that compute the \e symmetric difference + * between two or more input polygons and insert the resulting + * polygons with holes into a container via an output iterator. + * - * The signature of the function is: - * - `%OutputIterator symmetric_difference(const Type1& pgn1, const Type2& pgn2, %OutputIterator oi);` + * A function template in this group that accepts two input polygons has one of + * the two following signatures: + * - `OutputIterator symmetric_difference(const Type1& pgn1, const Type2& pgn2, + * OutputIterator oi);` + * - `OutputIterator symmetric_difference(const Type1& pgn1, const Type2& pgn2, + * OutputIterator oi, const GpsTraits& traits);` * * \cgalHeading{Parameters} * - * The types of the parameters of the `symmetric_difference()` function are any of the following combinations. + * The types `Type1` and `Type2` of the parameters must be convertible to the + * types specified in a row in the table below, respectively. The 3rd column + * specifies the corresponding dereference type of the output iterator. + * + * \param oi the output iterator for the result. + * + * The types `Type1` and `Type2` of the parameters must be convertible to the + * types specified in a row in the table below, respectively. The 3rd column + * specifies the corresponding dereference type of the output iterator. * *
* - * - * - * - * - * - * - * - * - * + * + * + * + * + * + * + * + * + * *
Arg 1 typeArg 2 type
Polygon_2Polygon_2
Polygon_2Polygon_with_holes_2
Polygon_with_holes_2Polygon_2
Polygon_with_holes_2Polygon_with_holes_2
General_polygon_2General_polygon_2
General_polygon_2General_polygon_with_holes_2
General_polygon_with_holes_2General_polygon_2
General_polygon_with_holes_2General_polygon_with_holes_2
`Type1` `Type2` %Dereference Type of `oi`
`Polygon_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_2` `Polygon_with_holes_2`
`Polygon_with_holes_2` `Polygon_with_holes_2` `Polygon_with_holes_2`
`General_polygon_2` `General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_2` `General_polygon_with_holes_2``General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_2` `General_polygon_with_holes_2`
`General_polygon_with_holes_2``General_polygon_with_holes_2``General_polygon_with_holes_2`
*
* + * \sa \link boolean_complement `CGAL::complement()` \endlink * \sa \link boolean_do_intersect `CGAL::do_intersect()` \endlink * \sa \link boolean_intersection `CGAL::intersection()` \endlink * \sa \link boolean_join `CGAL::join()` \endlink @@ -1297,6 +1758,8 @@ namespace CGAL { /// @{ +//////// Traits-less + /*! computes the symmetric difference between two polygons and inserts the * resulting polygons with holes into a container via an output iterator. * \param pgn1 the 1st input polygon. @@ -1367,6 +1830,8 @@ symmetric_difference(const Polygon_with_holes_2& pgn1, * Its dereference type must be convertible to * `General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template OutputIterator symmetric_difference(const General_polygon_2& pgn1, @@ -1383,6 +1848,8 @@ OutputIterator symmetric_difference(const General_polygon_2& pgn1, * Its dereference type must be convertible to * `General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template OutputIterator @@ -1400,6 +1867,8 @@ symmetric_difference(const General_polygon_with_holes_2 >`. * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. */ template OutputIterator @@ -1407,7 +1876,6 @@ symmetric_difference(const General_polygon_2& pgn1, const General_polygon_with_holes_2 >& pgn2, OutputIterator oi); - /*! computes the symmetric difference between two general polygons and inserts * the resulting general polygons with holes into a container via an output * iterator. @@ -1424,33 +1892,266 @@ symmetric_difference(const General_polygon_with_holes_2& pgn1, const General_polygon_with_holes_2& pgn2, OutputIterator oi); -/*! computes the symmetric difference of the general polygons (or general - * polygons with holes) 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`. +/*! Given a range of polygons (resp. general polygons) or a range of general + * polygons with holes (resp. general polygons with holes) computes the + * symmetric difference of all polygons in the range and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. A point is contained in the symmetric difference, if and + * only if it is contained in an odd number of input polygons. + * \param begin the first iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param end the past-the-end iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \return the past-the-end iterator of the output container. */ template OutputIterator symmetric_difference(InputIterator begin, InputIterator end, 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`. +/*! Given a range of polygons (resp. general polygons) and a range of general + * polygons with holes (resp. general polygons with holes) computes the + * intersection of all polygons in the two ranges and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. A point is contained in the symmetric difference, if and + * only if it is contained in an odd number of input polygons. + * \param begin1 the first iterator of the 1st input range. It's value type is + * Polygon_2 (resp. General_polygon_2). + * \param end1 the past-the-end iterator of the 1st input range. It's value + * type is Polygon_2 (resp. General_polygon_2). + * \param begin2 the first iterator of the 2nd input range. It's value type + * is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param end2 the past-the-end iterator of the 2nd input range. It's value + * type is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \return the past-the-end iterator of the output container. */ -template -OutputIterator symmetric_difference(InputIterator1 pgn_begin1, - InputIterator1 pgn_end1, - InputIterator2 pgn_begin2, - InputIterator2 pgn_end2, +template +OutputIterator symmetric_difference(InputIterator1 begin1, InputIterator1 end1, + InputIterator2 begin2, InputIterator2 end2, OutputIterator oi); + +//////// With Traits + +/*! computes the symmetric difference between two polygons and inserts the + * resulting polygons with holes into a container via an output iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator symmetric_difference(const Polygon_2& pgn1, + const Polygon_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + +/*! computes the symmetric difference between two polygons and inserts the + * resulting polygons with holes into a container via an output iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const Polygon_2& pgn1, + const Polygon_with_holes_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + +/*! computes the symmetric difference between two polygons and inserts the + * resulting polygons with holes into a container via an output iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const Polygon_with_holes_2& pgn1, + const Polygon_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + + +/*! computes the symmetric difference between two polygons with holes and + * inserts the resulting polygons with holes into a container via an output + * iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const Polygon_with_holes_2& pgn1, + const Polygon_with_holes_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + +/*! computes the symmetric difference between two general polygons and inserts + * the resulting general polygons with holes into a container via an output + * iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `General_polygon_with_holes_2 >`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator symmetric_difference(const General_polygon_2& pgn1, + const General_polygon_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + + +/*! computes the symmetric difference between two general polygons and inserts + * the resulting general polygons with holes into a container via an output + * iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `General_polygon_with_holes_2 >`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const General_polygon_with_holes_2 >& pgn1, + const General_polygon_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + + +/*! computes the symmetric difference between two general polygons and inserts + * the resulting general polygons with holes into a container via an output + * iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `General_polygon_with_holes_2 >`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre `%ArrTraits` must be a model of the concept + * `ArrangementDirectionalXMonotoneTraits_2`. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const General_polygon_2& pgn1, + const General_polygon_with_holes_2 >& pgn2, + OutputIterator oi, + const GpsTraits& traits); + +/*! computes the symmetric difference between two general polygons and inserts + * the resulting general polygons with holes into a container via an output + * iterator. + * \param pgn1 the 1st input polygon. + * \param pgn2 the 2nd input polygon. + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `General_polygon_with_holes_2`. + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator +symmetric_difference(const General_polygon_with_holes_2& pgn1, + const General_polygon_with_holes_2& pgn2, + OutputIterator oi, + const GpsTraits& traits); + +/*! Given a range of polygons (resp. general polygons) or a range of general + * polygons with holes (resp. general polygons with holes) computes the + * symmetric difference of all polygons in the range and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. A point is contained in the symmetric difference, if and + * only if it is contained in an odd number of input polygons. + * \param begin the first iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param end the past-the-end iterator of the input range. It's value type is + * either Polygon_2 (resp. General_polygon_2) or Polygon_with_holes + * (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator symmetric_difference(InputIterator begin, InputIterator end, + OutputIterator oi, + const GpsTraits& traits); + +/*! Given a range of polygons (resp. general polygons) and a range of general + * polygons with holes (resp. general polygons with holes) computes the + * intersection of all polygons in the two ranges and inserts the resulting + * polygons with holes (resp. general polygons with holes) into a container via + * an output iterator. A point is contained in the symmetric difference, if and + * only if it is contained in an odd number of input polygons. + * \param begin1 the first iterator of the 1st input range. It's value type is + * Polygon_2 (resp. General_polygon_2). + * \param end1 the past-the-end iterator of the 1st input range. It's value + * type is Polygon_2 (resp. General_polygon_2). + * \param begin2 the first iterator of the 2nd input range. It's value type + * is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param end2 the past-the-end iterator of the 2nd input range. It's value + * type is Polygon_with_holes_2 (resp. General_polygon_with_holes_2). + * \param oi the output iterator for the result. + * Its dereference type must be convertible to + * `Polygon_with_holes_2` (resp. `General_polygons_with_holes_2`). + * \param traits a traits object. + * \return the past-the-end iterator of the output container. + * \pre GpsTraits must be a model of `GeneralPolygonSetTraits_2`. + */ +template +OutputIterator symmetric_difference(InputIterator1 begin1, InputIterator1 end1, + InputIterator2 begin2, InputIterator2 end2, + OutputIterator oi, + const GpsTraits& traits); + /// @} } /* namespace CGAL */