boost/hana/fwd/pair.hpp

   1 /*!
   2 @file
   3 Forward declares `boost::hana::pair`.
   4
   5 @copyright Louis Dionne 2013-2017
   6 Distributed under the Boost Software License, Version 1.0.
   7 (See accompanying file LICENSE.md or copy at http://boost.org/LICENSE_1_0.txt)
   8  */
   9
  10 #ifndef BOOST_HANA_FWD_PAIR_HPP
  11 #define BOOST_HANA_FWD_PAIR_HPP
  12
  13 #include <boost/hana/config.hpp>
  14 #include <boost/hana/fwd/core/make.hpp>
  15
  16
  17 BOOST_HANA_NAMESPACE_BEGIN
  18     //! @ingroup group-datatypes
  19     //! Generic container for two elements.
  20     //!
  21     //! `hana::pair` is conceptually the same as `std::pair`. However,
  22     //! `hana::pair` automatically compresses the storage of empty types,
  23     //! and as a result it does not have the `.first` and `.second` members.
  24     //! Instead, one must use the `hana::first` and `hana::second` free
  25     //! functions to access the elements of a pair.
  26     //!
  27     //!
  28     //! Modeled concepts
  29     //! ----------------
  30     //! 1. `Comparable`\n
  31     //! Two pairs `(x, y)` and `(x', y')` are equal if and only if both
  32     //! `x == x'` and `y == y'`.
  33     //! @include example/pair/comparable.cpp
  34     //!
  35     //! 2. `Orderable`\n
  36     //! Pairs are ordered as-if they were 2-element tuples, using a
  37     //! lexicographical ordering.
  38     //! @include example/pair/orderable.cpp
  39     //!
  40     //! 3. `Foldable`\n
  41     //! Folding a pair is equivalent to folding a 2-element tuple. In other
  42     //! words:
  43     //! @code
  44     //!     fold_left(make_pair(x, y), s, f) == f(f(s, x), y)
  45     //!     fold_right(make_pair(x, y), s, f) == f(x, f(y, s))
  46     //! @endcode
  47     //! Example:
  48     //! @include example/pair/foldable.cpp
  49     //!
  50     //! 4. `Product`\n
  51     //! The model of `Product` is the simplest one possible; the first element
  52     //! of a pair `(x, y)` is `x`, and its second element is `y`.
  53     //! @include example/pair/product.cpp
  54 #ifdef BOOST_HANA_DOXYGEN_INVOKED
  55     template <typename First, typename Second>
  56     struct pair {
  57         //! Default constructs the `pair`. Only exists when both elements
  58         //! of the pair are default constructible.
  59         constexpr pair();
  60
  61         //! Initialize each element of the pair with the corresponding element.
  62         //! Only exists when both elements of the pair are copy-constructible.
  63         constexpr pair(First const& first, Second const& second);
  64
  65         //! Initialize both elements of the pair by perfect-forwarding the
  66         //! corresponding argument. Only exists when both arguments are
  67         //! implicitly-convertible to the corresponding element of the pair.
  68         template <typename T, typename U>
  69         constexpr pair(T&& t, U&& u);
  70
  71         //! Copy-initialize a pair from another pair. Only exists when both
  72         //! elements of the source pair are implicitly convertible to the
  73         //! corresponding element of the constructed pair.
  74         template <typename T, typename U>
  75         constexpr pair(pair<T, U> const& other);
  76
  77         //! Move-initialize a pair from another pair. Only exists when both
  78         //! elements of the source pair are implicitly convertible to the
  79         //! corresponding element of the constructed pair.
  80         template <typename T, typename U>
  81         constexpr pair(pair<T, U>&& other);
  82
  83         //! Assign a pair to another pair. Only exists when both elements
  84         //! of the destination pair are assignable from the corresponding
  85         //! element in the source pair.
  86         template <typename T, typename U>
  87         constexpr pair& operator=(pair<T, U> const& other);
  88
  89         //! Move-assign a pair to another pair. Only exists when both elements
  90         //! of the destination pair are move-assignable from the corresponding
  91         //! element in the source pair.
  92         template <typename T, typename U>
  93         constexpr pair& operator=(pair<T, U>&& other);
  94
  95         //! Equivalent to `hana::equal`
  96         template <typename X, typename Y>
  97         friend constexpr auto operator==(X&& x, Y&& y);
  98
  99         //! Equivalent to `hana::not_equal`
 100         template <typename X, typename Y>
 101         friend constexpr auto operator!=(X&& x, Y&& y);
 102
 103         //! Equivalent to `hana::less`
 104         template <typename X, typename Y>
 105         friend constexpr auto operator<(X&& x, Y&& y);
 106
 107         //! Equivalent to `hana::greater`
 108         template <typename X, typename Y>
 109         friend constexpr auto operator>(X&& x, Y&& y);
 110
 111         //! Equivalent to `hana::less_equal`
 112         template <typename X, typename Y>
 113         friend constexpr auto operator<=(X&& x, Y&& y);
 114
 115         //! Equivalent to `hana::greater_equal`
 116         template <typename X, typename Y>
 117         friend constexpr auto operator>=(X&& x, Y&& y);
 118     };
 119 #else
 120     template <typename First, typename Second>
 121     struct pair;
 122 #endif
 123
 124     //! Tag representing `hana::pair`.
 125     //! @relates hana::pair
 126     struct pair_tag { };
 127
 128 #ifdef BOOST_HANA_DOXYGEN_INVOKED
 129     //! Creates a `hana::pair` with the given elements.
 130     //! @relates hana::pair
 131     //!
 132     //!
 133     //! Example
 134     //! -------
 135     //! @include example/pair/make.cpp
 136     template <>
 137     constexpr auto make<pair_tag> = [](auto&& first, auto&& second)
 138         -> hana::pair<std::decay_t<decltype(first)>, std::decay_t<decltype(second)>>
 139     {
 140         return {forwarded(first), forwarded(second)};
 141     };
 142 #endif
 143
 144     //! Alias to `make<pair_tag>`; provided for convenience.
 145     //! @relates hana::pair
 146     //!
 147     //! Example
 148     //! -------
 149     //! @include example/pair/make.cpp
 150     constexpr auto make_pair = make<pair_tag>;
 151 BOOST_HANA_NAMESPACE_END
 152
 153 #endif // !BOOST_HANA_FWD_PAIR_HPP