Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/taocpp/operators
A highly efficient, move-aware operators library
https://github.com/taocpp/operators
cpp cpp11 header-only
Last synced: 25 days ago
JSON representation
A highly efficient, move-aware operators library
- Host: GitHub
- URL: https://github.com/taocpp/operators
- Owner: taocpp
- License: mit
- Created: 2013-03-24T14:42:59.000Z (over 11 years ago)
- Default Branch: main
- Last Pushed: 2022-12-09T14:01:04.000Z (almost 2 years ago)
- Last Synced: 2024-08-01T00:41:16.662Z (4 months ago)
- Topics: cpp, cpp11, header-only
- Language: C++
- Homepage:
- Size: 173 KB
- Stars: 196
- Watchers: 20
- Forks: 16
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesomecpp - taocpp/operators - - zero-dependency C++11 single-header library that provides highly efficient, move aware operators for arithmetic data types. (Containers and Algorithms)
README
# The Art of C++ / Operators
[](https://github.com/taocpp/operators/releases/latest)
[](https://bintray.com/conan/conan-center/taocpp-operators%3A_/_latestVersion)
[](https://travis-ci.org/taocpp/operators)
[](https://ci.appveyor.com/project/taocpp/operators)
[](https://coveralls.io/github/taocpp/operators)
[](https://lgtm.com/projects/g/taocpp/operators/context:cpp)
[The Art of C++](https://taocpp.github.io/) / 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](#overview)
[Example](#example)
[Requirements](#requirements)
[Installation](#installation)
[Provided Templates](#provided-templates)
[Commutativity](#commutativity)
[RValue References](#rvalue-references)
[constexpr](#constexpr)
[noexcept](#noexcept)
[nodiscard](#nodiscard)
[Changelog](#changelog)
[History](#history)
[License](#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...
```c++
#include
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.
```c++
// 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](#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](https://github.com/conan-io/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](https://github.com/conan-io/conan-center-index) 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`.
TemplateProvidesRequires
equality_comparable< T >
T != T
T == T
equality_comparable< T, U >
T != U
U == T
U != T
T == U
less_than_comparable< T >
T > T
T <= T
T >= T
T < T
less_than_comparable< T, U >
T <= U
T >= U
U < T
U > T
U <= T
U >= T
T < U
T > U
equivalent< T >
T == T
T < T
equivalent< T, U >
T == U
T < U
T > U
partially_ordered< T >
T > T
T <= T
T >= T
T < T
T == T
partially_ordered< T, U >
T <= U
T >= U
U < T
U > T
U <= T
U >= T
T < U
T > U
T == U
commutative_addable< T >
T + T
T += T
commutative_addable< T, U >
T + U
U + T
T += U
addable< T >
T + T
T += T
addable< T, U >
T + U
T += U
addable_left< T, U >
U + T
T( U )
T += T
subtractable< T >
T - T
T -= T
subtractable< T, U >
T - U
T -= U
subtractable_left< T, U >
U - T
T( U )
T -= T
commutative_multipliable< T >
T * T
T *= T
commutative_multipliable< T, U >
T * U
U * T
T *= U
multipliable< T >
T * T
T *= T
multipliable< T, U >
T * U
T *= U
multipliable_left< T, U >
U * T
T( U )
T *= T
dividable< T >
T / T
T /= T
dividable< T, U >
T / U
T /= U
dividable_left< T, U >
U / T
T( U )
T /= T
modable< T >
T % T
T %= T
modable< T, U >
T % U
T %= U
modable_left< T, U >
U % T
T( U )
T %= T
commutative_andable< T >
T & T
T &= T
commutative_andable< T, U >
T & U
U & T
T &= U
andable< T >
T & T
T &= T
andable< T, U >
T & U
T &= U
andable_left< T, U >
U & T
T( U )
T &= T
commutative_orable< T >
T | T
T |= T
commutative_orable< T, U >
T | U
U | T
T |= U
orable< T >
T | T
T |= T
orable< T, U >
T | U
T |= U
orable_left< T, U >
U | T
T( U )
T |= T
commutative_xorable< T >
T ^ T
T ^= T
commutative_xorable< T, U >
T ^ U
U ^ T
T ^= U
xorable< T >
T ^ T
T ^= T
xorable< T, U >
T ^ U
T ^= U
xorable_left< T, U >
U ^ T
T( U )
T ^= T
left_shiftable< T >
T << T
T <<= T
left_shiftable< T, U >
T << U
T <<= U
right_shiftable< T >
T >> T
T >>= T
right_shiftable< T, U >
T >> U
T >>= U
incrementable< T >
T++
++T
decrementable< T >
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.
TemplateProvides
totally_ordered< T >
equality_comparable< T >
less_than_comparable< T >
totally_ordered< T, U >
equality_comparable< T, U >
less_than_comparable< T, U >
commutative_ring< T >
commutative_addable< T >
subtractable< T >
commutative_multipliable< T >
commutative_ring< T, U >
commutative_addable< T, U >
subtractable< T, U >
subtractable_left< T, U >
commutative_multipliable< T, U >
ring< T >
commutative_addable< T >
subtractable< T >
multipliable< T >
ring< T, U >
commutative_addable< T, U >
subtractable< T, U >
subtractable_left< T, U >
multipliable< T, U >
field< T >
commutative_ring< T >
dividable< T >
field< T, U >
commutative_ring< T, U >
dividable< T, U >
dividable_left< T, U >
ordered_commutative_ring< T >
commutative_ring< T >
totally_ordered< T >
ordered_commutative_ring< T, U >
commutative_ring< T, U >
totally_ordered< T, U >
ordered_ring< T >
ring< T >
totally_ordered< T >
ordered_ring< T, U >
ring< T, U >
totally_ordered< T, U >
ordered_field< T >
field< T >
totally_ordered< T >
ordered_field< T, U >
field< T, U >
totally_ordered< T, U >
commutative_bitwise< T >
commutative_andable< T >
commutative_orable< T >
commutative_xorable< T >
commutative_bitwise< T, U >
commutative_andable< T, U >
commutative_orable< T, U >
commutative_xorable< T, U >
bitwise< T >
andable< T >
orable< T >
xorable< T >
bitwise< T, U >
andable< T, U >
orable< T, U >
xorable< T, U >
bitwise_left< T, U >
andable_left< T, U >
orable_left< T, U >
xorable_left< T, U >
shiftable< T >
left_shiftable< T >
right_shiftable< T >
shiftable< T, U >
left_shiftable< T, U >
right_shiftable< T, U >
unit_steppable< T >
incrementable< T >
decrementable< T >
## Commutativity
For some templates, there are both [commutative](https://en.wikipedia.org/wiki/Commutative_property)
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:
```c++
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
```c++
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:
```c++
// 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
```c++
#define TAO_OPERATORS_CONSTEXPR
```
before including ``.
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
```c++
#define TAO_OPERATORS_CONSTEXPR constexpr
```
before including ``.
## noexcept
For compilers that do not support `noexcept`, the following might be a viable
work-around:
```c++
#include // make sure it's included before the following!
#define noexcept(...)
// you probably also need this for older compilers:
#define TAO_OPERATORS_CONSTEXPR
#include
#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`:
```c++
#define TAO_OPERATORS_NODISCARD
#include
```
## 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](http://www.boost.org/doc/libs/1_66_0/libs/utility/operators.htm) library.
## License
The Art of C++ is certified [Open Source](http://www.opensource.org/docs/definition.html) 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](http://www.opensource.org/licenses/mit-license.html) 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.