# Parma_Polyhedra_Library::Generator Class Reference
[C++ Language Interface]

A line, ray, point or closure point. More...

`#include <ppl.hh>`

Inherits Parma_Polyhedra_Library::Linear_Row.

Inherited by Parma_Polyhedra_Library::Grid_Generator`[private]`.

List of all members.

## Public Types
enum | Type { LINE, RAY, POINT, CLOSURE_POINT }
| The generator type. More...
## Public Member Functions
| Generator (const Generator &g)
| Ordinary copy constructor.
| ~Generator ()
| Destructor.
Generator & | operator= (const Generator &g)
| Assignment operator.
dimension_type | space_dimension () const
| Returns the dimension of the vector space enclosing `*this`.
Type | type () const
| Returns the generator type of `*this`.
bool | is_line () const
| Returns `true` if and only if `*this` is a line.
bool | is_ray () const
| Returns `true` if and only if `*this` is a ray.
bool | is_point () const
| Returns `true` if and only if `*this` is a point.
bool | is_closure_point () const
| Returns `true` if and only if `*this` is a closure point.
Coefficient_traits::const_reference | coefficient (Variable v) const
| Returns the coefficient of `v` in `*this`.
Coefficient_traits::const_reference | divisor () const
| If `*this` is either a point or a closure point, returns its divisor.
memory_size_type | total_memory_in_bytes () const
| Returns a lower bound to the total size in bytes of the memory occupied by `*this`.
memory_size_type | external_memory_in_bytes () const
| Returns the size in bytes of the memory managed by `*this`.
bool | is_equivalent_to (const Generator &y) const
| Returns `true` if and only if `*this` and `y` are equivalent generators.
void | ascii_dump () const
| Writes to `std::cerr` an ASCII representation of `*this`.
void | ascii_dump (std::ostream &s) const
| Writes to `s` an ASCII representation of `*this`.
void | print () const
| Prints `*this` to `std::cerr` using `operator<<`.
bool | ascii_load (std::istream &s)
| Loads from `s` an ASCII representation (as produced by ascii_dump(std::ostream&) const) and sets `*this` accordingly. Returns `true` if successful, `false` otherwise.
bool | OK () const
| Checks if all the invariants are satisfied.
void | swap (Generator &y)
| Swaps `*this` with `y`.
## Static Public Member Functions
static Generator | line (const Linear_Expression &e)
| Returns the line of direction `e`.
static Generator | ray (const Linear_Expression &e)
| Returns the ray of direction `e`.
static Generator | point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
| Returns the point at `e` / `d`.
static Generator | closure_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
| Returns the closure point at `e` / `d`.
static dimension_type | max_space_dimension ()
| Returns the maximum space dimension a Generator can handle.
static void | initialize ()
| Initializes the class.
static void | finalize ()
| Finalizes the class.
static const Generator & | zero_dim_point ()
| Returns the origin of the zero-dimensional space .
static const Generator & | zero_dim_closure_point ()
| Returns, as a closure point, the origin of the zero-dimensional space .
## Related Functions
(Note that these are not member functions.)
std::ostream & | operator<< (std::ostream &s, const Generator &g)
| Output operator.
void | swap (Parma_Polyhedra_Library::Generator &x, Parma_Polyhedra_Library::Generator &y)
| Specializes `std::swap`.
bool | operator== (const Generator &x, const Generator &y)
| Returns `true` if and only if `x` is equivalent to `y`.
bool | operator!= (const Generator &x, const Generator &y)
| Returns `true` if and only if `x` is not equivalent to `y`.
template<typename To >
bool | rectilinear_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
| Computes the rectilinear (or Manhattan) distance between `x` and `y`.
template<typename Temp , typename To >
bool | rectilinear_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
| Computes the rectilinear (or Manhattan) distance between `x` and `y`.
template<typename To >
bool | euclidean_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
| Computes the euclidean distance between `x` and `y`.
template<typename Temp , typename To >
bool | euclidean_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
| Computes the euclidean distance between `x` and `y`.
template<typename To >
bool | l_infinity_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir)
| Computes the distance between `x` and `y`.
template<typename Temp , typename To >
bool | l_infinity_distance_assign (Checked_Number< To, Extended_Number_Policy > &r, const Generator &x, const Generator &y, Rounding_Dir dir, Temp &tmp0, Temp &tmp1, Temp &tmp2)
| Computes the distance between `x` and `y`.
std::ostream & | operator<< (std::ostream &s, const Generator::Type &t)
| Output operator.

## Detailed Description

A line, ray, point or closure point.

An object of the class Generator is one of the following:

- a line ;

- a ray ;

- a point ;

- a closure point ;

where is the dimension of the space and, for points and closure points, is the divisor.

A note on terminology.
  As observed in Section Representations of Convex Polyhedra, there are cases when, in order to represent a polyhedron using the generator system , we need to include in the finite set even points of that are not vertices of . This situation is even more frequent when working with NNC polyhedra and it is the reason why we prefer to use the word `point' where other libraries use the word `vertex'.

