.. _constraints:

Constriants
===========

.. index::
   single: Constraints
   ! single: Verify() function
   see: Assertions; Constraints

The Verify() function
---------------------

An assertion is made by a call to the ``Verify()`` function with a
value as the first argument and a constraint on that value as the
second argument. "Value" is meant to be taken in a wide sense since it
may in some cases be a pointer to a function. An optional third
argument may be given to include a custom error message. This message
will be included in the test report if the test fails.

There is also a short form of the ``Verify()`` function, taking only
one argument. This argument may be an expression but it must be
possible to cast the result to ``bool``. ::

  // A typical call.
  Verify(MyValue, SomeConstraint);

  // It may also includes a custom error message
  Verfify(MyValue, SomeConstraint, "My custom error message");

  // Short form
  Verify(MyValue == SomeValue);

  // Short form with custom error message.
  Verify(MyValue == SomeValue, "My custom error message");

The short form is handy if one which to fail a test for some reason. ::

  // This will always fail.
  Verify(false, "Test not implemented");

Constraints are functors, i.e. objects with the function call operator
defined. They take one argument of same type as the value to verify
and returns ``true`` if the value fulfills the constraint. If the
constraint is not fulfilled by the value it throws a ``x_test_failed``
exception.
 
``Verify()`` and its alias ``VERIFY()`` are actually macros and will
expand to a call to the ``verify()`` function. There is no magic in
there however, the macro will only add the current file and line to
the call, i.e. ::

  // This macro call
  Verify(MyValue, SomeConstriant);
  
  // will expand to
  verify(__FILE__, __LINE__, MyValue, SomeConstraint);

There is a rich set of predefined constraints. Below follows a list of
them and their syntax. Many constraints exist in an inverse form, which
of course verifies the inverse constraint. Existence of an inverse form
is marked with "(inv)" in the list.


.. index:: ! Constraints

Value constraints
-----------------

:index:`True <Constraints; True>`
  Check if a value is true. ::

    Verify(MyValue, Is.True);

:index:`False <Constraints; False>`
  Check if a value is false. ::

    Verify(MyValue, Is.False);

:index:`Null <Constraints; Null>` (inv)
  Check if a value is NULL. This constraint is only defined for pointer
  types. ::

    Verify(MyPointer, Is.Null);

    // Inverse form
    Verify(MyPointer, Is.Not.Null);

:index:`NaN <Constraints; NaN>` (inv)
  Check if a value is not-a-number. This check uses the
  ``numeric_limits`` template for the type of the given value. ::

    Verify(MyValue, Is.NaN);

    // Inverse form
    Verify(MyValue, Is.Not.NaN);

:index:`NegativeInfinity <Constraints; NegativeInfinity>` (inv)
  Check if a value is negative infinity. This check uses the
  ``numeric_limits`` template for the type of the given value. ::

    Verify(MyValue, Is.NegativeInfinity);

    // Inverse form
    Verify(MyValue, Is.Not.NegativeInfinity);

:index:`PositiveInfinity <Constraints; PositiveInfinity>` (inv)
  Check if a value is positive infinity. This check uses the
  ``numeric_limits`` template for the type of the given value. ::

    Verify(MyValue, Is.PositiveInfinity);

    // Inverse form
    Verify(MyValue, Is.Not.PositiveInfinity);

:index:`Infinity <Constraints; Infinity>` (inv)
  Check if a value is either positive or negative infinity. This check
  uses the ``numeric_limits`` template for the type of the given
  value. ::

    Verify(MyValue, Is.Infinity);

    // Inverse form
    Verify(MyValue, Is.Not.Infinity);

:index:`LessThan <Constraints; LessThan>` (inv)
  Check if a value is less than a given value. ::

    Verify(MyValue, Is.LessThan(Limit));

    // Inverse form
    Verify(MyValue, Is.Not.LessThan(Limit));

:index:`LessThanOrEqualTo <Constraints; LessThanOrEqualTo, Constraints; AtMost>` (inv), AtMost
  Check if a value is less than or equal to a given value. ::

    Verify(MyValue, Is.LessThanOrEqualTo(Limit));
    Verify(MyValue, Is.AtMost(Limit));

    // Inverse form
    Verify(MyValue, Is.Not.LessThanOrEqualTo(Limit));

