diff --git a/Generator/doc/Generator/CGAL/Random.h b/Generator/doc/Generator/CGAL/Random.h index 5b00e04a8d5..f67801208a1 100644 --- a/Generator/doc/Generator/CGAL/Random.h +++ b/Generator/doc/Generator/CGAL/Random.h @@ -106,7 +106,8 @@ double upper = 1.0); returns a random `IntType` from the interval \f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type -as `int`, `std::ptrdiff_t`, `std::size_t`,etc. Warning: In contrast to `get_int` this function may return `upper`. +as `int`, `std::ptrdiff_t`, `std::size_t`,etc. +\warning In contrast to `get_int` this function may return `upper`. */ template IntType uniform_smallint( IntType lower=0, IntType upper=9); @@ -114,7 +115,8 @@ template IntType uniform_smallint( IntType lower=0, IntType u returns a random `IntType` from the interval \f$ [\mbox{lower,upper}]\f$. `IntType` can be an integral type -as `int`, `std::ptrdiff_t`, `std::size_t`,etc. Warning: In contrast to `get_int` this function may return `upper`. +as `int`, `std::ptrdiff_t`, `std::size_t`,etc. +\warning In contrast to `get_int` this function may return `upper`. */ template IntType uniform_int( IntType lower=0, IntType upper=9); diff --git a/Generator/doc/Generator/CGAL/point_generators_2.h b/Generator/doc/Generator/CGAL/point_generators_2.h index c47d3ed6976..ef2afb7bff0 100644 --- a/Generator/doc/Generator/CGAL/point_generators_2.h +++ b/Generator/doc/Generator/CGAL/point_generators_2.h @@ -11,25 +11,21 @@ are needed from `rnd` for each point. The function `perturb_points_2` perturbs each point in a given range of points by a random amount. -Requirements --------------- +###Requires ### +- `Creator` must be a function object accepting two + `double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point + `(x,y)` of type `P`. + Predefined implementations for these creators like the default are + described in Section \ref sectionCreatorFunctionObjects. -
    -
  • `Creator` must be a function object accepting two -`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point -`(x,y)` of type `P`. +- The `value_type` of the `ForwardIterator` must be assignable + to `P`. +- `P` is equal to the `value_type` of the + `ForwardIterator` when using the default initializer. +- The expressions `to_double((*first).x())` and + `to_double((*first).y())` must result in the respective + coordinate values. -Predefined implementations for these creators like the default are -described in Section \ref sectionCreatorFunctionObjects . - -
  • The `value_type` of the `ForwardIterator` must be assignable -to `P`. -
  • `P` is equal to the `value_type` of the -`ForwardIterator` when using the default initializer. -
  • The expressions `to_double((*first).x())` and -`to_double((*first).y())` must result in the respective -coordinate values. -
\sa `CGAL::points_on_segment_2` \sa `CGAL::points_on_square_grid_2` @@ -51,7 +47,7 @@ namespace CGAL { \ingroup PkgGenerators creates \f$ n\f$ points equally spaced on the segment from \f$ p\f$ to \f$ q\f$, -i.e. \f$ \forall i: 0 \le i < n: o[i] := \frac{n-i-1}{n-1}\, p + +i.e.\ \f$ \forall i: 0 \le i < n: o[i] := \frac{n-i-1}{n-1}\, p + \frac{i}{n-1}\, q\f$. Returns the value of \f$ o\f$ after inserting the \f$ n\f$ points. @@ -81,20 +77,19 @@ the \f$ n\f$ points. The function `points_on_square_grid_2` generates a given number of points on a square grid whose size is determined by the number of points to be generated. -Requirements --------------- -
    -
  • `Creator` must be a function object accepting two -`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point -`(x,y)` of type `P`. Predefined implementations for these -creators like the default can be found in -Section \ref sectionCreatorFunctionObjects . -
  • The `OutputIterator` must accept values of type `P`. If the -`OutputIterator` has a `value_type` the default -initializer of the `creator` can be used. `P` is set to -the `value_type` in this case. -
+###Requires### + +- `Creator` must be a function object accepting two + `double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point + `(x,y)` of type `P`. Predefined implementations for these + creators like the default can be found in + Section \ref sectionCreatorFunctionObjects. +- The `OutputIterator` must accept values of type `P`. If the + `OutputIterator` has a `value_type` the default + initializer of the `creator` can be used. `P` is set to + the `value_type` in this case. + \sa `CGAL::perturb_points_2` \sa `CGAL::points_on_segment_2` @@ -123,22 +118,19 @@ in the range \f$ [first,last)\f$. Three random numbers are needed from `rnd` for each point. Returns the value of `first2` after inserting the \f$ n\f$ points. -Requirements --------------- +###Requires ### -
    -
  • `Creator` must be a function object accepting two -`double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point -`(x,y)` of type `P`. Predefined implementations for these -creators like the default can be found in -Section \ref sectionCreatorFunctionObjects . -
  • The `value_type` of the `RandomAccessIterator` must be -assignable to `P`. `P` is equal to the `value_type` of the -`RandomAccessIterator` when using the default initializer. -
  • The expressions `to_double((*first).x())` and -`to_double((*first).y())` must result in the respective -coordinate values. -
+- `Creator` must be a function object accepting two + `double` values \f$ x\f$ and \f$ y\f$ and returning an initialized point + `(x,y)` of type `P`. Predefined implementations for these + creators like the default can be found in + Section \ref sectionCreatorFunctionObjects. +- The `value_type` of the `RandomAccessIterator` must be + assignable to `P`. `P` is equal to the `value_type` of the + `RandomAccessIterator` when using the default initializer. +- The expressions `to_double((*first).x())` and + `to_double((*first).y())` must result in the respective + coordinate values. \sa `CGAL::perturb_points_2` \sa `CGAL::points_on_segment_2` @@ -218,7 +210,7 @@ typedef const Point_2& reference; /*! \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly distributed in the open disc with radius \f$ r\f$, -i.e. \f$ |*g| < r\f$ . Two random numbers are needed from +i.e.\ \f$ |*g| < r\f$. Two random numbers are needed from `rnd` for each point. */ @@ -292,8 +284,8 @@ typedef const Point_2& reference; /*! \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly distributed in the half-open square with side length \f$ 2 a\f$, centered -at the origin, i.e. \f$ \forall p = *g: -a \le p.x() < a\f$ and -\f$ -a \le p.y() < a\f$ . +at the origin, i.e.\ \f$ \forall p = *g: -a \le p.x() < a\f$ and +\f$ -a \le p.y() < a\f$. Two random numbers are needed from `rnd` for each point. */ @@ -371,7 +363,7 @@ typedef const Point_2& reference; /*! \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly distributed on the circle with radius \f$ r\f$, -i.e. \f$ |*g| == r\f$ . A single random number is needed from +i.e.\ \f$ |*g| == r\f$. A single random number is needed from `rnd` for each point. */ @@ -445,7 +437,7 @@ typedef const Point_2& reference; /*! \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly distributed on the segment from \f$ p\f$ to \f$ q\f$ (excluding \f$ q\f$), -i.e. \f$ *g == (1-\lambda)\, p + \lambda q\f$ where \f$ 0 \le\lambda< 1\f$ . +i.e.\ \f$ *g == (1-\lambda)\, p + \lambda q\f$ where \f$ 0 \le\lambda< 1\f$. A single random number is needed from `rnd` for each point. \require The expressions `to_double(p.x())` and `to_double(p.y())` must result in the respective `double` representation of the coordinates of \f$ p\f$, and similarly for \f$ q\f$. */ @@ -519,9 +511,9 @@ typedef const Point_2& reference; /*! \f$ g\f$ is an input iterator creating points of type `Point_2` uniformly distributed on the boundary of the square with side length \f$ 2 a\f$, -centered at the origin, i.e. \f$ \forall p = *g:\f$ one +centered at the origin, i.e.\ \f$ \forall p = *g:\f$ one coordinate is either \f$ a\f$ or \f$ -a\f$ and for the -other coordinate \f$ c\f$ holds \f$ -a \le c < a\f$ . +other coordinate \f$ c\f$ holds \f$ -a \le c < a\f$. A single random number is needed from `rnd` for each point. */ @@ -612,7 +604,7 @@ std::size_t n, std::size_t i = 0); /*! returns the range in which the point -coordinates lie, i.e. \f$ \forall x: |x| \leq\f$ `range()` and +coordinates lie, i.e.\ \f$ \forall x: |x| \leq\f$ `range()` and \f$ \forall y: |y| \leq\f$`range()` */ double range(); diff --git a/Generator/doc/Generator/CGAL/point_generators_3.h b/Generator/doc/Generator/CGAL/point_generators_3.h index 441fdbd651e..11005fa186b 100644 --- a/Generator/doc/Generator/CGAL/point_generators_3.h +++ b/Generator/doc/Generator/CGAL/point_generators_3.h @@ -11,24 +11,21 @@ inserting the \f$ n\f$ points. The function `points_on_cube_grid_3` generates a given number of points on a cubic grid whose size is determined by the number of points to be generated. -Requirements --------------- +###Requires### +- `Creator` must be a function object accepting three + `double` values \f$ x\f$, \f$ y\f$, and \f$ z\f$ and returning an initialized + point `(x,y,z)` of type `P`. Predefined implementations for + these creators like the default can be found in + Section \ref sectionCreatorFunctionObjects . +- The `OutputIterator` must accept values of type `P`. If the + `OutputIterator` has a `value_type` the default + initializer of the `creator` can be used. `P` is set to + the `value_type` in this case. -
    -
  • `Creator` must be a function object accepting three -`double` values \f$ x\f$, \f$ y\f$, and \f$ z\f$ and returning an initialized -point `(x,y,z)` of type `P`. Predefined implementations for -these creators like the default can be found in -Section \ref sectionCreatorFunctionObjects . -
  • The `OutputIterator` must accept values of type `P`. If the -`OutputIterator` has a `value_type` the default -initializer of the `creator` can be used. `P` is set to -the `value_type` in this case. -
-`CGAL::points_on_square_grid_2` +\sa `CGAL::points_on_square_grid_2` -`CGAL::random_selection` +\sa `CGAL::random_selection` */ template diff --git a/Generator/doc/Generator/Concepts/PointGenerator.h b/Generator/doc/Generator/Concepts/PointGenerator.h index 738bdf7dcf0..b93f9b055b4 100644 --- a/Generator/doc/Generator/Concepts/PointGenerator.h +++ b/Generator/doc/Generator/Concepts/PointGenerator.h @@ -36,7 +36,7 @@ typedef Hidden_type value_type; /// @{ /*! -return an absolute bound for +returns an absolute bound for the coordinates of all generated points. */ double range() const; diff --git a/Generator/doc/Generator/Generator.txt b/Generator/doc/Generator/Generator.txt index 1321be6c295..b37401f0ae7 100644 --- a/Generator/doc/Generator/Generator.txt +++ b/Generator/doc/Generator/Generator.txt @@ -31,8 +31,8 @@ on a circle (`Random_points_on_circle_2`), on a segment (`Random_points_on_segment`), and on a square (`Random_points_on_square_2`). For generating grid points we provide three functions, -`points_on_segment_2()`, -`points_on_square_grid_2()` that write to output iterators and +`::points_on_segment_2()`, +`::points_on_square_grid_2()` that write to output iterators and an input iterator `Points_on_segment_2`. For 3D points, input iterators are provided for random points uniformly @@ -48,34 +48,34 @@ distributed in a \f$ d\f$-dimensional cube (`Random_points_in_cube_d`) or \f$ d\f$-dimensional ball (`Random_points_in_ball_d`) or on the boundary of a sphere (`Random_points_on_sphere_d`). For generating grid points, we provide the function -`points_on_grid_d()` that writes to +`::points_on_grid_d()` that writes to an output iterator. We also provide two functions for generating more complex geometric objects. -The function `random_convex_set_2()` computes a random convex planar +The function `::random_convex_set_2()` computes a random convex planar point set of a given size where the points are drawn from a specific -domain and `random_polygon_2()` generates a random simple polygon from +domain and `::random_polygon_2()` generates a random simple polygon from points drawn from a specific domain. -## Random Perturbations ## +## %Random Perturbations ## Degenerate input sets like grid points can be randomly perturbed by a small amount to produce quasi-degenerate test sets. This challenges numerical stability of algorithms using inexact arithmetic and exact predicates to compute the sign of expressions slightly off from zero. -For this the function `perturb_points_2()` is provided. +For this the function `::perturb_points_2()` is provided. ## Adding Degeneracies ## For a given point set certain kinds of degeneracies can be produced -by adding new points. The `random_selection()` function is +by adding new points. The `::random_selection()` function is useful for generating multiple copies of identical points. -The function `random_collinear_points_2()` adds collinearities to +The function `::random_collinear_points_2()` adds collinearities to a point set. ## Support Functions and Classes for Generators ## -The function `random_selection()` chooses \f$ n\f$ items at random from a random +The function `::random_selection()` chooses \f$ n\f$ items at random from a random access iterator range which is useful to produce degenerate input data sets with multiple entries of identical items.