How to build a generator.
  Each type of generator is built by applying the corresponding function (`line`, `ray`, `point` or `closure_point`) to a linear expression, representing a direction in the space; the space dimension of the generator is defined as the space dimension of the corresponding linear expression. Linear expressions used to define a generator should be homogeneous (any constant term will be simply ignored). When defining points and closure points, an optional Coefficient argument can be used as a common divisor for all the coefficients occurring in the provided linear expression; the default value for this argument is 1.

  In all the following examples it is assumed that variables `x`, `y` and `z` are defined as follows:

        Variable x(0);
        Variable y(1);
        Variable z(2);

Example 1
  The following code builds a line with direction and having space dimension :

        Generator l = line(x - y - z);

  As mentioned above, the constant term of the linear expression is not relevant. Thus, the following code has the same effect:

        Generator l = line(x - y - z + 15);

  By definition, the origin of the space is not a line, so that the following code throws an exception:

        Generator l = line(0*x);

Example 2
  The following code builds a ray with the same direction as the line in Example 1:

        Generator r = ray(x - y - z);

  As is the case for lines, when specifying a ray the constant term of the linear expression is not relevant; also, an exception is thrown when trying to build a ray from the origin of the space.

Example 3
  The following code builds the point :

        Generator p = point(1*x + 0*y + 2*z);

  The same effect can be obtained by using the following code:

        Generator p = point(x + 2*z);

  Similarly, the origin can be defined using either one of the following lines of code:

        Generator origin3 = point(0*x + 0*y + 0*z);
        Generator origin3_alt = point(0*z);

  Note however that the following code would have defined a different point, namely :

        Generator origin2 = point(0*y);

  The following two lines of code both define the only point having space dimension zero, namely . In the second case we exploit the fact that the first argument of the function `point` is optional.

        Generator origin0 = Generator::zero_dim_point();
        Generator origin0_alt = point();

Example 4
  The point specified in Example 3 above can also be obtained with the following code, where we provide a non-default value for the second argument of the function `point` (the divisor):

        Generator p = point(2*x + 0*y + 4*z, 2);

  Obviously, the divisor can be usefully exploited to specify points having some non-integer (but rational) coordinates. For instance, the point can be specified by the following code:

        Generator q = point(-15*x + 32*y + 21*z, 10);

  If a zero divisor is provided, an exception is thrown.

Example 5
  Closure points are specified in the same way we defined points, but invoking their specific constructor function. For instance, the closure point is defined by

        Generator c = closure_point(1*x + 0*y + 2*z);

  For the particular case of the (only) closure point having space dimension zero, we can use any of the following:

        Generator closure_origin0 = Generator::zero_dim_closure_point();
        Generator closure_origin0_alt = closure_point();

How to inspect a generator
  Several methods are provided to examine a generator and extract all the encoded information: its space dimension, its type and the value of its integer coefficients.

Example 6
  The following code shows how it is possible to access each single coefficient of a generator. If `g1` is a point having coordinates , we construct the closure point `g2` having coordinates .

        if (g1.is_point()) {
          cout << "Point g1: " << g1 << endl;
          Linear_Expression e;
          for (dimension_type i = g1.space_dimension(); i-- > 0; )
            e += (i + 1) * g1.coefficient(Variable(i)) * Variable(i);
          Generator g2 = closure_point(e, g1.divisor());
          cout << "Closure point g2: " << g2 << endl;
        }
        else
          cout << "Generator g1 is not a point." << endl;

  Therefore, for the point

        Generator g1 = point(2*x - y + 3*z, 2);

  we would obtain the following output:

        Point g1: p((2*A - B + 3*C)/2)
        Closure point g2: cp((2*A - 2*B + 9*C)/2)

  When working with (closure) points, be careful not to confuse the notion of coefficient with the notion of coordinate: these are equivalent only when the divisor of the (closure) point is 1.

## Member Enumeration Documentation

enum Parma_Polyhedra_Library::Generator::Type

The generator type.

Enumerator:

  LINE | The generator is a line.
  RAY | The generator is a ray.
  POINT | The generator is a point.
  CLOSURE_POINT | The generator is a closure point.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.

## Member Function Documentation

Generator line | ( | const Linear_Expression & | e | ) | `[inline, static]`

Returns the line of direction `e`.

Shorthand for Generator Generator::line(const Linear_Expression& e).

Exceptions:

  | std::invalid_argument | Thrown if the homogeneous part of `e` represents the origin of the vector space.

Generator ray | ( | const Linear_Expression & | e | ) | `[inline, static]`

Returns the ray of direction `e`.

Shorthand for Generator Generator::ray(const Linear_Expression& e).

Exceptions:

  | std::invalid_argument | Thrown if the homogeneous part of `e` represents the origin of the vector space.

Generator point | ( | const Linear_Expression & | e = `Linear_Expression::zero()`,
|  | Coefficient_traits::const_reference | d = `Coefficient_one()` |
| ) |  |  | `[inline, static]`

