Update reference

Author: pdimov

doc/lambda2/reference.adoc

@@ -1,5 +1,5 @@
 ////
-Copyright 2020 Peter Dimov
+Copyright 2020, 2021 Peter Dimov
 Distributed under the Boost Software License, Version 1.0.
 https://www.boost.org/LICENSE_1_0.txt
 ////
@@ -16,33 +16,116 @@ https://www.boost.org/LICENSE_1_0.txt
 namespace boost {
 namespace lambda2 {
 
+// placeholders
+
+template<int I> struct lambda2_arg;
+
+inline constexpr lambda2_arg<1> _1{};
+inline constexpr lambda2_arg<1> _2{};
+inline constexpr lambda2_arg<1> _3{};
+inline constexpr lambda2_arg<1> _4{};
+inline constexpr lambda2_arg<1> _5{};
+inline constexpr lambda2_arg<1> _6{};
+inline constexpr lambda2_arg<1> _7{};
+inline constexpr lambda2_arg<1> _8{};
+inline constexpr lambda2_arg<1> _9{};
+
+// arithmetic operators
+
 template<class A, class B> auto operator+( A && a, B && b );
 template<class A, class B> auto operator-( A && a, B && b );
 template<class A, class B> auto operator*( A && a, B && b );
 template<class A, class B> auto operator/( A && a, B && b );
 template<class A, class B> auto operator%( A && a, B && b );
 template<class A> auto operator-( A && a );
 
+// relational operators
+
 template<class A, class B> auto operator==( A && a, B && b );
 template<class A, class B> auto operator!=( A && a, B && b );
 template<class A, class B> auto operator>( A && a, B && b );
 template<class A, class B> auto operator<( A && a, B && b );
 template<class A, class B> auto operator>=( A && a, B && b );
 template<class A, class B> auto operator<=( A && a, B && b );
 
+// logical operators
+
 template<class A, class B> auto operator&&( A && a, B && b );
 template<class A, class B> auto operator||( A && a, B && b );
 template<class A> auto operator!( A && a );
 
+// bitwise operators
+
 template<class A, class B> auto operator&( A && a, B && b );
 template<class A, class B> auto operator|( A && a, B && b );
 template<class A, class B> auto operator^( A && a, B && b );
 template<class A> auto operator~( A && a );
 
+template<class A, class B> auto operator<<( A && a, B && b );
+template<class A, class B> auto operator>>( A && a, B && b );
+
+// additional unary operators
+
+template<class A> auto operator+( A && a );
+template<class A> auto operator*( A && a );
+template<class A> auto operator++( A && a );
+template<class A> auto operator--( A && a );
+template<class A> auto operator++( A && a, int );
+template<class A> auto operator--( A && a, int );
+
+// compound assignment operators
+
+template<class A, class B> auto operator+=( A && a, B && b );
+template<class A, class B> auto operator-=( A && a, B && b );
+template<class A, class B> auto operator*=( A && a, B && b );
+template<class A, class B> auto operator/=( A && a, B && b );
+template<class A, class B> auto operator%=( A && a, B && b );
+template<class A, class B> auto operator&=( A && a, B && b );
+template<class A, class B> auto operator|=( A && a, B && b );
+template<class A, class B> auto operator^=( A && a, B && b );
+template<class A, class B> auto operator<<=( A && a, B && b );
+template<class A, class B> auto operator>>=( A && a, B && b );
+
 } // namespace lambda2
 } // namespace boost
 ```
 
+### Placeholders
+
+```
+template<int I> struct lambda2_arg
+{
+    template<class... A> decltype(auto) operator()( A&&... a ) const noexcept;
+    template<class T> auto operator[]( T&& t ) const;
+};
+```
+
+`lambda2_arg<I>` is the type of the library-provided placeholders `_I`. The
+standard customization point `std::is_placeholder` is specialized for it,
+enabling the use of Lambda2's placeholders with `std::bind`.
+
+The placeholders define `operator()`, which permits their direct use as
+function objects. E.g. `_1(x, y)` returns `x`.
+
+`operator[]` is also defined to allow expressions like `_1[x]` or `_1[_2]`.
+
+```
+template<class... A> decltype(auto) operator()( A&&... a ) const noexcept;
+```
+[none]
+* {blank}
++
+Returns: :: `std::get<std::size_t{I-1}>( std::tuple<A&&...>( std::forward<A>(a)... ) );`
+
+```
+template<class T> auto operator[]( T&& t ) const;
+```
+[none]
+* {blank}
++
+Returns: :: `std::bind( fn, *this, std::forward<T>(t) );`, where `fn` is
+  a function object such that `fn(x, y)` returns `x[y]`.
+
 ### Common Requirements
 
 All operators defined in the subsequent sections only participate in
@@ -214,3 +297,94 @@ template<class A> auto operator~( A && a );
 +
 Returns: ::
   `std::bind( std::bit_not<>(), std::forward<A>(a) );`
+
+```
+template<class A, class B> auto operator<<( A && a, B && b );
+```
+[none]
+* {blank}
++
+Returns: :: `std::bind( fn, std::forward<A>(a), std::forward<B>(b) );`,
+  where `fn` is a function object such that `fn(x, y)` returns `x << y`.
+
+```
+template<class A, class B> auto operator>>( A && a, B && b );
+```
+[none]
+* {blank}
++
+Returns: :: `std::bind( fn, std::forward<A>(a), std::forward<B>(b) );`,
+  where `fn` is a function object such that `fn(x, y)` returns `x >> y`.
+
+### Additional Unary Operators
+
+```
+template<class A> auto operator+( A && a );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `+x`.
+
+```
+template<class A> auto operator*( A && a );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `*x`.
+
+```
+template<class A> auto operator++( A && a );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `++x`.
+
+```
+template<class A> auto operator--( A && a );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `--x`.
+
+```
+template<class A> auto operator++( A && a, int );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `x++`.
+
+```
+template<class A> auto operator--( A && a, int );
+```
+[none]
+* {blank}
++
+Returns: ::
+  `std::bind( fn, std::forward<A>(a) );`, where `fn` is a function object
+  such that `fn(x)` returns `x--`.
+
+### Compound Assignment Operators
+
+```
+template<class A, class B> auto operator@=( A && a, B && b );
+```
+[none]
+* {blank}
++
+Returns: :: `std::bind( fn, std::forward<A>(a), std::forward<B>(b) );`,
+  where `fn` is a function object such that `fn(x, y)` returns `x @= y`.