lines 9-138 of file: include/cppad/utility/near_equal.hpp

{xrst_begin NearEqual}
{xrst_spell
   cout
   endl
}

Determine if Two Values Are Nearly Equal
########################################

Syntax
******

   # ``include <cppad/utility/near_equal.hpp>``

*b* = ``NearEqual`` ( *x* , *y* , *r* , *a* )

Purpose
*******
Returns true,
if *x* and *y* are nearly equal,
and false otherwise.

x
*
The argument *x*
has one of the following possible prototypes

| |tab| ``const`` *Type* & *x* ,
| |tab| ``const std::complex<`` *Type* > & *x* ,

y
*
The argument *y*
has one of the following possible prototypes

| |tab| ``const`` *Type* & *y* ,
| |tab| ``const std::complex<`` *Type* > & *y* ,

r
*
The relative error criteria *r* has prototype

   ``const`` *Type* & *r*

It must be greater than or equal to zero.
The relative error condition is defined as:

.. math::

   | x - y | \leq r ( |x| + |y| )

a
*
The absolute error criteria *a* has prototype

   ``const`` *Type* & *a*

It must be greater than or equal to zero.
The absolute error condition is defined as:

.. math::

   | x - y | \leq a

b
*
The return value *b* has prototype

   ``bool`` *b*

If either *x* or *y* is infinite or not a number,
the return value is false.
Otherwise, if either the relative or absolute error
condition (defined above) is satisfied, the return value is true.
Otherwise, the return value is false.

Type
****
The type *Type* must be a
:ref:`NumericType-name` .
The routine :ref:`CheckNumericType-name` will generate
an error message if this is not the case.
In addition, the following operations must be defined objects
*a* and *b* of type *Type* :

.. list-table::
   :widths: auto

   * - **Operation**
     - **Description**
   * - *a* <= *b*
     - less that or equal operator (returns a ``bool`` object)

Include Files
*************
The file ``cppad/utility/near_equal.hpp``
is included by ``cppad/cppad.hpp``
but it can also be included separately with out the rest of
the ``CppAD`` routines.

Example
*******
{xrst_toc_hidden
   example/utility/near_equal.cpp
}
The file :ref:`near_equal.cpp-name` contains an example
and test of ``NearEqual`` .
It return true if it succeeds and false otherwise.

Exercise
********
Create and run a program that contains the following code:
::

   using std::complex;
   using std::cout;
   using std::endl;

   complex<double> one(1., 0), i(0., 1);
   complex<double> x = one / i;
   complex<double> y = - i;
   double          r = 1e-12;
   double          a = 0;
   bool           ok = CppAD::NearEqual(x, y, r, a);
   if( ok )
   cout << "Ok"    << endl;
   else
   cout << "Error" << endl;

{xrst_end NearEqual}