:index:`EqualTo <Constraints; EqualTo>` (inv)
  Check that a value is equal to another value. ::

    Verify(MyValue, Is.EqualTo(SomeValue));

    // Inverse form
    Verify(MyValue, Is.Not.EqualTo(SomeValue));

:index:`GreaterThanOrEqualTo <Constraints; GreaterThanOrEqualTo, Constraints; AtLeast>` (inv), AtLeast
  Check if a value is greater than or equal to a given value. ::

    Verify(MyValue, Is.GreaterThanOrEqualTo(Limit));
    Verify(MyValue, Is.AtLeast(Limit));

    // Inverse form
    Verify(MyValue, Is.Not.GreaterThanOrEqualTo(Limit));

:index:`GreaterThan <Constraints; GreaterThan>` (inv)
  Check if a value is greater than a given value. ::

    Verify(MyValue, Is.GreaterThan(Limit));

    // Inverse form
    Verify(MyValue, Is.Not.GreaterThan(Limit));

:index:`SameAs <Constraints; SameAs>` (inv)
  Check if a two instances are the same, useful for pointers and
  references. ::

    Verify(MyReference, Is.SameAs(SomeReference));

    // Inverse form
    Verify(MyReference, Is.Not.SameAs(SomeReference));

:index:`InRange <Constraints; InRange>` (inv)
  Check that a value lies between two other values. The default is to
  include points on the boundery. ::

    Verify(MyValue, Is.InRange(Low, High));

    // Inverse form
    Verify(MyValue, Is.Not.InRange(Low,High));

:index:`Within <Constraints; Within>`  (inv)
  Check that a value is within a symmetric interval around some given
  value. The interval may be given in either percent or in absolute
  units. ::

    Verify(MyValue, Is.Within(p).PercentOf(SomeValue));
    Verify(MyValue, Is.Within(u).UnitsOf(SomeValue));

    // Inverse form
    Verify(MyValue, Is.Not.Within(p).PercentOf(SomeValue));
    Verify(MyValue, Is.Not.Within(u).UnitsOf(SomeValue));
  
:index:`CloseTo <Constraints; CloseTo>`
  CloseTo is a short form of ``Within(1e-6).UnitsOf(SomeValue)``, mostly
  for floating point comparison. If a different limit is desired this
  can be changed by setting the ``Limit`` property on the ``CloseTo``
  object in e.g. the suite setup method. ::

    // Change limit, in e.g. suite_setup
    CloseTo.Limit = 1e-3;

    // statement in some test method 
    Verify(MyValue, Is.CloseTo(SomeValue));

:index:`Constrained <Constraints; Constrained>` (inv)
  Used for custom constraints with no arguments. The custom operation
  is supplied with the ``Using()`` method. It must be a functor taking
  one argument and returning ``true`` or ``false`` depending on if the
  value fulfills the operation or not ::

    Verify(MyValue, Is.Constrained.Using(MyFunctor));

    // Inverse form
    Verify(MyValue, Is.Not.Constrained.Using(MyFunctor));
  
:index:`RelatedTo <Constraints; RelatedTo>` (inv)
  Used for custom constraints with one argument. The custom operation
  is supplied with the ``Using()`` method. It must be a functor taking
  two arguments and returning ``true`` or ``false`` depending on if the
  two values fulfills the relation or not. ::

    Verify(MyValue, Is.RelatedTo(SomeValue).Using(MyRelationFunctor));

    // Inverse form
    Verify(MyValue, Is.Not.RelatedTo(SomeValue).Using(MyRelationFunctor));

  This could for example be used for string matching using regular
  expressions. Assume that ``Match`` is a functor taking a string as
  the first argument and a regular expression as a second argument and
  returns ``true`` if the string matches the expression and ``false``
  otherwise. Then one could write ::

    Verify(MyString, Is.RelatedTo(MyRegExp).Using(Match));


.. index:: Constraints; Custom

Customizing value constraints
-----------------------------

Constraints like ``LessThan``, ``EqualTo`` and thier friends are based
on the corresponding operators, ``<``, ``==``, etc. If this is not
appropriate for a type that is to be verified, e.g. if the operator is
not defined for the type, it is possible to supply a custom functor to
the constraint. This is done by the ``Using()`` method. 

