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

A line, parameter or point. More...

Inherits Parma_Polyhedra_Library::Generator.

List of all members.

## Public Types

enum | Type { LINE, PARAMETER, POINT }
| The generator type. More...

## Public Member Functions

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_parameter () const
| Returns `true` if and only if `*this` is a parameter.
bool | is_line_or_parameter () const
| Returns `true` if and only if `*this` is a line or a parameter.
bool | is_point () const
| Returns `true` if and only if `*this` is a point.
bool | is_parameter_or_point () const
| Returns `true` if and only if `*this` row represents a parameter or a point.
Grid_Generator & | operator= (const Grid_Generator &g)
| Assignment operator.
Grid_Generator & | operator= (const Generator &g)
| Assignment operator.
Coefficient_traits::const_reference | divisor () const
| Returns the divisor of `*this`.
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 Grid_Generator &y) const
| Returns `true` if and only if `*this` and `y` are equivalent generators.
bool | is_equal_to (const Grid_Generator &y) const
| Returns `true` if `*this` is exactly equal to `y`.
bool | all_homogeneous_terms_are_zero () const
| Returns `true` if and only if all the homogeneous terms of `*this` are .
void | scale_to_divisor (Coefficient_traits::const_reference d)
| Scales `*this` to be represented with a divisor of `d` (if \*this is a parameter or point).
bool | OK () const
| Checks if all the invariants are satisfied.
void | swap (Grid_Generator &y)
| Swaps `*this` with `y`.
void | coefficient_swap (Grid_Generator &y)
| Swaps `*this` with `y`, leaving `*this` with the original capacity.

## Static Public Member Functions

static Grid_Generator | line (const Linear_Expression &e)
| Returns the line of direction `e`.
static Grid_Generator | parameter (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
| Shorthand for Grid_Generator Grid_Generator::parameter(const Linear_Expression& e, Coefficient_traits::const_reference d).
static Grid_Generator | point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
| Returns the point at `e` / `d`.

## Related Functions

(Note that these are not member functions.)
std::ostream & | operator<< (std::ostream &s, const Grid_Generator &g)
| Output operator.
void | swap (Parma_Polyhedra_Library::Grid_Generator &x, Parma_Polyhedra_Library::Grid_Generator &y)
| Specializes `std::swap`.
Grid_Generator | grid_line (const Linear_Expression &e)
| Shorthand for Grid_Generator Grid_Generator::line(const Linear_Expression& e).
Grid_Generator | grid_point (const Linear_Expression &e=Linear_Expression::zero(), Coefficient_traits::const_reference d=Coefficient_one())
| Shorthand for Grid_Generator Grid_Generator::point(const Linear_Expression& e, Coefficient_traits::const_reference d).
bool | operator== (const Grid_Generator &x, const Grid_Generator &y)
| Returns `true` if and only if `x` is equivalent to `y`.
bool | operator!= (const Grid_Generator &x, const Grid_Generator &y)
| Returns `true` if and only if `x` is not equivalent to `y`.
std::ostream & | operator<< (std::ostream &s, const Grid_Generator::Type &t)
| Output operator.

## Detailed Description

A line, parameter or point.

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

- a line ;

- a parameter ;

- a point ;

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

How to build a grid generator.
  Each type of generator is built by applying the corresponding function (`line`, `parameter` or `point`) to a linear expression; 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 parameters, 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 :

        Grid_Generator l = grid_line(x - y - z);

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

        Grid_Generator l = grid_line(0*x);

Example 2
  The following code builds the parameter as the vector which has the same direction as the line in Example 1:

        Grid_Generator q = parameter(x - y - z);

  Note that, unlike lines, for parameters, the length as well as the direction of the vector represented by the code is significant. Thus `q` is not the same as the parameter `q1` defined by

        Grid_Generator q1 = parameter(2x - 2y - 2z);

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

        Grid_Generator q = parameter(0*x);

Example 3
  The following code builds the point :

        Grid_Generator p = grid_point(1*x + 0*y + 2*z);

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

        Grid_Generator p = grid_point(x + 2*z);

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

        Grid_Generator origin3 = grid_point(0*x + 0*y + 0*z);
        Grid_Generator origin3_alt = grid_point(0*z);

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

        Grid_Generator origin2 = grid_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.

        Grid_Generator origin0 = Generator::zero_dim_point();
        Grid_Generator origin0_alt = grid_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 `grid_point` (the divisor):

        Grid_Generator p = grid_point(2*x + 0*y + 4*z, 2);

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

        Grid_Generator p1 = grid_point(-15*x + 32*y + 21*z, 10);

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

Example 5
  Parameters, like points can have a divisor. For instance, the parameter can be defined:

        Grid_Generator q = parameter(2*x + 0*y + 4*z, 2);

  Also, the divisor can be used to specify parameters having some non-integer (but rational) coordinates. For instance, the parameter can be defined:

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

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

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

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

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

  Therefore, for the point

        Grid_Generator g1 = grid_point(2*x - y + 3*z, 2);

  we would obtain the following output:

        Point g1: p((2*A - B + 3*C)/2)
        Parameter g2: parameter((2*A - 2*B + 9*C)/2)

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

## Member Enumeration Documentation

enum Parma_Polyhedra_Library::Grid_Generator::Type

The generator type.

Enumerator:

  LINE | The generator is a line.
  PARAMETER | The generator is a parameter.
  POINT | The generator is a point.

Reimplemented from Parma_Polyhedra_Library::Generator.

## Member Function Documentation

static Grid_Generator Parma_Polyhedra_Library::Grid_Generator::line | ( | const Linear_Expression & | e | ) | `[static]`

Returns the line of direction `e`.

Exceptions:

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

Reimplemented from Parma_Polyhedra_Library::Generator.

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

Shorthand for Grid_Generator Grid_Generator::parameter(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.

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

Returns the point at `e` / `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.

Reimplemented from Parma_Polyhedra_Library::Generator.

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

Returns the divisor of `*this`.

Exceptions:

  | std::invalid_argument | Thrown if `*this` is a line.

Reimplemented from Parma_Polyhedra_Library::Generator.

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

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

Generators having different space dimensions are not equivalent.

void Parma_Polyhedra_Library::Grid_Generator::scale_to_divisor | ( | Coefficient_traits::const_reference | d | ) |

Scales `*this` to be represented with a divisor of `d` (if \*this is a parameter or point).

Exceptions:

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

void Parma_Polyhedra_Library::Grid_Generator::coefficient_swap | ( | Grid_Generator & | y | ) |

Swaps `*this` with `y`, leaving `*this` with the original capacity.

All up to and including the last element of the smaller of `this` and `y` are swapped. The parameter divisor element of `y` is swapped with the divisor element of `*this`.