The Art of C++ / Operators

The Art of C++ / Operators is a zero-dependency C++11 single-header library that provides highly efficient, move aware operators for arithmetic data types.

Table of Content

Overview
Example
Requirements
Installation
Provided Templates
Commutativity
RValue References
constexpr
noexcept
nodiscard
Changelog
History
License

Overview

Overloaded operators for class types typically don't come alone. For example, when x + y is possible then x += y should be, too. When x < y is possible then x > y, x >= y, and x <= y should be, too.

Implementing large sets of operators, possibly for multiple classes, is both tedious and error-prone. However, more often than not, some of these operators can be defined in terms of others. For example x >= y can frequently be defined as !(x < y).

Given the implementation of some basic operators, the templates in the Art of C++ / Operators can generate many more operators automatically.

The generated operators are overloaded to take advantage of movable types, and allow the compiler to avoid unneccessary temporary objects wherever possible. All generated operators are noexcept when the underlying operations are noexcept. Generated comparison operators are constexpr (when supported by the compiler).

Example

Given this dummy integer class...

#include <tao/operators.hpp>

class MyInt
  : tao::operators::commutative_addable< MyInt >,
    tao::operators::multipliable< MyInt, double >
{
public:
  // create a new instance of MyInt
  MyInt( const int v ) noexcept;

  // copy and move constructor
  MyInt( const MyInt& v ) noexcept;
  MyInt( MyInt&& v ) noexcept; // optional

  // copy and move assignment
  MyInt& operator=( const MyInt& v ) noexcept;
  MyInt& operator=( MyInt&& v ) noexcept; // optional

  // addition of another MyInt
  MyInt& operator+=( const MyInt& v ) noexcept;
  MyInt& operator+=( MyInt&& v ) noexcept; // optional

  // multiplication by a scalar
  MyInt& operator*=( const double v ) noexcept;
};

...the base class templates will generate the following operators.

// generated by tao::operators::commutative_addable< MyInt >
MyInt   operator+( const MyInt& lhs, const MyInt& rhs ) noexcept;
MyInt&& operator+( const MyInt& lhs, MyInt&&      rhs ) noexcept;
MyInt&& operator+( MyInt&&      lhs, const MyInt& rhs ) noexcept;
MyInt&& operator+( MyInt&&      lhs, MyInt&&      rhs ) noexcept;

// generated by tao::operators::multipliable< MyInt, double >
MyInt   operator*( const MyInt& lhs, const double& rhs ) noexcept;
MyInt   operator*( const MyInt& lhs, double&&      rhs ) noexcept;
MyInt&& operator*( MyInt&&      lhs, const double& rhs ) noexcept;
MyInt&& operator*( MyInt&&      lhs, double&&      rhs ) noexcept;

Note: The // optional in class MyInt above marks methods that you typically only add when your class benefits from an rvalue reference parameter. If there is no benefit for the implementation, you can just omit these methods. If you leave them out, The Art of C++ / Operators will simply call the corresponding non-movable version that takes the parameter by const lvalue reference.

Requirements

Requires C++11 or newer. Tested with:

• GCC 4.7+
• Clang 3.2+
• Visual Studio 2015+

Remember to enable C++11, e.g., provide -std=c++11 or similar options.

Note: If you use or test the library with other compilers/versions, e.g., Visual C++, Intel C++, or any other compiler we'd like to hear from you.

Note: For compilers that don't support noexcept, see chapter noexcept.

Installation

The Art of C++ / Operators is a single-header library. There is nothing to build or install, just copy the header somewhere and include it in your code.

Package Managers

You can download and install taocpp-operators using the Conan package manager:

conan install taocpp-operators/1.2.2@

The taocpp-operators package in conan is kept up to date by Conan team members and community contributors. If the version is out-of-date, please create an issue or pull request on the Conan Center Index repository.

Provided Templates

The following table gives an overview of the available templates. Note that the "Provides" and "Requires" columns are just a basic overview. Multiple overloads per provided operator might exist to ensure the most efficient implementation for each case, exploiting move-semantics when possible and (unless explicitly disabled) pass-through of temporary values to avoid creating new temporaries.

Each overload of an operator is marked noexcept when the required operation(s) that are used to implement it are also marked noexcept.

Template	Provides	Requires
equality_comparable	T != T	T == T
equality_comparable	T != U U == T U != T	T == U
less_than_comparable	T > T T  T >= T	T
less_than_comparable	T  T >= U U  U > T U  U >= T	T  T > U
equivalent	T == T	T
equivalent	T == U	T  T > U
partially_ordered	T > T T  T >= T	T  T == T
partially_ordered	T  T >= U U  U > T U  U >= T	T  T > U T == U
commutative_addable	T + T	T += T
commutative_addable	T + U U + T	T += U
addable	T + T	T += T
addable	T + U	T += U
addable_left	U + T	T( U ) T += T
subtractable	T - T	T -= T
subtractable	T - U	T -= U
subtractable_left	U - T	T( U ) T -= T
commutative_multipliable	T * T	T *= T
commutative_multipliable	T * U U * T	T *= U
multipliable	T * T	T *= T
multipliable	T * U	T *= U
multipliable_left	U * T	T( U ) T *= T
dividable	T / T	T /= T
dividable	T / U	T /= U
dividable_left	U / T	T( U ) T /= T
modable	T % T	T %= T
modable	T % U	T %= U
modable_left	U % T	T( U ) T %= T
commutative_andable	T & T	T &= T
commutative_andable	T & U U & T	T &= U
andable	T & T	T &= T
andable	T & U	T &= U
andable_left	U & T	T( U ) T &= T
commutative_orable	T | T	T |= T
commutative_orable	T | U U | T	T |= U
orable	T | T	T |= T
orable	T | U	T |= U
orable_left	U | T	T( U ) T |= T
commutative_xorable	T ^ T	T ^= T
commutative_xorable	T ^ U U ^ T	T ^= U
xorable	T ^ T	T ^= T
xorable	T ^ U	T ^= U
xorable_left	U ^ T	T( U ) T ^= T
left_shiftable	T	T
left_shiftable	T	T
right_shiftable	T >> T	T >>= T
right_shiftable	T >> U	T >>= U
incrementable	T++	++T
decrementable	T--	--T