Returns the point at `e` / `d`.

Shorthand for Generator Generator::point(const Linear_Expression& e, Coefficient_traits::const_reference d).

Both `e` and `d` are optional arguments, with default values Linear_Expression::zero() and Coefficient_one(), respectively.

Exceptions:

  | std::invalid_argument | Thrown if `d` is zero.

Generator closure_point | ( | const Linear_Expression & | e = `Linear_Expression::zero()`,
|  | Coefficient_traits::const_reference | d = `Coefficient_one()` |
| ) |  |  | `[inline, static]`

Returns the closure point at `e` / `d`.

Shorthand for Generator Generator::closure_point(const Linear_Expression& e, Coefficient_traits::const_reference d).

Both `e` and `d` are optional arguments, with default values Linear_Expression::zero() and Coefficient_one(), respectively.

Exceptions:

  | std::invalid_argument | Thrown if `d` is zero.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Generator::coefficient | ( | Variable | v | ) | const`[inline]`

Returns the coefficient of `v` in `*this`.

Exceptions:

  | std::invalid_argument | Thrown if the index of `v` is greater than or equal to the space dimension of `*this`.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.

Coefficient_traits::const_reference Parma_Polyhedra_Library::Generator::divisor | ( |  | ) | const`[inline]`

If `*this` is either a point or a closure point, returns its divisor.

Exceptions:

  | std::invalid_argument | Thrown if `*this` is neither a point nor a closure point.

Reimplemented in Parma_Polyhedra_Library::Grid_Generator.

bool Parma_Polyhedra_Library::Generator::is_equivalent_to | ( | const Generator & | y | ) | const

Returns `true` if and only if `*this` and `y` are equivalent generators.

Generators having different space dimensions are not equivalent.

## Friends And Related Function Documentation

std::ostream & operator<< | ( | std::ostream & | s,
|  | const Generator & | g |
| ) |  |  | `[related]`

Output operator.

void swap | ( | Parma_Polyhedra_Library::Generator & | x,
|  | Parma_Polyhedra_Library::Generator & | y |
| ) |  |  | `[related]`

Specializes `std::swap`.

bool operator== | ( | const Generator & | x,
|  | const Generator & | y |
| ) |  |  | `[related]`

Returns `true` if and only if `x` is equivalent to `y`.

bool operator!= | ( | const Generator & | x,
|  | const Generator & | y |
| ) |  |  | `[related]`

Returns `true` if and only if `x` is not equivalent to `y`.

template<typename To >

bool rectilinear_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir |
| ) |  |  | `[related]`

Computes the rectilinear (or Manhattan) distance between `x` and `y`.

Computes the euclidean distance between `x` and `y`.

If the rectilinear distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

If the rectilinear distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

If the euclidean distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

template<typename Temp , typename To >

bool rectilinear_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir,
|  | Temp & | tmp0,
|  | Temp & | tmp1,
|  | Temp & | tmp2 |
| ) |  |  | `[related]`

Computes the rectilinear (or Manhattan) distance between `x` and `y`.

If the rectilinear distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using the temporary variables `tmp0`, `tmp1` and `tmp2`.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

template<typename To >

bool euclidean_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir |
| ) |  |  | `[related]`

Computes the euclidean distance between `x` and `y`.

If the euclidean distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

template<typename Temp , typename To >

bool euclidean_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir,
|  | Temp & | tmp0,
|  | Temp & | tmp1,
|  | Temp & | tmp2 |
| ) |  |  | `[related]`

Computes the euclidean distance between `x` and `y`.

If the euclidean distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using the temporary variables `tmp0`, `tmp1` and `tmp2`.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

template<typename To >

bool l_infinity_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir |
| ) |  |  | `[related]`

Computes the distance between `x` and `y`.

If the distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<To, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

If the distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using variables of type Checked_Number<Temp, Extended_Number_Policy>.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

template<typename Temp , typename To >

bool l_infinity_distance_assign | ( | Checked_Number< To, Extended_Number_Policy > & | r,
|  | const Generator & | x,
|  | const Generator & | y,
|  | Rounding_Dir | dir,
|  | Temp & | tmp0,
|  | Temp & | tmp1,
|  | Temp & | tmp2 |
| ) |  |  | `[related]`

Computes the distance between `x` and `y`.

If the distance between `x` and `y` is defined, stores an approximation of it into `r` and returns `true`; returns `false` otherwise.

The direction of the approximation is specified by `dir`.

All computations are performed using the temporary variables `tmp0`, `tmp1` and `tmp2`.

Note:
  Distances are only defined between generators that are points and/or closure points; for rays or lines, `false` is returned.

std::ostream & operator<< | ( | std::ostream & | s,
|  | const Generator::Type & | t |
| ) |  |  | `[related]`

Output operator.

The documentation for this class was generated from the following file:

- ppl.hh