<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<section id="safe_numerics.checked_integer_arithmetic">
  <title>safe_compare&lt;T, U&gt;</title>

  <?dbhtml stop-chunking?>

  <section>
    <title>Synopsis</title>

    <programlisting>// compare any pair of integers
template&lt;class T, class U&gt;
bool constexpr safe_compare::less_than(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool constexpr safe_compare::greater_than(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool constexpr safe_compare::less_than_equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool constexpr safe_compare::greater_than_equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool constexpr safe_compare::equal(const T &amp; lhs, const U &amp; rhs);

template&lt;class T, class U&gt;
bool constexpr safe_compare::not_equal(const T &amp; lhs, const U &amp; rhs);</programlisting>
  </section>

  <section>
    <title>Description</title>

    <para>Compare two primitive integers. These functions will return a
    correct result regardless of the type of the operands. Specifically it is
    guaranteed to return the correct arithmetic result when comparing signed
    and unsigned types of any size. It does not follow the standard C/C++
    procedure of converting the operands to some common type then doing the
    compare. So it is not equivalent to the C/C++ binary operations
    <code>&lt;</code>, <code>&gt;</code>, <code><code>&gt;</code>=</code>,
    <code>&lt;=</code>, <code>==</code>, <code>!=</code> and shouldn't be used
    by user programs which should be portable to standard C/C++ integer
    arithmetic. The functions are free functions defined inside the namespace
    <code>boost::numeric::safe_compare</code>.</para>
  </section>

  <section>
    <title>Type requirements</title>

    <para>All template parameters of the functions must be C/C++ built-in
    integer types, <code><code>char</code></code>,
    <code><code>int</code></code> ....</para>
  </section>

  <section>
    <title>Complexity</title>

    <para>Each function performs one and only one arithmetic operation.</para>
  </section>

  <section>
    <title>Example of use</title>

    <programlisting>#include &lt;cassert&gt;
#include &lt;safe_compare.hpp&gt;

using namespace boost::numeric;
const short int x = -64;
const unsigned int y = 42000;

assert(x &lt; y); // fails
assert(safe_compare::less_than(x, y)); // OK</programlisting>
  </section>

  <section>
    <title>Header</title>

    <para><ulink
    url="../../include/boost/safe_numerics/safe_compare.hpp"><code>#include
    &lt;boost/numeric/safe_numerics/safe_compare.hpp&gt;
    </code></ulink></para>
  </section>
</section>
