includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(binops)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Binary Operators)

manpagename(binops)(Template functions for class-type binary operators)

manpagesynopsis()
    bf(#include <utility>)nl()
    bf(#include <bobcat/typetrait>)nl()
    bf(#include <bobcat/binops>)nl()

manpagedescription()
    Classes can overload binary operators. A class named tt(Class) may
overload these binary operators to suit its own needs, allowing, e.g., two
tt(Class) type objects to be added after overloading tt(operator+). Operators
for the binary operators *, /, %, +, -, <<, >>, &, |, and ^ (in this man-page
they are generically indicated as the `tt(@)' operator) can be overloaded by
defining the tt(operator@) function.

    If a class supports copy construction and if it offers binary assignment
operators (i.e., it offers members of the form tt(operator@=)), then the
matching binary operators can all be implemented identically. The
em(move-aware) tt(Class &operator@(Class &&lhs, Class const &rhs)) is easily
implemented in terms of tt(operator@=) (note that the class itself doesn't
have to be `move-aware' to define this function). The move-aware binary
operator one requires a one line implementation, and as its
implementation never changes it could safely be defined tt(inline):
        verb(
Class operator@(Class &&lhs, Class const &rhs)
{
    return std::move(std::move(lhs) @= rhs);
}
        )
    The traditional binary operator can be implemented using its standard
form:
        verb(
Class operator@(Class const &lhs, Class const &rhs)
{
    Class tmp(lhs);
    tmp @= rhs;
    return tmp;
}
        )
    The implementation in tt(bobcat/binops) is slightly more complex as it
allows from lhs or rhs promotions.

    As the binary operators can all be implemented alike their definitions are
perfectly suited for templates: A class offering a particular tt(operator@=)
then automatically also offers the matching binary operators after including
tt(bobcat/binops). Since the binary function templates are not instantiated
until used their definitions can be processed by the compiler even if a class
implements only a subset of the available binary assignment operators.

manpagesection(NAMESPACE)

    The binary operator functions templates in tt(bobcat/binops) are em(not)
implemented in a particular namespace. This allows sources to include
tt(bobcat/binops) in multiple namespaces. 

    If tt(bobcat/binops) is to be used in multiple namespaces then the include
safeguard (using the identifier tt(INCLUDED_BOBCAT_BINOPS_)) must be
suppressed between inclusions of tt(bobcat/binops) in different
namespaces. 

    E.g., to make the binary operator function templates available in a source
file using the tt(namespace FBB) and in a source file using the default
namespace the following scheme can be used:
        verb(
#include <utility>              // ensure std::move is available
#include <bobcat/typetrait>     // required by binops

namespace MY_NAMESPACE
{
    #include <bobcat/binops>    // binary operators available in MY_NAMESPACE
}
#undef INCLUDED_BOBCAT_BINOPS_  // suppress the include guard

#include <bobcat/binops>        // read binops again so the binary
                                // operators can be used in the
                                // default namespace as well
    )

manpagesection(INHERITS FROM)
    -

manpagesection(OVERLOADED OPERATORS)
    The function templates in tt(bobcat/binops) implement all arithmetic
binary operators, both move-aware and the traditional binary operators,
expecting constant lvalue references. They can be used if the matching binary
assignment operators were implemented in the classes for which the templates
must be instantiated. The following operators are available:

Move-aware operators, using temporary objects for its left-hand side operands:
    itemization(
    itb(Class operator*(Class &&lhs, Class const &rhs))
    itb(Class operator/(Class &&lhs, Class const &rhs))
    itb(Class operator%(Class &&lhs, Class const &rhs))
    itb(Class operator+(Class &&lhs, Class const &rhs))
    itb(Class operator-(Class &&lhs, Class const &rhs))
    itb(Class operator<<(Class &&lhs, Class const &rhs))
    itb(Class operator>>(Class &&lhs, Class const &rhs))
    itb(Class operator&(Class &&lhs, Class const &rhs))
    itb(Class operator|(Class &&lhs, Class const &rhs))
    itb(Class operator^(Class &&lhs, Class const &rhs))
    )

`Traditional' operators, using lvalue references to constant objects 
for its left-hand side operands:
    itemization(
    itb(Class operator*(Class const &lhs, Class const &rhs))
    itb(Class operator/(Class const &lhs, Class const &rhs))
    itb(Class operator%(Class const &lhs, Class const &rhs))
    itb(Class operator+(Class const &lhs, Class const &rhs))
    itb(Class operator-(Class const &lhs, Class const &rhs))
    itb(Class operator<<(Class const &lhs, Class const &rhs))
    itb(Class operator>>(Class const &lhs, Class const &rhs))
    itb(Class operator&(Class const &lhs, Class const &rhs))
    itb(Class operator|(Class const &lhs, Class const &rhs))
    itb(Class operator^(Class const &lhs, Class const &rhs))
    )
    The latter group of operators also support promotions.

manpagesection(EXAMPLE)
    verbinclude(../../binops/driver/driver.cc)

manpagefiles()
    em(bobcat/binops) - defines the binary operator function templates

manpageseealso()
    bf(bobcat/binopsbase)(3)
    bf(bobcat)(7)

manpagebugs()
    itemization(
    it() The header files tt(utility), defining tt(std::move), and
tt(bobcat/typetrait) are required by, but are not included by
tt(bobcat/binops). This was a design decision, see the bf(NAMESPACE)
section.
    )

includefile(include/trailer)



