From 3fca44f9492f5e5e70de0bd560dffba54603eb0d Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Thu, 14 Sep 2023 16:04:23 +0300 Subject: [PATCH 1/8] Left \ingroup statements in separe lines --- .../Arrangement_on_surface_2/CGAL/Arrangement_2.h | 12 ++++++------ .../CGAL/Arrangement_on_surface_2.h | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h index bf3e048637d7..a269c6e01842 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h @@ -160,12 +160,12 @@ class Arrangement_2 : public Arrangement_on_surface_2 Date: Thu, 14 Sep 2023 16:41:41 +0300 Subject: [PATCH 2/8] 1st revision --- .../CGAL/CORE_algebraic_number_traits.h | 218 ++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h new file mode 100644 index 000000000000..4b40d11fd1d7 --- /dev/null +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h @@ -0,0 +1,218 @@ +namespace CGAL { + +/*! \ingroup PkgArrangementOnSurface2TraitsClasses + * + * `CORE_algebraic_number_traits` is a traits class for CORE's algebraic + * number types. + * + * \sa `Arr_conic_traits_2` + */ +class CORE_algebraic_number_traits { +public: + /// \name Types + /// @{ + + //! The integer number type. + typedef CORE::BigInt Integer; + + //! The rational number type. + typedef CORE::BigRat Rational; + + //! The polynomial type. + typedef CORE::Polynomial Polynomial; + + //! The algebraic number type. + typedef CORE::Expr Algebraic; + + /// @} + + /// \name Utility Functions + /// @{ + + /*! Obtain the numerator of a rational number. + * \param q A rational number. + * \return The numerator of q. + */ + Integer numerator(const Rational& q) const; + + /*! Obtain the denominator of a rational number. + * \param q A rational number. + * \return The denominator of q. + */ + Integer denominator(const Rational& q) const; + + /*! Convert an integer to an algebraic number. + * \param z An integer. + * \return The algebraic number equivalent to z. + */ + Algebraic convert(const Integer& z) const; + + /*! Convert a rational number to an algebraic number. + * \param q A rational number. + * \return The algebraic number equivalent to q. + */ + Algebraic convert(const Rational& q) const; + + /*! Construct a rational number that lies strictly between two algebraic + * values. + * \param x1 The first algebraic value. + * \param x2 The second algebraic value. + * \pre The two values are not equal. + * \return A rational number that lies in the open interval (x1, x2). + */ + Rational rational_in_interval(const Algebraic& x1, const Algebraic& x2) const; + + /*! Obtain a range of double-precision floats that contains the given + * algebraic number. + * \param x The given number. + * \return A pair that contain x. + */ + std::pair double_interval(const Algebraic& x) const; + + /*! Convert a sequence of rational coefficients to an equivalent sequence + * of integer coefficients. If the input coefficients are q(1), ..., q(k), + * where q(i) = n(i)/d(i) then the output coefficients will be of the + * form: + * n(i) * lcm {d(1), ... , d(k)} + * a(i) = ------------------------------- + * d(i) * gcd {n(1), ... , n(k)} + * + * \param q_begin The begin iterator of the rational sequence. + * \param q_end The past-the-end iterator of the rational sequence. + * \param zoi An output iterator for the integer coefficients. + * \return A past-the-end iterator for the output container. + * \pre The value type of q_begin and q_end is `Rational`, and + * the value type of zoi is `Integer`. + */ + template + OutputIterator convert_coefficients(InputIterator q_begin, + InputIterator q_end, + OutputIterator zoi) const; + + /*! Compute the square root of an algebraic number. + * \param x The number. + * \return The square root of x. + * \pre x is non-negative. + */ + Algebraic sqrt(const Algebraic& x) const; + + /*! Compute the roots of a quadratic equations \f$a*x^2+ b*x + c = 0\f$ + * with integer coefficients. + * \param a The coefficient of \f$x^2\f$ + * \param b The coefficient of \f$x\f$ + * \param c The free term. + * \param oi An output iterator for the real-valued solutions of the + * quadratic equation. + * \return A past-the-end iterator for the output container. + * \pre The value type of oi is Algebraic. + */ + template + OutputIterator solve_quadratic_equation(const NT& a, const NT& b, const NT& c, + OutputIterator oi) const; + + /*! Construct a polynomial with integer coefficients. + * \param coeffs The coefficients of the input polynomial. + * \param degree The degree of the input polynomial. + * \return The polynomial. + */ + Polynomial construct_polynomial(const Integer* coeffs, + unsigned int degree) const; + + /*! Construct a polynomial with integer coefficients given rational + * coefficients. + * \param coeffs The coefficients of the input polynomial. + * \param degree The degree of the input polynomial. + * \param poly Output: The resulting polynomial with integer coefficients. + * \param poly_denom Output: The denominator for the polynomial. + * \return Whether this polynomial is non-zero (false if the polynomial is + * zero). + */ + bool construct_polynomial(const Rational *coeffs, + unsigned int degree, + Polynomial& poly, Integer& poly_denom) const; + + /*! Construct two polynomials with integer coefficients such that P(x)/Q(x) + * is a rational function equivalent to the one represented by the two + * given vectors of rational coefficients. It is guaranteed that the GCD + * of P(x) and Q(x) is trivial. + * \param p_coeffs The coefficients of the input numerator polynomial. + * \param p_degree The degree of the input numerator polynomial. + * \param q_coeffs The coefficients of the input denominator polynomial. + * \param q_degree The degree of the input denominator polynomial. + * \param p_poly Output: The resulting numerator polynomial with integer + * coefficients. + * \param q_poly Output: The resulting denominator polynomial with integer + * coefficients. + * \return (true) on success; (false) if the denominator is 0. + */ + bool construct_polynomials(const Rational* p_coeffs, + unsigned int p_degree, + const Rational* q_coeffs, + unsigned int q_degree, + Polynomial& p_poly, Polynomial& q_poly) const; + + /*! Compute the degree of a polynomial. + */ + int degree(const Polynomial& poly) const; + + /*! Evaluate a polynomial at a given x-value. + * \param poly A polynomial. + * \param x The value to evaluate at. + * \return The value of the polynomial at x. + */ + template + NT evaluate_at(const Polynomial& poly, NT& x) const; + + /*! Compute the derivative of the given polynomial. + * \param poly The polynomial p(x). + * \return The derivative p'(x). + */ + Polynomial derive(const Polynomial& poly) const; + + /*! Multiply a polynomial by some scalar coefficient. + * \param poly The polynomial P(x). + * \param a The scalar value. + * \return The scalar multiplication a*P(x). + */ + Polynomial scale(const Polynomial& poly, const Integer& a) const; + + /*! Perform "long division" of two polynomials: Given A(x) and B(x) compute + * two polynomials Q(x) and R(x) such that: A(x) = Q(x)*B(x) + R(x) and + * R(x) has minimal degree. + * \param polyA The first polynomial A(x). + * \param polyB The second polynomial A(x). + * \param rem Output: The remainder polynomial R(x). + * \return The quontient polynomial Q(x). + */ + Polynomial divide(const Polynomial& polyA, + const Polynomial& polyB, + Polynomial& rem) const; + + /*! Compute the real-valued roots of a polynomial with integer coefficients, + * sorted in ascending order. + * \param poly The input polynomial. + * \param oi An output iterator for the real-valued root of the polynomial. + * \return A past-the-end iterator for the output container. + * \pre The value type of oi is Algebraic. + */ + template + OutputIterator compute_polynomial_roots(const Polynomial& poly, + OutputIterator oi) const; + + /*! Compute the real-valued roots of a polynomial with integer coefficients, + * within a given interval. The roots are sorted in ascending order. + * \param poly The input polynomial. + * \param x_min The left bound of the interval. + * \param x_max The right bound of the interval. + * \param oi An output iterator for the real-valued root of the polynomial. + * \return A past-the-end iterator for the output container. + * \pre The value type of oi is Algebraic. + */ + template + OutputIterator compute_polynomial_roots(const Polynomial& poly, + double x_min, double x_max, + OutputIterator oi) const; + /// @} +}; + +} /* end namespace CGAL */ From 8123d2e2f8cfc4c679b968109396f5234cc5834d Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Thu, 14 Sep 2023 16:44:26 +0300 Subject: [PATCH 3/8] Added missing documentation for CGAL::CORE_algebraic_number_traits --- .../doc/Arrangement_on_surface_2/PackageDescription.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/PackageDescription.txt b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/PackageDescription.txt index c14d0489746b..20dc50a57953 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/PackageDescription.txt +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/PackageDescription.txt @@ -236,6 +236,7 @@ implemented as peripheral classes or as free (global) functions. - `CGAL::Arr_bounded_planar_topology_traits_2` - `CGAL::Arr_unb_planar_topology_traits_2` - `CGAL::Arr_spherical_topology_traits_2` +- `CGAL::CORE_algebraic_number_traits` \cgalCRPSection{Functions} From 8c2f72d94daa22183ed2584ebf4eb471ede91638 Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Thu, 14 Sep 2023 16:44:47 +0300 Subject: [PATCH 4/8] Removed erroneous link --- .../doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h | 1 - 1 file changed, 1 deletion(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h index fe4de62ca8f0..2c0d60278730 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h @@ -34,7 +34,6 @@ namespace CGAL { * \sa `Arr_default_dcel` * \sa `ArrangementBasicTraits_2` * \sa `CGAL::overlay()` - * \sa `CGAL::is_valid()` * Insertion Functions From e5f49d70991dc610ca80acf0e1123d00157ba10a Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Thu, 14 Sep 2023 16:56:58 +0300 Subject: [PATCH 5/8] Fixed the description of the topology traits --- .../Arrangement_on_surface_2.txt | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt index b4bff8ed2db1..f7dfaa98b520 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt @@ -5651,10 +5651,24 @@ must model the basic concept `ArrangementBasicTopologyTraits`. A model of this basic concept holds the (\dcel) data structure used to represent the arrangement cells (i.e., vertices, edges, and facets) and the incidence relations between them. At this point we do not -expose the concepts that refine the basic concept. The package -contains one topology traits, namely, -`Arr_spherical_topology_traits_2`. It can serve as a topology traits -for an arrangement embedded on a sphere. More precisely, for an +expose the concepts that refine the basic concept. The package +contains three topology traits class templates, namely, +`Arr_bounded_planar_topology_traits_2`, +`Arr_unb_planar_topology_traits_2`, and +`Arr_spherical_topology_traits_2`. The first two are internally used +to define any instance of the class template +`Arrangement_2`. In particular, an instance +`Arrangement_2` is derived from the instance +`Arrangement_on_surface_2`, where +the `Topology_traits` type is selected based on the provided geometry +traits `Geometry_traits_2`, or more precisely, on the boundary +conditions defined by the geometry traits. If all sides of the +boundary of the parameter space are cosed, the instance +`Arr_bounded_planar_topology_traits_2` is +selected; otherwise the instance +`Arr_unb_planar_topology_traits_2` is +selected. The third topology traits serves as a topology traits for +an arrangement embedded on a sphere. More precisely, for an arrangement embedded on a sphere defined over a parameter space, the left and right boundary sides of which are identified, and the top and bottom boundary sides are contracted. From 71cd38ecb5fe12330791ba40ad71eb4eac1f27b7 Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Tue, 19 Sep 2023 12:20:06 +0300 Subject: [PATCH 6/8] Several fixes mainly related to output iterators --- .../Arrangement_on_surface_2.txt | 2 +- .../CGAL/Arr_algebraic_segment_traits_2.h | 402 ++++++++---------- .../CGAL/Arr_batched_point_location.h | 64 +-- .../CGAL/Arr_conic_traits_2.h | 29 +- .../CGAL/Arr_point_location_result.h | 35 +- .../CGAL/Arr_polycurve_traits_2.h | 19 +- .../CGAL/Arr_vertical_decomposition_2.h | 80 ++-- .../CGAL/Arrangement_2.h | 33 -- .../CGAL/Arrangement_on_surface_2.h | 49 ++- .../CGAL/CORE_algebraic_number_traits.h | 180 ++++---- .../Concepts/ArrTraits--Intersect_2.h | 35 +- .../Concepts/ArrTraits--MakeXMonotone_2.h | 20 +- .../batched_point_location.cpp | 2 +- 13 files changed, 467 insertions(+), 483 deletions(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt index f7dfaa98b520..4299322e38cd 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Arrangement_on_surface_2.txt @@ -5663,7 +5663,7 @@ to define any instance of the class template the `Topology_traits` type is selected based on the provided geometry traits `Geometry_traits_2`, or more precisely, on the boundary conditions defined by the geometry traits. If all sides of the -boundary of the parameter space are cosed, the instance +boundary of the parameter space are closed, the instance `Arr_bounded_planar_topology_traits_2` is selected; otherwise the instance `Arr_unb_planar_topology_traits_2` is diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_algebraic_segment_traits_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_algebraic_segment_traits_2.h index 069d91859ee7..5007dce85f53 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_algebraic_segment_traits_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_algebraic_segment_traits_2.h @@ -26,45 +26,37 @@ one of the integral types above. */ -template< typename Coefficient > +template class Arr_algebraic_segment_traits_2 { public: /// \name Types /// @{ -/*! -Value to specify whether a point should be in the interior -of a segment, or its minimal point, -or its maximal point in lexicographic order. -*/ +/*! Value to specify whether a point should be in the interior of a segment, or + * its minimal point, or its maximal point in lexicographic order. + */ enum Site_of_point { POINT_IN_INTERIOR = 0, MIN_ENDPOINT = -1, MAX_ENDPOINT = 1 }; -/*! -the type for bivariate polynomials, -with innermost coefficient type `Coefficient`. -Constitutes a model of the concept `Polynomial_d` -with two variables. - -\sa `CGAL::Polynomial_d` -*/ +/*! the type for bivariate polynomials, with innermost coefficient type + * `Coefficient`. Constitutes a model of the concept `Polynomial_d` with two + * variables. + * + * \sa `CGAL::Polynomial_d` + */ typedef unspecified_type Polynomial_2; -/*! -model for the concept -`AlgebraicKernel_1` -*/ +/*! model for the concept `AlgebraicKernel_1` + */ typedef unspecified_type Algebraic_kernel_1; -/*! -represents coordinates of points. -Typedef from `Algebraic_kernel_1::Algebraic_real_1` -*/ +/*! represents coordinates of points. + * Typedef from `Algebraic_kernel_1::Algebraic_real_1` + */ typedef unspecified_type Algebraic_real_1; -/*! -Typedef from `Algebraic_kernel_1::Bound` -*/ +/*! Typedef from `Algebraic_kernel_1::Bound` + */ typedef unspecified_type Bound; /// @} @@ -74,46 +66,41 @@ typedef unspecified_type Bound; /*! -*/ + */ Construct_curve_2 construct_curve_2_object() const; /*! -*/ + */ Construct_point_2 construct_point_2_object() const; /*! -*/ + */ Construct_x_monotone_segment_2 construct_x_monotone_segment_2_object() const; /// @} /*! - -*/ + */ class Construct_curve_2 { public: /// \name Object Creation Functors /// @{ -/*! -Returns a `Curve_2` object that represents the curve defined by -the polynomial `p` -*/ +/*! Returns a `Curve_2` object that represents the curve defined by the + * polynomial `p` + */ Curve_2 operator() (Polynomial_2 p); -/*! -Returns a `Curve_2` object specified by `s`. -The passed string represents the defining polynomial of the curve -and must be given in a MAPLE-readable format using "x" as first -and "y" as second variable, e.g., -"(x^3*y-2*x)*(-6*x-y^3*x^6)" -for integer coefficients, and "3/2*x*y^4-5/7*x^2+3/1" -for rational coefficients. -*/ +/*! Returns a `Curve_2` object specified by `s`. The passed string represents + * the defining polynomial of the curve and must be given in a MAPLE-readable + * format using "x" as first and "y" as second variable, e.g., + * \f$(x^3*y-2*x)*(-6*x-y^3*x^6)\f$ for integer coefficients, and + * \f$3/2*x*y^4-5/7*x^2+3/1\f$ for rational coefficients. + */ Curve_2 operator() (std::string s); /// @} @@ -122,49 +109,42 @@ Curve_2 operator() (std::string s); /*! - -*/ + */ class Construct_point_2 { public: /// \name Object Creation Functors /// @{ -/*! -Returns a `Point_2` object that represents the `arcno`-th -point in the fiber of `cv` at \f$ x\f$-coordinate `x`, -counted from the bottom, starting with zero. -\pre (`cv` must not have a vertical line at `x`, -and \f$ 0\leq arcno < c\f$, where \f$ c\f$ is the number of points -in the fiber of `cv` at `x`.) -*/ +/*! Returns a `Point_2` object that represents the `arcno`-th + * point in the fiber of `cv` at \f$ x\f$-coordinate `x`, + * counted from the bottom, starting with zero. + * \pre (`cv` must not have a vertical line at `x`, + * and \f$ 0\leq arcno < c\f$, where \f$ c\f$ is the number of points + * in the fiber of `cv` at `x`.) + */ Point_2 operator() (Algebraic_real_1 x, Curve_2 cv, int arcno); -/*! -Returns a `Point_2` object that represents the -point on `xcv` at \f$ x\f$-coordinate `x` -\pre (`x` is in the \f$ x\f$-range of `xcv`.) -*/ +/*! Returns a `Point_2` object that represents the + * point on `xcv` at \f$ x\f$-coordinate `x` + * \pre (`x` is in the \f$ x\f$-range of `xcv`.) + */ Point_2 operator() (Algebraic_real_1 x, X_monotone_curve_2 xcv); -/*! -Returns a `Point_2` object that represents (x,y) -*/ +/*! Returns a `Point_2` object that represents (x,y) + */ Point_2 operator() (Algebraic_real_1 x, Algebraic_real_1 y); -/*! -Returns a `Point_2` object that represents (x,y) -*/ +/*! Returns a `Point_2` object that represents (x,y) + */ Point_2 operator() (Coefficient x, Coefficient y); -/*! -Returns a `Point_2` object that represents (x,y) -*/ +/*! Returns a `Point_2` object that represents (x,y) + */ Point_2 operator() (Bound x, Bound y); -/*! -Returns a `Point_2` object that represents (x,y) -*/ +/*! Returns a `Point_2` object that represents (x,y) + */ Point_2 operator() (int x, int y); /// @} @@ -173,91 +153,86 @@ Point_2 operator() (int x, int y); /*! - -*/ + */ class Construct_x_monotone_segment_2 { public: /// \name Object Creation Functors /// @{ -/*! -Writes a sequence of `X_monotone_curve_2` objects (terminal -segments) into `out`. These terminal segments compose an -\f$ x\f$-monotone (or vertical) segment of the curve `cv` that -starts in `end_min`, and ends in `end_max`. -\pre (`end_min` must have a unique \f$ x\f$-monotone segment -to its right, or `end_max` must have a unique -\f$ x\f$-monotone segment to its left. Furthermore, -`end_min` and `end_max` must be connected -by an \f$ x\f$-monotone segment of `cv`) -*/ -template OutputIterator -operator() (Curve_2 cv, Point_2 end_min, Point_2 end_max, -OutputIterator out); - -/*! -Writes a sequence of `X_monotone_curve_2` objects into `out`. -These segments form an \f$ x\f$-monotone (or vertical) -segment of the curve `cv`. - -If `site_of_p==POINT_IN_INTERIOR`, the maximal segment is -returned that contains `p` in its interior. - -returned that contains `p` as its left endpoint. - -returned that contains `p` as its left endpoint. -\pre (If `site_of_p==POINT_IN_INTERIOR`, `p` -must be an interior point of an \f$ x\f$-monotone or a vertical -segment. -must either have a unique \f$ x\f$-monotone segment to the right, -or a vertical segment from `p` upwards. -must either have a unique \f$ x\f$-monotone segment to the left, -or a vertical segment from `p` downwards.) -*/ -template OutputIterator -operator() (Curve_2 cv, Point_2 p, -Site_of_point site_of_p, -OutputIterator out); - -/*! -Writes a sequence of `X_monotone_curve_2` objects into `out`. -These segments form a straight-line segment connecting -the points `p` and `q`. If `p` and `q` share the -same \f$ x\f$-coordinate, the constructed vertical segment consists of -only one `X_monotone_curve_2` object and can be computed -efficiently. In the non-vertical case, -the construction is only possible if `p` and `q` -have both rational x- and y-coordinates. -\pre (`p` must not be equal to `q`.) - -*/ -template OutputIterator -operator() (Point_2 p, Point_2 q, -OutputIterator out); +/*! inserts a sequence of `X_monotone_curve_2` objects (terminal segments) into + * an output container given through an output iterator. These terminal segments + * compose an \f$x\f$-monotone (or vertical) segment of a given curve that + * starts in `end_min`, and ends in `end_max`. + * + * \param cv The input curve. + * \param end_min The starting point. + * \param end_max The ending point. + * \param oi The output iterator that points at the output container. + * \return The past-the-end iterator of the output container. + * + * \pre `end_min` must have a unique \f$x\f$-monotone segment to its right, or + * `end_max` must have a unique \f$x\f$-monotone segment to its left. + * Furthermore, `end_min` and `end_max` must be connected by an + * \f$x\f$-monotone segment of `cv`) + */ +template +OutputIterator operator() (Curve_2 cv, Point_2 end_min, Point_2 end_max, + OutputIterator oi); + +/*! inserts a sequence of `X_monotone_curve_2` objects into an output container + * given through an output iterator. These segments form an \f$x\f$-monotone + * (or vertical) segment of the curve `cv`. + * + * If `site_of_p==POINT_IN_INTERIOR`, the maximal segment is + * returned that contains `p` in its interior. + * + * returned that contains `p` as its left endpoint. + * + * returned that contains `p` as its left endpoint. + * + * \pre (If `site_of_p==POINT_IN_INTERIOR`, `p` + * must be an interior point of an \f$x\f$-monotone or a vertical + * segment. + * must either have a unique \f$x\f$-monotone segment to the right, + * or a vertical segment from `p` upwards. + * must either have a unique \f$x\f$-monotone segment to the left, + * or a vertical segment from `p` downwards.) + */ +template +OutputIterator operator() (Curve_2 cv, Point_2 p, Site_of_point site_of_p, + OutputIterator out); + +/*! inserts a sequence of `X_monotone_curve_2` objects into an output container + * given through an output iterator. These segments form a straight-line + * segment connecting the points `p` and `q`. If `p` and `q` share the same + * \f$x\f$-coordinate, the constructed vertical segment consists of only one + * `X_monotone_curve_2` object and can be computed efficiently. In the + * non-vertical case, the construction is only possible if `p` and `q` have both + * rational x- and y-coordinates. + * + * \pre (`p` must not be equal to `q`.) + */ +template +OutputIterator operator() (Point_2 p, Point_2 q, OutputIterator out); /// @} }; /* end Arr_algebraic_segment_traits_2::Construct_x_monotone_segment_2 */ -/*! - - -Models the `ArrangementTraits_2::Curve_2` concept. -Represents algebraic curves. Internally, the type stores -topological-geometric information about the particular curve. -In order to use internal caching, instances should only be created -using the `Construct_curve_2` functor of the traits class. - -*/ +/*! Models the `ArrangementTraits_2::Curve_2` concept. + * Represents algebraic curves. Internally, the type stores + * topological-geometric information about the particular curve. + * In order to use internal caching, instances should only be created + * using the `Construct_curve_2` functor of the traits class. + */ class Curve_2 { public: /// \name Modifiers /// @{ -/*! -returns the defining polynomial of the curve. +/*! returns the defining polynomial of the curve. */ Polynomial_2 polynomial () const; @@ -265,124 +240,105 @@ Polynomial_2 polynomial () const; }; /* end Arr_algebraic_segment_traits_2::Curve_2 */ -/*! - - -Models the `ArrangementBasicTraits_2::Point_2` concept. -Represents points in \f$ \mathbb{R}^2\f$. Intersection points of algebraic curves -are in general non-rational, so we need a data structure that is capable -of representing arbitrary points with algebraic coordinates. - -The traits class represents algebraic coordinates by the type -`Algebraic_real_1`, which is a model of the `AlgebraicReal_1` -concept. -A point \f$ p\f$ is stored by a triple \f$ (x,cv,arcno)\f$, -where \f$ x\f$ is the \f$ x\f$-coordinate of a point, \f$ cv\f$ is an instance -of `Curve_2` that contains the point, (and has no vertical line at \f$ x\f$), -and \f$ arcno\f$ is an `int`, denoting that \f$ p\f$ is met as the \f$ arcno\f$-th -point when shooting a vertical ray at \f$ x\f$, starting from \f$ -\infty\f$ -(where counting starts with \f$ 0\f$). +/*! Models the `ArrangementBasicTraits_2::Point_2` concept. + * Represents points in \f$ \mathbb{R}^2\f$. Intersection points of algebraic + * curves are in general non-rational, so we need a data structure that is + * capable of representing arbitrary points with algebraic coordinates. + * + * The traits class represents algebraic coordinates by the type + * `Algebraic_real_1`, which is a model of the `AlgebraicReal_1` concept. + * A point \f$ p\f$ is stored by a triple \f$ (x,cv,arcno)\f$, + * where \f$ x\f$ is the \f$ x\f$-coordinate of a point, \f$ cv\f$ is an instance + * of `Curve_2` that contains the point, (and has no vertical line at \f$ x\f$), + * and \f$ arcno\f$ is an `int`, denoting that \f$ p\f$ is met as the + * \f$arcno\f$-th point when shooting a vertical ray at \f$ x\f$, starting from + * \f$-\infty\f$ (where counting starts with \f$ 0\f$). + * + * In addition to the methods listed below, the copy constructor and assignment + * operator for `Point_2` objects are also supported. + * + * The functor `Construct_point_2` constructs `Point_2` instances. + */ -In addition to the methods listed below, the copy constructor and assignment -operator for `Point_2` objects are also supported. - -The functor `Construct_point_2` constructs `Point_2` instances. - -*/ class Point_2 { public: /// \name Modifiers /// @{ -/*! -returns the \f$ x\f$-coordinate of `p`. -*/ +/*! returns the \f$ x\f$-coordinate of `p`. + */ Algebraic_real_1 x () const; -/*! -returns the \f$ y\f$-coordinates of `p`. - -Attention: As described above, points are not stored -by their \f$ y\f$-coordinate in `Algebraic_real_1` representation. In fact, -this representation must be computed on demand, and might become quite -costly for points defined by high-degree polynomials. Therefore, it is -recommended to avoid to call this function as much as possible. -*/ +/*! returns the \f$ y\f$-coordinates of `p`. + * + * Attention: As described above, points are not stored + * by their \f$ y\f$-coordinate in `Algebraic_real_1` representation. In fact, + * this representation must be computed on demand, and might become quite + * costly for points defined by high-degree polynomials. Therefore, it is + * recommended to avoid to call this function as much as possible. + */ Algebraic_real_1 y () const; -/*! -returns a `Curve_2` instance that `p`is part of. -*/ +/*! returns a `Curve_2` instance that `p`is part of. + */ Curve_2 curve () const; -/*! -returns the arc number of `p`. -*/ +/*! returns the arc number of `p`. + */ int arcno () const; -/*! -returns double-approximations of the \f$ x\f$- and \f$ y\f$-coordinates. -*/ +/*! returns double-approximations of the \f$ x\f$- and \f$ y\f$-coordinates. + */ std::pair to_double () const; /// @} }; /* end Arr_algebraic_segment_traits_2::Point_2 */ -/*! - - -Models the `ArrangementBasicTraits_2::X_monotone_curve_2` concept. -Represents terminal segments of an algebraic curves, -that means vertical segments or \f$ x\f$-monotone segments with no critical -\f$ x\f$-coordinate in the interior of their \f$ x\f$-range. -Terminal segments might either be bounded or unbounded. -By definition, each interior point of -a non-vertical segment has the same arc number (see the documentation of -type `Point_2` above, which is called the arc number of the segment -(note the arc number at the endpoints might differ). -Such segments are represented internally by a 4-tuple \f$ (p,q,cv,arcno)\f$, -where \f$ p\f$ and \f$ q\f$ are the endpoints, \f$ cv\f$ is the supporting curve -that the segment belongs to, and arcno is the arc number of the segment. - -Arbitrary (weakly) \f$ x\f$-monotone segments are presented by a range -of `X_monotone_curve_2` instances, whose union equals the segment. -The functor `Construct_x_monotone_segment_2` allows their construction. -To construct all (maximal) terminal segments of a curve, -use the `Make_x_monotone_2` functor supplied by the traits class. - -*/ +/*! Models the `ArrangementBasicTraits_2::X_monotone_curve_2` concept. + * Represents terminal segments of an algebraic curves, that means vertical + * segments or \f$ x\f$-monotone segments with no critical \f$ x\f$-coordinate + * in the interior of their \f$ x\f$-range. Terminal segments might either be + * bounded or unbounded. By definition, each interior point of a non-vertical + * segment has the same arc number (see the documentation of type `Point_2` + * above, which is called the arc number of the segment (note the arc + * number at the endpoints might differ). Such segments are represented + * internally by a 4-tuple \f$ (p,q,cv,arcno)\f$, where \f$ p\f$ and \f$ q\f$ + * are the endpoints, \f$ cv\f$ is the supporting curve that the segment + * belongs to, and arcno is the arc number of the segment. + * + * Arbitrary (weakly) \f$ x\f$-monotone segments are presented by a range + * of `X_monotone_curve_2` instances, whose union equals the segment. + * The functor `Construct_x_monotone_segment_2` allows their construction. + * To construct all (maximal) terminal segments of a curve, + * use the `Make_x_monotone_2` functor supplied by the traits class. + */ class X_monotone_curve_2 { public: /// \name Modifiers /// @{ -/*! -returns the supporting algebraic curve of `s`. -*/ +/*! returns the supporting algebraic curve of `s`. + */ Curve_2 curve () const; -/*! -returns whether `s` is a vertical segment. -*/ +/*! returns whether `s` is a vertical segment. + */ bool is_vertical () const; -/*! -returns whether `s` has a finite endpoint on the left -*/ +/*! returns whether `s` has a finite endpoint on the left + */ bool is_finite (CGAL::Arr_curve_end ce) const; -/*! -\pre (The corresponding curve end is finite) -*/ +/*! \pre (The corresponding curve end is finite) + */ Point_2 curve_end (CGAL::Arr_curve_end ce) const; -/*! -returns the arc number of the segment. -\pre (The segment is non-vertical) -*/ +/*! returns the arc number of the segment. + * \pre (The segment is non-vertical) + */ int arcno () const; /*! @@ -395,8 +351,6 @@ Algebraic_real_1 x () const; }; /* end Arr_algebraic_segment_traits_2::X_monotone_curve_2 */ - - - }; /* end Arr_algebraic_segment_traits_2 */ + } /* end namespace CGAL */ diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_batched_point_location.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_batched_point_location.h index bafb54b7db7b..d71d0f7faf9b 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_batched_point_location.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_batched_point_location.h @@ -1,36 +1,38 @@ namespace CGAL { -/*! -\ingroup PkgArrangementOnSurface2PointLocation - -Performs a batched point-location operation on a -given arrangement. It accepts a range of query points, and locates each -point in the arrangement. The query results are returned through the output -iterator. Each query result is given as a pair of the query point and an -object representing the arrangement feature that contains it, namely a -discriminated union container of the bounded types `Face_const_handle`, -`Halfedge_const_handle`, and `Vertex_const_hanlde`. The resulting -pairs in the output sequence are sorted in increasing \f$ xy\f$-lexicographical -order of the query points. The function returns a past-the-end iterator of -the output sequence. - -\cgalHeading{Requirements} - -
    -
  • `InputIterator::value_type` must be `Arrangement_2::Point_2`. -
  • `OutputIterator::value_type` must be convertible to -`std::pair::%Type>`. -
- -\sa `CGAL::Arr_point_location_result` - -*/ -template::%Type>`. + * + * \sa `CGAL::Arr_point_location_result` + * + */ +template -OutputIterator locate (const Arrangement_2& arr, -InputIterator points_begin, -InputIterator points_end, -OutputIterator oi); +OutputIterator locate (const Arrangement_2& arr, + InputIterator begin, + InputIterator end, + OutputIterator oi); } /* namespace CGAL */ - diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_conic_traits_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_conic_traits_2.h index d53d7b3bb21a..afe365a3da4e 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_conic_traits_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_conic_traits_2.h @@ -467,20 +467,23 @@ class Arr_conic_traits_2 { */ Approximate_point_2 operator()(const Point_2& p) const; - /*! Obtain a polyline that approximates an \f$x\f$-monotone curve. The - * polyline is defined by a range of approximate points beginning at - * `oi`. The type `OutputIterator` must dereference the type - * `Approximate_point_2`. The first and last points in the range are always - * the endpoints of the given arc `xcv`. The operator returns a - * past-the-end iterator of the destination range. - * \param oi An output iterator for the resulting polyline. - * \param error The error bound of the polyline approximation. This is - * the Hausdorff distance between the arc and the polyline - * that approximates the arc. + /*! approximates a given \f$x\f$-monotone curve. It computes a sequence of + * approximate points that represent an approximate polyline, and inserts + * them into an output container given through an output iterator. The + * first and last points in the sequence are always approximations of the + * endpoints of the given arc. + * + * \param oi An output iterator for the output container. + * \param error The error bound of the polyline approximation. This is the + * Hausdorff distance between the arc and the polyline that + * approximates the arc. * \param xcv The exact \f$x\f$-monotone arc. * \param l2r A Boolean flag that indicates whether the arc direction is - * left to right. - * \return The past-the-end iterator of the output iterator. + * left to right. + * \return The past-the-end iterator of the output container. + * + * \pre Dereferencing `oi` must yield an object of type + * `Arr_conic_traits_2::Approximate_point_2`. */ template OutputIterator operator()(OutputIterator oi, double error, @@ -521,7 +524,7 @@ class Arr_conic_traits_2 { Trim_2 trim_2_object() const; /*! Obtain an `Approximate_2` functor. */ - Trim_2 approximate_2_object() const; + Approximate_2 approximate_2_object() const; /// @} diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_point_location_result.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_point_location_result.h index 2a48e35b399b..0456c4e06f8c 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_point_location_result.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_point_location_result.h @@ -1,27 +1,28 @@ namespace CGAL { -/*! -\ingroup PkgArrangementOnSurface2PointLocation - -A unary metafunction to determine the return type of a point-location -or vertical ray-shoot query. - -\tparam Arrangement must be an instance of the `CGAL::Arrangement_2` class template. - -\sa `ArrangementPointLocation_2` -\sa `ArrangementVerticalRayShoot_2` -\sa `CGAL::Arr_naive_point_location` -\sa `CGAL::Arr_walk_along_line_point_location` -\sa `CGAL::Arr_landmarks_point_location` -\sa `CGAL::Arr_trapezoid_ric_point_location` -*/ -template +/*! \ingroup PkgArrangementOnSurface2PointLocation + * + * A unary metafunction to determine the return type of a point-location or + * vertical ray-shoot query. + * + * \tparam Arrangement must be an instance of the + * `CGAL::Arrangement_on_surface_2` class template. + * + * \sa `ArrangementPointLocation_2` + * \sa `ArrangementVerticalRayShoot_2` + * \sa `CGAL::Arr_naive_point_location` + * \sa `CGAL::Arr_walk_along_line_point_location` + * \sa `CGAL::Arr_landmarks_point_location` + * \sa `CGAL::Arr_trapezoid_ric_point_location` + */ +template struct Arr_point_location_result { /*! The type of the arrangement feature that is the result of a * point-location query or a vertical ray-shoot query, namely, - * `std::variant` + * `std::variant` */ typedef unspecified_type Type; }; /* end Arr_point_location_result */ + } /* end namespace CGAL */ diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_polycurve_traits_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_polycurve_traits_2.h index a1bb1b331d12..e5b8be8d93c7 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_polycurve_traits_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_polycurve_traits_2.h @@ -238,17 +238,22 @@ namespace CGAL { const Point_2& tgt) const; }; - /*! Subdivide a given subcurve into x-monotone subcurves and insert them - * into a given output iterator. + /*! Subdivide a given subcurve into \f$x\f$-monotone subcurves and + * isolated points, and insert them into an output container. An object in + * the output container is represented by a discriminated union container + * that holds either a point or an \f$x\f$-monotone curve. */ class Make_x_monotone_2 { public: - /*! - * \pre if `cv` is not empty then it must be continuous and well-oriented. + /*! performs the subdivision. + * * \param cv the subcurve. - * \param oi an output iterator for the result. Its value type is a variant - * that wraps Point_2 or an X_monotone_curve_2 objects. - * \return the past-the-end iterator. + * \param oi The output iterator that points at the output container. + * \return the past-the-end iterator of the output container. + * + * \pre if `cv` is not empty, then it must be continuous and well-oriented. + * \pre Dereferencing `oi` must yield a polymorphic object of type + * `std::variant<`\link Arr_polycurve_traits_2::Point_2 `Point_2` \endlink, `X_monotone_curve_2>`. */ template OutputIterator operator()(const Curve_2& cv, OutputIterator oi) const; diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h index 7a39bd94d777..38c0403f9fd6 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h @@ -2,51 +2,53 @@ namespace CGAL { /*! \ingroup PkgArrangementOnSurface2Funcs * - * Produces the symbolic vertical decomposition of a given arrangement, - * performing a batched vertical ray-shooting query from all arrangement - * vertices, such that every vertex is associated with a pair of objects, one - * corresponds to the arrangement feature that lies below it, and the other - * corresponds to the feature that lies above it. The output of this function - * can be readily used for inserting vertical walls and physically decomposing - * the arrangement into pseudo-trapezoids. To do this, it is convenient to - * process the vertices in an ascending \f$ xy\f$-lexicographic order. The - * visible objects are therefore returned through an output iterator, which - * pairs each finite arrangement vertex with the two features it "sees", such - * that the vertices are given in ascending \f$ xy\f$-lexicographic order. + * produces the symbolic vertical decomposition of a given arrangement. More + * precisely, this function performs a batched vertical ray-shooting query from + * every arrangement vertex, and pairs each vertex with a pair of polymorphic + * objects, one corresponds to the arrangement feature that lies below it, and + * the other corresponds to the feature that lies above it. * - * Produces the symbolic vertical decomposition of the `arr` arrangement. More - * precisely, it performs a batched vertical ray-shooting query from all - * arrangement vertices, such that every vertex is associated with a pair of - * objects, one corresponding to the arrangement feature that lies below it, - * while the other corresponds to the feature that lies above it. The query - * results are returned through the output iterator, which pairs each finite - * arrangement vertex with a pair of objects, the first represents the feature - * below the vertex, and the second represents the feature that lies above - * it. Each object is an optional variant that wraps a handle to an arrangement - * feature. If the vertex is the top end-vertex of a vertical edge, we say that + * The finite arrangement vertices and the features they "see", if exist, + * that are, the query results, are inserted in ascending \f$xy\f$-lexicographic + * order (of the query vertex) into an output container given through an output + * iterator. If the vertex is the top end-vertex of a vertical edge, we say that * there is no feature below it; similarly, if it is the bottom end-vertex of a - * vertical edge, we say that there is no feature above it. In these cases the - * optional object is set to be empty; otherwise it is set as follows: + * vertical edge, we say that there is no feature above it. Each feature, if + * exists, is represented by a discriminated union container that holds an + * object of one of the following types: + * *
    - *
  • `Halfedge_const_handle`, if the vertex is located above (or below) an - * edge. The given halfedge is always directed from right to left. In case - * there is no concrete edge below (or above) the vertex, and the arrangement - * is unbounded, then the object returned is a fictitious halfedge. - *
  • `Face_const_handle`, in case there is no edge below (or above) - * the vertex, and the arrangement is bounded. - *
  • `Vertex_const_handle`, in case the vertex is located vertically above - * (or below) another arrangement vertex. - *
The function returns a past-the-end iterator for its output sequence. + *
  • `Arrangement_on_surface_2::Halfedge_const_handle`, if the vertex is + * located above (or below) an edge. The given halfedge is always directed + * from right to left. In case there is no concrete edge below (or above) + * the vertex, and the arrangement is unbounded, then the object returned + * is a fictitious halfedge. + *
  • `Arrangement_on_surface_2::Face_const_handle`, in case there is no edge + * below (or above) the vertex, and the arrangement is bounded. + *
  • `Arrangement_on_surface_2::Vertex_const_handle`, in case the vertex is + * located vertically above (or below) another arrangement vertex. + * * - * \cgalHeading{Requirements} + * The output of this function can be readily used for inserting vertical walls + * and physically decomposing the arrangement into pseudo-trapezoids. * - * `OutputIterator::value_type` must be - * `pair >`. + * \param arr The arrangement. + * \param oi The output iterator that points at the output container. + * \return The past-the-end iterator of the output container. + * + * \cgalHeading{Requirements} * + * \pre Dereferencing `oi` must yield an object of type + * `std::pair>>, + * where `Type` is + * `std::variant`. */ -template -OutputIterator decompose (const Arrangement_2& arr, -OutputIterator oi); +template +OutputIterator +decompose(const Arrangement_on_surface_2& arr, + OutputIterator oi); } /* namespace CGAL */ diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h index a269c6e01842..465f1f3a9b20 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_2.h @@ -379,37 +379,4 @@ template bool remove_vertex(Arrangement_2& arr, typename Arrangement_2::Vertex_handle v); -/*! \ingroup PkgArrangementOnSurface2Funcs - * - * Compute the zone of the given \f$ x\f$-monotone curve in the existing - * arrangement. Meaning, it output the arrangement's vertices, edges and faces - * that the \f$ x\f$-monotone curve intersects. The order of the objects is the - * order that they are discovered when traversing the \f$ x\f$-monotone curve - * from left to right. - * - * A given point-location object is used for answering point-location queries - * during the insertion process. By default, the function uses the "walk along - * line" point-location strategy - namely an instance of the class - * `Arr_walk_along_line_point_location >`. - * - * Compute the zone of the given \f$ x\f$-monotone curve `c` in the arrangement - * `arr`. - * - * \pre If provided, `pl` must be attached to the given arrangement `arr`. - * - * \cgalHeading{Requirements} - * - *
      - *
    • The instantiated `GeomTraits` class must model the - * `ArrangementXMonotoneTraits_2` concept. - *
    • The point-location object `pl`, must model the - * `ArrangementPointLocation_2` concept. - *
    - */ -template -OutputIterator zone(Arrangement_2& arr, - const typename Traits::X_monotone_curve_2& c, - OutputIterator oi, const PointLocation& pl); - } /* namespace CGAL */ diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h index 2c0d60278730..48485644adeb 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h @@ -1294,38 +1294,45 @@ bool remove_vertex /*! \ingroup PkgArrangementOnSurface2Funcs * - * Compute the zone of the given \f$ x\f$-monotone curve in the existing - * arrangement. Meaning, it output the arrangement's vertices, edges and faces - * that the \f$ x\f$-monotone curve intersects. The order of the objects is the - * order that they are discovered when traversing the \f$ x\f$-monotone curve - * from left to right. + * computes the zone of the given \f$x\f$-monotone curve in a given + * arrangement. More precisely, this function finds the arrangement vertices, + * edges ,and faces that the given \f$x\f$-monotone curve intersects, and + * inserts them in the order they are discovered when traversing the + * \f$x\f$-monotone curve from left to right into an output contaiuner given + * through an output iterator. An object in the resulting zone is represented by + * a discriminated union container that holds a vertex handle, halfedge handle, + * or a face handle. * * A given point-location object is used for answering point-location queries * during the insertion process. By default, the function uses the "walk along - * line" point-location strategy - namely an instance of the class + * line" point-location strategy, namely, an instance of the class * `Arr_walk_along_line_point_location >`. + * TopologyTraits>>`. * - * Compute the zone of the given \f$ x\f$-monotone curve `c` in the arrangement - * `arr`. + * \param arr The given arrangement. + * \param c The \f$x\f$-monotone curve. + * \param oi The output iterator that points at the output container. + * \param pl The point-location object. + * \return The past-the-end iterator of the output container. * * \pre If provided, `pl` must be attached to the given arrangement `arr`. + * \pre The instantiated `GeometryTraits` class must model the + * `ArrangementXMonotoneTraits_2` concept. + * \pre The point-location object `pl`, must model the + * `ArrangementPointLocation_2` concept. + * \pre Dereferencing `oi` must yield a polymorphic object of type + * `std::variant`. * * \cgalHeading{Requirements} - * - *
      - *
    • The instantiated `GeometryTraits` class must model the - * `ArrangementXMonotoneTraits_2` concept. - *
    • The point-location object `pl`, must model the - * `ArrangementPointLocation_2` concept. - *
    */ template -OutputIterator zone -(Arrangement_on_surface_2& arr, - const typename GeometryTraits::X_monotone_curve_2& c, - OutputIterator oi, - const PointLocation& pl); +OutputIterator +zone(Arrangement_on_surface_2& arr, + const typename GeometryTraits::X_monotone_curve_2& c, + OutputIterator oi, + const PointLocation& pl); } /* namespace CGAL */ diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h index 4b40d11fd1d7..b48ef555575a 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/CORE_algebraic_number_traits.h @@ -29,88 +29,102 @@ class CORE_algebraic_number_traits { /// \name Utility Functions /// @{ - /*! Obtain the numerator of a rational number. - * \param q A rational number. - * \return The numerator of q. + /*! obtains the numerator of a rational number. + * + * \param q The rational number. + * \return The numerator of `q`. */ Integer numerator(const Rational& q) const; - /*! Obtain the denominator of a rational number. - * \param q A rational number. - * \return The denominator of q. + /*! obtains the denominator of a rational number. + * + * \param q The rational number. + * \return The denominator of `q`. */ Integer denominator(const Rational& q) const; - /*! Convert an integer to an algebraic number. - * \param z An integer. - * \return The algebraic number equivalent to z. + /*! converts an integer to an algebraic number. + * + * \param z The integer. + * \return The algebraic number equivalent to `z`. */ Algebraic convert(const Integer& z) const; - /*! Convert a rational number to an algebraic number. + /*! converts a rational number to an algebraic number. + * * \param q A rational number. - * \return The algebraic number equivalent to q. + * \return The algebraic number equivalent to `q`. */ Algebraic convert(const Rational& q) const; - /*! Construct a rational number that lies strictly between two algebraic + /*! constructs a rational number that lies strictly between two algebraic * values. + * * \param x1 The first algebraic value. * \param x2 The second algebraic value. * \pre The two values are not equal. - * \return A rational number that lies in the open interval (x1, x2). + * \return The rational number that lies in the open interval (`x1`, `x2`). */ Rational rational_in_interval(const Algebraic& x1, const Algebraic& x2) const; - /*! Obtain a range of double-precision floats that contains the given + /*! obtains a range of double-precision floats that contains the given * algebraic number. + * * \param x The given number. - * \return A pair that contain x. + * \return The range of double-precision floats that contain `x`. */ std::pair double_interval(const Algebraic& x) const; - /*! Convert a sequence of rational coefficients to an equivalent sequence - * of integer coefficients. If the input coefficients are q(1), ..., q(k), - * where q(i) = n(i)/d(i) then the output coefficients will be of the - * form: - * n(i) * lcm {d(1), ... , d(k)} - * a(i) = ------------------------------- - * d(i) * gcd {n(1), ... , n(k)} - * - * \param q_begin The begin iterator of the rational sequence. - * \param q_end The past-the-end iterator of the rational sequence. - * \param zoi An output iterator for the integer coefficients. - * \return A past-the-end iterator for the output container. - * \pre The value type of q_begin and q_end is `Rational`, and - * the value type of zoi is `Integer`. + /*! converts a sequence of rational coefficients to an equivalent sequence + * of integer coefficients. If the input coefficients are + * \f$q(1),\ldots,q(k)\f$, where \f$q(i) = n(i)/d(i)\f$, then the output + * coefficients will be of the form: + * \f$a(i) = \frac{n(i) \cdot \mathrm{lcm}(d(1),\ldots,d(k))}{d(i) \cdot \mathrm{gcd}(n(1),\ldots, n(k))}\f$. + * It inserts the output sequence into an output container given through an + * output iterator. + * + * \param begin The begin iterator of the rational coefficients input + * container. + * \param end The past-the-end iterator of the rational coefficients input + * container. + * \param oi The output iterator of the integer coefficients output container. + * \return The past-the-end iterator of the output container. + * + * \pre The value type of `InputIterator` is `Rational`. + * \pre Dereferencing `oi` must yield an object convertible to `Integer`. */ template - OutputIterator convert_coefficients(InputIterator q_begin, - InputIterator q_end, - OutputIterator zoi) const; + OutputIterator convert_coefficients(InputIterator begin, + InputIterator end, + OutputIterator oi) const; - /*! Compute the square root of an algebraic number. + /*! computes the square root of an algebraic number. + * * \param x The number. - * \return The square root of x. - * \pre x is non-negative. + * \return The square root of `x`. + * \pre `x` is non-negative. */ Algebraic sqrt(const Algebraic& x) const; - /*! Compute the roots of a quadratic equations \f$a*x^2+ b*x + c = 0\f$ - * with integer coefficients. + /*! computes the roots of a quadratic equations \f$a*x^2+ b*x + c = 0\f$ + * with integer coefficients, and inserts them into an output container given + * through an output iterator. + * * \param a The coefficient of \f$x^2\f$ * \param b The coefficient of \f$x\f$ * \param c The free term. - * \param oi An output iterator for the real-valued solutions of the - * quadratic equation. - * \return A past-the-end iterator for the output container. - * \pre The value type of oi is Algebraic. + * \param oi The output iterator of the output container of real-valued + * solutions of the quadratic equation. + * \return The past-the-end iterator of the output container. + * + * \pre Dereferencing `oi` must yield an object convertible to `Algebraic`. */ template OutputIterator solve_quadratic_equation(const NT& a, const NT& b, const NT& c, OutputIterator oi) const; - /*! Construct a polynomial with integer coefficients. + /*! constructs a polynomial with integer coefficients. + * * \param coeffs The coefficients of the input polynomial. * \param degree The degree of the input polynomial. * \return The polynomial. @@ -118,8 +132,9 @@ class CORE_algebraic_number_traits { Polynomial construct_polynomial(const Integer* coeffs, unsigned int degree) const; - /*! Construct a polynomial with integer coefficients given rational + /*! constructs a polynomial with integer coefficients given rational * coefficients. + * * \param coeffs The coefficients of the input polynomial. * \param degree The degree of the input polynomial. * \param poly Output: The resulting polynomial with integer coefficients. @@ -131,10 +146,11 @@ class CORE_algebraic_number_traits { unsigned int degree, Polynomial& poly, Integer& poly_denom) const; - /*! Construct two polynomials with integer coefficients such that P(x)/Q(x) - * is a rational function equivalent to the one represented by the two - * given vectors of rational coefficients. It is guaranteed that the GCD - * of P(x) and Q(x) is trivial. + /*! constructs two polynomials with integer coefficients such that + * \f$P(x)/Q(x)\f$ is a rational function equivalent to the one represented + * by the two given vectors of rational coefficients. It is guaranteed that + * the GCD of \f$P(x)\f$ and \f$Q(x)\f$ is trivial. + * * \param p_coeffs The coefficients of the input numerator polynomial. * \param p_degree The degree of the input numerator polynomial. * \param q_coeffs The coefficients of the input denominator polynomial. @@ -143,7 +159,7 @@ class CORE_algebraic_number_traits { * coefficients. * \param q_poly Output: The resulting denominator polynomial with integer * coefficients. - * \return (true) on success; (false) if the denominator is 0. + * \return `true` on success; `false` if the denominator is 0. */ bool construct_polynomials(const Rational* p_coeffs, unsigned int p_degree, @@ -155,58 +171,70 @@ class CORE_algebraic_number_traits { */ int degree(const Polynomial& poly) const; - /*! Evaluate a polynomial at a given x-value. - * \param poly A polynomial. + /*! evaluates a polynomial at a given \f$x\f$-value. + * + * \param poly The polynomial. * \param x The value to evaluate at. - * \return The value of the polynomial at x. + * \return The value of the polynomial at `x`. */ template NT evaluate_at(const Polynomial& poly, NT& x) const; - /*! Compute the derivative of the given polynomial. - * \param poly The polynomial p(x). - * \return The derivative p'(x). + /*! computes the derivative of the given polynomial. + * + * \param poly The polynomial \f$p(x)\f$. + * \return The derivative \f$p'(x)\f$. */ Polynomial derive(const Polynomial& poly) const; - /*! Multiply a polynomial by some scalar coefficient. - * \param poly The polynomial P(x). + /*! multiplies a polynomial by some scalar coefficient. + * + * \param poly The polynomial \f$P(x)\f$. * \param a The scalar value. - * \return The scalar multiplication a*P(x). + * \return The scalar multiplication \f$a \cdot P(x)\f$. */ Polynomial scale(const Polynomial& poly, const Integer& a) const; - /*! Perform "long division" of two polynomials: Given A(x) and B(x) compute - * two polynomials Q(x) and R(x) such that: A(x) = Q(x)*B(x) + R(x) and - * R(x) has minimal degree. - * \param polyA The first polynomial A(x). - * \param polyB The second polynomial A(x). - * \param rem Output: The remainder polynomial R(x). - * \return The quontient polynomial Q(x). + /*! performs "long division" of two polynomials: Given \f$A(x)\f$ and + * \f$B(x)\f$ compute two polynomials \f$Q(x)\f$ and \f$R(x)\f$ such that: + * \f$A(x) = Q(x) \cdot B(x) + R(x)\f$ and \f$R(x)\f$ has minimal degree. + * + * \param poly_a The first polynomial \f$A(x)\f$. + * \param poly_b The second polynomial \f$A(x)\f$. + * \param rem Output: The remainder polynomial \f$R(x)\f$. + * \return The quontient polynomial \f$Q(x)\f$. */ - Polynomial divide(const Polynomial& polyA, - const Polynomial& polyB, + Polynomial divide(const Polynomial& poly_a, + const Polynomial& poly_b, Polynomial& rem) const; - /*! Compute the real-valued roots of a polynomial with integer coefficients, - * sorted in ascending order. + /*! computes the real-valued roots of a polynomial with integer coefficients, + * and inserts them in ascending order into an output container given through + * an output iterator. + * * \param poly The input polynomial. - * \param oi An output iterator for the real-valued root of the polynomial. - * \return A past-the-end iterator for the output container. - * \pre The value type of oi is Algebraic. + * \param oi The output iterator of the output container of real-valued root + * of the polynomial. + * \return The past-the-end iterator of the output container. + * + * \pre Dereferencing `oi` must yield an object convertible to `Algebraic`. */ template OutputIterator compute_polynomial_roots(const Polynomial& poly, OutputIterator oi) const; - /*! Compute the real-valued roots of a polynomial with integer coefficients, - * within a given interval. The roots are sorted in ascending order. + /*! computes the real-valued roots of a polynomial with integer coefficients + * within a given interval, and inserts them in ascending order into an output + * container given through an output iterator. + * * \param poly The input polynomial. * \param x_min The left bound of the interval. * \param x_max The right bound of the interval. - * \param oi An output iterator for the real-valued root of the polynomial. - * \return A past-the-end iterator for the output container. - * \pre The value type of oi is Algebraic. + * \param oi The output iterator of the output container of the real-valued + * root of the polynomial. + * \return The past-the-end iterator of the output container. + * + * \pre Dereferencing `oi` must yield an object convertible to `Algebraic`. */ template OutputIterator compute_polynomial_roots(const Polynomial& poly, diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--Intersect_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--Intersect_2.h index 7f0c1a50fcd5..f13a26422e92 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--Intersect_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--Intersect_2.h @@ -16,26 +16,33 @@ class Intersect_2 { /// A model of this concept must provide: /// @{ - /*! computes the intersections of `xc1` and `xc2` and writes them in an - * ascending lexicographic \f$xy\f$-order into a range beginning at - * `oi`. The type `OutputIterator` must dereference a polymorphic object of - * type `std::variant` that wraps objects of type either type - * `pair` or - * `ArrTraits::X_monotone_curve_2`. An object of the former type represents an - * intersection point with its multiplicity (in case the multiplicity is - * undefined or unknown, it should be set to \f$0\f$). An object of the latter - * type represents an overlapping subcurve of `xc1` and `xc2`. The operator - * returns a past-the-end iterator of the destination range. + /*! computes the intersections of two \f$x\f$-monotone curves and inserts the + * result in ascending \f$xy\f$-lexicographic order into an output container + * given through an output iterator. An intersection, if exists, is + * represented by a discriminated union container that holds either an + * intersection point along with its multiplicity or an overlapping + * \f$x\f$-monotone subcurve. If the multiplicity is undefined or unknown, it + * should be set to \f$0\f$. * - * A special case may occur when the parameter space of the surface, the - * arrangement is embedded on, is identified on the left and right sides of - * the boundary. An intersection point that lies on the identification curve, + * \param xc1 The first \f$x\f$-monotone curve. + * \param xc2 The second \f$x\f$-monotone curve. + * \param oi The output iterator that points at the output container. + * \return The past-the-end iterator of the output container. + * + * A special case may occur when the left and right sides of the boundary of + * the parameter space of the surface, the arrangement is embedded on, are + * identified. An intersection point that lies on the identification curve, * between two \f$x\f$-monotone curves that intersect at their left and right * ends must be ignored. Consider two \f$x\f$-monotone curves that intersect * at their left and right ends, respectively, at a point \f$p\f$ that lies on * the identification curve. If, for example, the number of intersections * between these two curves is greater than 1, the order of intersections is - * non-deterministic. + * nondeterministic. + * + * \pre Dereferencing `oi` must yield an object of type + * `std::optional>`, + * where `%Point_2` is a model of `ArrTraits::Point_2` and + * `X_monotone_curve_2` is a model of `ArrTraits::XMonotoneCurve_2`. */ template OutputIterator operator()(ArrTraits::X_monotone_curve_2 xc1, diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--MakeXMonotone_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--MakeXMonotone_2.h index 3f125aea2f65..a86290bd333d 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--MakeXMonotone_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/Concepts/ArrTraits--MakeXMonotone_2.h @@ -15,12 +15,20 @@ class MakeXMonotone_2 { /// A model of this concept must provide: /// @{ - /*! subdivides the input curve `c` into \f$x\f$-monotone subcurves and - * isolated points, and inserts the results into a range beginning at the given - * output iterator `oi`. The type `OutputIterator` dereferences a - * `std::variant` that wraps either an `ArrTraits::Point_2` object or an - * `ArrTraits::X_monotone_curve_2` object. The operator returns a past-the-end - * iterator for the output sequence. + /*! subdivides an input curve into \f$x\f$-monotone subcurves and isolated + * points, and inserts the results into an output container given through an + * output iterator. An object in the output container is represented by a + * discriminated union container that holds either a point or an + * \f$x\f$-monotone curve. + * + * \param c The input curve. + * \param oi The output iterator that points at the output container. + * \return The past-the-end iterator of the output container. + * + * \pre Dereferencing `oi` must yield a polymorphic object of type + * `std::variant<%Point_2, X_monotone_curve_2>`, where `%Point_2` is a model + * of `ArrTraits::Point_2` and `X_monotone_curve_2` is a model of + * `ArrTraits::XMonotoneCurve_2`. */ template OutputIterator operator()(ArrTraits::Curve_2 c, OutputIterator oi); diff --git a/Arrangement_on_surface_2/examples/Arrangement_on_surface_2/batched_point_location.cpp b/Arrangement_on_surface_2/examples/Arrangement_on_surface_2/batched_point_location.cpp index 6d42fb6ca5f6..f2cbc29815d4 100644 --- a/Arrangement_on_surface_2/examples/Arrangement_on_surface_2/batched_point_location.cpp +++ b/Arrangement_on_surface_2/examples/Arrangement_on_surface_2/batched_point_location.cpp @@ -23,7 +23,7 @@ int main() { Point(1, 4), Point(4, 3), Point(6, 3), Point(3, 2), Point(5, 2), Point(1, 0) }; std::list results; - locate(arr, points.begin(), points.end(), std::back_inserter(results)); + CGAL::locate(arr, points.begin(), points.end(), std::back_inserter(results)); // Print the results. for (auto it = results.begin(); it != results.end(); ++it) From c66218bf8512568ed7eca8d7b46da9442f6d9218 Mon Sep 17 00:00:00 2001 From: Efi Fogel Date: Tue, 19 Sep 2023 13:42:40 +0300 Subject: [PATCH 7/8] Fixed typo --- .../CGAL/Arr_vertical_decomposition_2.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h index 38c0403f9fd6..09f2ad4e5d21 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h @@ -40,7 +40,7 @@ namespace CGAL { * * \pre Dereferencing `oi` must yield an object of type * `std::pair>>, + * std::pair>>`, * where `Type` is * `std::variant Date: Wed, 20 Sep 2023 12:25:17 +0300 Subject: [PATCH 8/8] Forced references (to std::variant) not to spread over more than a single line to pacify older version of Doxygen --- .../CGAL/Arr_vertical_decomposition_2.h | 4 +--- .../Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h | 4 +--- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h index 09f2ad4e5d21..15631d265e38 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arr_vertical_decomposition_2.h @@ -42,9 +42,7 @@ namespace CGAL { * `std::pair>>`, * where `Type` is - * `std::variant`. + * `std::variant`. */ template OutputIterator diff --git a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h index 48485644adeb..5886ce3f19d8 100644 --- a/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h +++ b/Arrangement_on_surface_2/doc/Arrangement_on_surface_2/CGAL/Arrangement_on_surface_2.h @@ -1321,9 +1321,7 @@ bool remove_vertex * \pre The point-location object `pl`, must model the * `ArrangementPointLocation_2` concept. * \pre Dereferencing `oi` must yield a polymorphic object of type - * `std::variant`. + * `std::variant`. * * \cgalHeading{Requirements} */