The following templates provide common groups of related operations. For example, since a type which is left shiftable is usually also right shiftable, the shiftable template provides the combined operators of both.

Template	Provides
totally_ordered	equality_comparable less_than_comparable
totally_ordered	equality_comparable less_than_comparable
commutative_ring	commutative_addable subtractable commutative_multipliable
commutative_ring	commutative_addable subtractable subtractable_left commutative_multipliable
ring	commutative_addable subtractable multipliable
ring	commutative_addable subtractable subtractable_left multipliable
field	commutative_ring dividable
field	commutative_ring dividable dividable_left
ordered_commutative_ring	commutative_ring totally_ordered
ordered_commutative_ring	commutative_ring totally_ordered
ordered_ring	ring totally_ordered
ordered_ring	ring totally_ordered
ordered_field	field totally_ordered
ordered_field	field totally_ordered
commutative_bitwise	commutative_andable commutative_orable commutative_xorable
commutative_bitwise	commutative_andable commutative_orable commutative_xorable
bitwise	andable orable xorable
bitwise	andable orable xorable
bitwise_left	andable_left orable_left xorable_left
shiftable	left_shiftable right_shiftable
shiftable	left_shiftable right_shiftable
unit_steppable	incrementable decrementable

Commutativity

For some templates, there are both commutative and non-commutative versions available. If the class you are writing is commutative wrt an operation, you should prefer the commutative template, i.e., the one which has commutative_ at the beginning.

It will be more efficient in some cases because it can avoid an extra temporary for the result and it has fewer requirements.

The one-argument version of the commutative template provides the same operators as the non-commutative one, but you can see from the result type in which cases creating a temporary (returning T) can be avoided (returning T&&).

For the two-argument version, commutative_{OP}< T, U > provides the operators of both {OP}< T, U > and {OP}_left< T, U >, again the return type indicates those cases where an extra temporary is avoided.

RValue References

As you can see above, several overloads of some operators return rvalue references. This helps to eliminate temporaries in more complicated expressions, but some people consider it dangerous. The argument against returning rvalue references usually is something like:

const auto& result = a + b + c;

where they expect a temporary to be returned from the expression a + b + c, and the lifetime of the temporary can be extended by binding it to a reference.

While this would work if an actual temporary value is returned, it does not work with the second operator + returning an rvalue reference to the intermediate temporary created by the first operator +.

I consider the above code bad style that has no place in modern C++. It should be replaced by

const auto result = a + b + c;

and the problem goes away. Also, if you expect an expression to return a temporary value, but you don't verify your assumption, it is your fault for basing your code on those assumptions.

There is, however, one problem where the above binding to a references happens behind the scenes, i.e. without being immediately visible. It may happen if you are using a range-based for-loop. The problem in this case is not limited to returning rvalue references, hence you should always make sure that you do not mix any kind of expression other than directly naming a variable when using a range-based for-loop. Example:

// instead of this:
for( const auto& e : a + b + c ) { ... }

// always use something like this:
const auto r = a + b + c;
for( const auto& e : r ) { ... }

With all that said, you can disable returning rvalue references by defining TAO_OPERATORS_NO_RVALUE_REFERENCE_RESULTS. If it is set, all operators will return a value (an rvalue) instead of rvalue references.

constexpr

All generated comparison operators are constexpr by default. To switch off constexpr support simply

#define TAO_OPERATORS_CONSTEXPR

before including <tao/operators.hpp>.

Note that Visual C++ seems to have some problems with constexpr depending on compile mode (debug/release), etc. and constexpr support is therefore disabled by default. To manually enable it again use

#define TAO_OPERATORS_CONSTEXPR constexpr

before including <tao/operators.hpp>.

noexcept

For compilers that do not support noexcept, the following might be a viable work-around:

#include <utility> // make sure it's included before the following!
#define noexcept(...)
// you probably also need this for older compilers:
#define TAO_OPERATORS_CONSTEXPR
#include <tao/operators.hpp>
#undef noexcept

nodiscard

When compiling with C++17 or higher, all generated methods are marked [[nodiscard]]. For compilers that do not support [[nodiscard]] or when it is causing trouble, you can disable it defining TAO_OPERATORS_NODISCARD:

#define TAO_OPERATORS_NODISCARD
#include <tao/operators.hpp>

Changelog

1.2.2

Released 2019-06-04

• Fix CMakeLists.txt version number.

1.2.1

Released 2019-06-04

• Add work-around for MSVC to fix broken EBO in more cases.

1.2.0

Released 2019-03-30

• Add support for [[nodiscard]].

1.1.1

Released 2018-06-17

• Automatic upload of Conan packages on release.

1.1.0

Released 2018-06-17

• Add constexpr support for comparison operators.

1.0.2

Released 2018-06-05

• Improve CMake support.
• Conan support.

1.0.1

Released 2018-04-23

• Work-around for MSVC to fix broken EBO.

1.0.0

Released 2018-02-13

• Initial release.

History

The Art of C++ / Operators is a modernised C++11 rewrite of the Boost.Operators library.

License

The Art of C++ is certified Open Source software. It may be used for any purpose, including commercial purposes, at absolutely no cost. It is distributed under the terms of the MIT license reproduced here.

Copyright (c) 2013-2020 Daniel Frey

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.