For example, suppose a complex number is modeled as ::

  struct complex {
    double Real;
    double Imag;
  };

and that we wish to verify that the absolute value of a complex number
is less than some value. There is no constraint that does that "out of
the box". But if we define ::

  class abs_value_less {
  public:
    bool operator(complex lhs, double, rhs) {
      return ((lhs.Real*lhs.Real + lhs.Imag*lhs.Imag) < rhs*rhs);
    }
  } AbsValueLess;

Then we can say ::

  Verify(MyComplex, LessThan(MyAbsValue).Using(AbsValueLess));
  
Of course we could have said ::

  Verify((MyComplex.Real*MyComplex.Real + MyComplex.Imag*MyComplex.Imag) < MyAbsValue*MyAbsValue);

However, if the check fails the error message for the former will
contain more information than for the latter case. The reason is that
in the latter case the ``Verify()`` function only sees a boolean
comparison and has no knowledge of the complex value. 

The first construction, with a custom comparison operation, is also
possible to use when `verifying collections of values`_.

Hence, all value constraints have the ``Using()`` method and there is
actually nothing special about the ``RelatedTo`` and ``Constrained``
constraints. They may in fact be used without the ``Using()``
call. Such a test will always fail however, since the default functor
of these constraints returns ``false`` for any value.


.. index:: Constraints; Throws

Throws constraints
------------------

Throws constraints are used in order to check if a function, method or
functor (class with overloaded call operator), throws a certain
exception during invocation. The function or method must have the
signature::

  void my_function()

i.e. returntype ``void`` and no arguments. This is not as a severe
limit as it may first seem. Any function may be wrapped up in such a
function or method. Functors may have any return type, but must still
be callable without arguments.

There are two forms of the exception constraint. The first takes the
exception class to check for as a template argument. The second takes
an instance of the exception class to look for as an argument::
 
  // Template form
  Throws.Exception<some_exception_class>()

  // Argument form
  Throws(SomeExceptionInstance)

The latter form uses call by reference and will copy the actual
exception thrown during invocation into the given instance. That way
it is possible to examine exceptions further e.g. to verify error
messages etc. For example::

  x_my_exception MyException;

  Verify(my_function, Throws(MyException));
  Verify(MyException.Message.find("my string") != string::npos);

The above will first check that ``my_function`` throws an instance of
``x_my_exception``, then check that the string ``Message`` of that
instance contains the string "my string".

The general syntax is::

  // Function
  Verify(my_function, Throws.Exception<exception_class>());
  Verify(my_function, Throws(ExceptionInstance));

  // Method
  Verify(MyInstance, my_method, Throws.Exception<exception_class>());
  Verify(MyInstance, my_method, Throws(ExceptionInstance));

  // Functor
  Verify(MyFunctorInstance, Throws.Exception<exception_class>());
  Verify(MyFunctorInstance, Throws(ExceptionInstance));

.. index:: Collections

Verifying collections of values
-------------------------------

It is possible to verify collections of values, e.g. arrays, vectors
or lists against constraints. This is done by using ``Each`` in
place of a single value. E.g. suppose that the array ``MyArray`` is to
be verified against the array ``Expected``, both of length 10. This
would be done as follows::

  // Check that corresponding elements are equal.
  Verify(Each(MyArray, MyArray+10), Is.EqualTo(Each(Expected, Expected+10)));

  // Suppose MyArray and Expected where vectors. Then the test would be
  Verify(Each(MyArray.begin(), MyArray.end()), Is.EqualTo(Each(Expected.begin(), Expected.end())));

This will verify that each element in ``MyArray`` is equal to the
corresponding element in ``Expected``. This construction may be used
together with all value constraints. ::

  // Check that each element is less than corresponding element
  Verify(Each(MyArray, MyArray+10), Is.LessThan(Each(Expected, Expected+10)));

Note that ``MyArray`` and ``Expected`` need not to be of the same
type, it is enough that the constraint (e.g. EqualTo) is defined
between the elements.

The ``Each`` construction may also be used to verify a collection
against a single value. ::

  // Check that all values are less than 3
  Verify(Each(MyArray, MyArray+10), Is.LessThan(3));

  // Verify that no element is NaN
  Verify(Each(MyArray, MyArray+10), Is.Not.NaN);