`<utility>`

operator!== · operator== · operator< · operator<= · operator> · operator>= · pair

get · make_pair · tuple_element · tuple_size

declval · forward · move · move_if_noexcept · piecewise_construct · piecewise_construct_t · swap

Include the STL standard header <utility> to define several templates of general use throughout the Standard Template Library.

Four template operators -- operator!=, operator<=, operator>, and operator>= -- define a total ordering on pairs of operands of the same type, given definitions of operator== and operator<.

Rhese template operators are defined in the rel_ops namespace, nested within the std namespace. If you wish to make use of these template operators, write the declaration:

using namespace std::rel_ops;

which promotes the template operators into the current namespace.

namespace std {
        // TEMPLATE CLASSES
template<class T, class Ty2>
    struct pair;

struct piecewise_construct_t; [added with C++11]
constexpr piecewise_construct_t piecewise_construct =
    piecewise_construct_t(); [added with C++11]

        // TEMPLATE FUNCTIONS
template<class Ty1, class Ty2>
    pair<Ty, Ty2> make_pair(Ty1 val1, Ty2 val2); [removed with C++11]
template<class Ty1, class Ty2>
    pair<Ty, Ty2> make_pair(Ty1&& val1, Ty2&& val2); [added with C++11]

template<class Ty1, class Ty2>
    bool operator==(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    bool operator!=(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    bool operator<(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    bool operator>(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    bool operator<=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    bool operator>=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

template<class Ty> [added with C++11]
    void swap(Ty& left, Ty& right)
        noexcept(is_nothrow_move_constructible<Ty>::value
            && is nothrow_move_assignable<Ty>::value);
template<class Ty, size_t N> [added with C++11]
    void swap(Ty (&left)[N], Ty (&right)[N])
        noexcept(noexcept(swap(*left, *right)));
template<class Ty1, class Ty2> [added with C++11]
    void swap(pair<Ty1, Ty2>& left,
        pair<Ty1, Ty2>& right);
            noexcept(noexcept(Left.swap(_Right)))

template<class Ty>
    typename add_rvalue_reference<Ty>::type
        declval(); [added with C++11]
template<class Ty>
    Ty&& forward(
        typename remove_reference<Ty>::type& right); [added with C++11]
template<class Ty>
    Ty&& forward(
        typename remove_reference<Ty>::type&& right) noexcept; [added with C++11]
template<class Ty>
    typename remove_reference<Ty>::type&&
        move(Ty&& right) noexcept; [added with C++11]
template<class Ty>
	typename conditional<!has_nothrow_move_constructor<Ty>::value
		&& has_copy_constructor<Ty>::value,
			const Ty&, Ty&&>::type
	move_if_noexcept(Ty& right) noexcept; [added with C++11]

template<int Idx, class T1, class T2>  [added with C++11]
    RI& get(pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2>  [added with C++11]
    const RI& get(const pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2>  [added with C++11]
    RI& get(pair<T1, T2>&& pr) noexcept;

template<class T1, class T2>  [added with C++11]
    class tuple_element<0, pair<T1, T2> >;
template<class T1, class T2>  [added with C++11]
    class tuple_element<1, pair<T1, T2> >;

template<class T1, class T2>  [added with C++11]
    class tuple_size<pair<T1, T2> >;
    namespace tr1 {
using std::get; using std::tuple_element; [added with C++11]
using std::tuple_size;
    } // namespace tr1

    namespace rel_ops {
    template<class Ty>
        bool operator!=(const Ty& left, const Ty& right);
    template<class Ty>
        bool operator<=(const Ty& left, const Ty& right);
    template<class Ty>
        bool operator>(const Ty& left, const Ty& right);
    template<class Ty>
        bool operator>=(const Ty& left, const Ty& right);
    }  // namespace rel_ops
}  // namespace std

`declval`

template<class Ty>
    typename add_rvalue_reference<Ty>::type
        declval(); [added with C++11]

The template function has no definition. You use it to specify unevaluated operands of type Ty, as in:

template<class To, class From>
    decltype(static_cast<To>(declval<From>()))
        convert(From&&);

which participates in overload resolution only if an expression of type From can be explicitly converted to a value of type To.

`forward`

template<class Ty>
    Ty&& forward(
        typename remove_reference<Ty>::type& right); [added with C++11]
template<class Ty>
    Ty&& forward(
        typename remove_reference<Ty>::type&& right) noexcept; [added with C++11]

The template function returns right as an rvalue reference. If the second form is instantiated with an lvalue reference type, the program is ill-formed.

`get`

template<int Idx, class T1, class T2>  [added with C++11]
    RI& get(pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2>  [added with C++11]
    const RI& get(const pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2>  [added with C++11]
    RI& get(pair<T1, T2>&& pr) noexcept;

The template functions each return a reference, called RI here, to an element of its pair argument. If the value of Idx is 0 the functions return pr.first and if the value of Idx is 1 the functions return pr.second. If the corresponding type Ti is a reference type, all functions return Ti; otherwise the first function returns Ti& the second function returns const Ti&, and the third function returns Ti&&.

`make_pair`

template<class Ty1, class Ty2>
    pair<Ty1x, Ty2x> make_pair(Ty1 val1, Ty2 val2); [removed with C++11]
template<class Ty1, class Ty2>
    pair<Ty1x, Ty2x> make_pair(Ty1&& val1, Ty2&& val2); [added with C++11]

The template function returns pair<Ty1x, Ty2x>(val1, val2), where Ty1x is determined from Ty1 as follows:

If Ty1 is reference_wrapper<X>, Ty1x is X&.
Otherwise, beginning with C++11, Ty1x is decay<Ty1>::type.
Otherwise, Ty1x is Ty1.

Ty2x is similarly determined from Ty2.

`move`

template<class T>
    typename remove_reference<T>::type&&
        move(T&& right) noexcept; [added with C++11]

The template function returns right as an rvalue reference, whether or not T is a reference type.

`move_if_noexcept`

template<class Ty>
	typename conditional<!is_nothrow_move_constructible<Ty>::value
		&& is_copy_constructible<Ty>::value,
			const Ty&, Ty&&>::type
	move_if_noexcept(Ty& right) noexcept;

The template function returns move(right).

`operator!=`

template<class Ty>
    bool operator!=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
    bool operator!=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns !(left == right).

`operator==`

template<class Ty1, class Ty2>
    bool operator==(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns left.first == right.first && left.second == right.second.

`operator<`

template<class Ty1, class Ty2>
    bool operator<(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns left.first < right.first || !(right.first < left.first) && left.second < right.second.

`operator<=`

template<class Ty>
    bool operator<=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
    bool operator<=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns !(right < left).

`operator>`

template<class Ty>
    bool operator>(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
    bool operator>(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns right < left.

`operator>=`

template<class Ty>
    bool operator>=(const Ty& left, const Ty& right);
template<class Ty1, class Ty2>
    bool operator>=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template function returns !(left < right).

`pair`

template<class Ty1, class Ty2>
    struct pair {
    Ty1 first;
    Ty2 second;

    typedef Ty1 first_type;
    typedef Ty2 second_type

    pair(const pair&) = default;
    pair(pair&&) = default;
    constexpr pair();
    pair(const Ty1& val1, const Ty2& val2);
    template<class Other1, class Other2> [added with C++11]
        pair(Other1&& val1, Other2&& val2)
            noexcept(is_nothrow_constructible<Ty1, Other1&&>::value
                && is_nothrow_constructible<Ty2, Other2&&>::value);
    template<class Other1, class Other2> [added with C++11]
        pair(const pair<Other1, Other2>& right);
    template<class Other1, class Other2> [added with C++11]
        pair(pair<Other1, Other2>&& right)
            noexcept(is_nothrow_constructible<Ty1, Other1&&>::value
                && is_nothrow_constructible<Ty2, Other2&&>::value);
    template<class... Types1, class... Types2> [added with C++11]
        pair(piecewise_construct_t,
            tuple<Types1...> val1, tuple<Types2...> val2)
            noexcept(is_nothrow_constructible<Ty1, Types1...&&>::value
                && is_nothrow_constructible<Ty2, Types2...&&>::value);

    pair& operator=(const pair& right);
    pair& operator=(pair&& right)
        noexcept(is_nothrow_move_assignable<Ty1>::value
            && is_nothrow_move_assignable<Ty2>::value); [added with C++11]
    template<class Other1, class Other2> [added with C++11]
        pair& operator=(const pair<Other1, Other2>& right);
    template<class Other1, class Other2> [added with C++11]
        pair& operator=(pair<Other1, Other2>&& right)
            noexcept(is_nothrow_assignable<Ty1, Other1&&>::value
                && is_nothrow_assignable<Ty2, Other2&&>::value);

    void swap(pair& right)
        noexcept(noexcept(swap(first, right.first))
            && noexcept(swap(second, right.second)));

The template class stores a pair of objects, first, of type Ty1, and second, of type Ty2.

`pair::first_type`

typedef Ty1 first_type;

The type definition is the same as the template parameter Ty1

`pair::operator=`

pair& operator=(const pair& right);
pair& operator=(pair&& right)
    noexcept(is_nothrow_move_assignable<Ty1>::value
        && is_nothrow_move_assignable<Ty2>::value); [added with C++11]
template<class Other1, class Other2> [added with C++11]
    pair& operator=(const pair<Other1, Other2>& right);
template<class Other1, class Other2> [added with C++11]
    pair& operator=(pair<Other1, Other2>&& right)
        noexcept(is_nothrow_assignable<Ty1, Other1&&>::value
            && is_nothrow_assignable<Ty2, Other2&&>::value);

All assignment operators store right.first in first and right.second in second, then return *this.

`pair::pair`

pair(const pair&) = default;
pair(pair&&) = default;
constexpr pair();
pair(const Ty1& val1, const Ty2& val2);
template<class Other1, class Other2> [added with C++11]
    pair(Other1&& val1, Other2&& val2)
        noexcept(is_nothrow_constructible<Ty1, Other1&&>::value
            && is_nothrow_constructible<Ty2, Other2&&>::value);
template<class Other1, class Other2> [added with C++11]
    pair(const pair<Other1, Other2>& right);
template<class Other1, class Other2> [added with C++11]
    pair(pair<Other1, Other2>&& right)
        noexcept(is_nothrow_constructible<Ty1, Other1&&>::value
            && is_nothrow_constructible<Ty2, Other2&&>::value);
template<class... Types1, class... Types2> [added with C++11]
    pair(piecewise_construct_t,
        tuple<Types1...> val1, tuple<Types2...> val2)
        noexcept(is_nothrow_constructible<Ty1, Types1...&&>::value
            && is_nothrow_constructible<Ty2, Types2...&&>::value);

The first (copy) constructor initializes first to right.first and second to right.second. The second (move) constructor initializes first by moving right.first and second by moving right.second. The third (default) constructor initializes first to Ty1() and second to Ty2().

The fourth and fifth constructors initialize first to val1 and second to val2. The fifth constructor participates in overload resolution only if is_convertible<Other1, Ty1> holds true is_convertible<Other2, Ty2> holds true.

The sixth and seventh constructors initialize first to right.first and second to right.second.

The last constructor initializes first to Ty1(val1...) and second to Ty2(val2...).

`pair::second_type`

typedef Ty2 second_type;

The type definition is the same as the template parameter Ty1

`pair::swap`

void swap(pair& right)
    noexcept(noexcept(swap(first, right.first))
        && noexcept(swap(second, right.second)));

The member function swaps first with right.first and second with right.second.

`piecewise_construct`

constexpr piecewise_construct_t piecewise_construct =
    piecewise_construct_t(); [added with C++11]

The object is used as a function argument to match the parameter type piecewise_construct_t.

`piecewise_construct_t`

struct piecewise_construct_t {}; [added with C++11]

The struct is used as a function parameter to indicate that two tuple arguments follow in a constructor for template class pair.

`swap`

template<class Ty> [added with C++11]
    void swap(Ty& left, Ty& right)
        noexcept(is_nothrow_move_constructible<Ty>::value
            && is nothrow_move_assignable<Ty>::value);
template<class Ty, size_t N> [added with C++11]
    void swap(Ty (&left)[N], Ty (&right)[N])
        noexcept(noexcept(swap(*left, *right)));
template<class Ty1, class Ty2> [added with C++11]
    void swap(pair<Ty1, Ty2>& left,
        pair<Ty1, Ty2>& right);
            noexcept(noexcept(Left.swap(_Right)))

The template function leaves the value originally stored in right subsequently stored in left, and the value originally stored in left subsequently stored in right. Note that the first two template functions are also declared in <algorithm>.

`tuple_element`

template<class T1, class T2>  [added with C++11]
    class tuple_element<0, pair<T1, T2> > {
    typedef T1 type;
    };
template<class T1, class T2>  [added with C++11]
    class tuple_element<1, pair<T1, T2> > {
    typedef T2 type;
    };

The templates are specializations of the template class tuple_element. Each has a nested typedef type that is a synonym for the type of the corresponding pair element.

`tuple_size`

template<class T1, class T2>  [added with C++11]
    class tuple_size<pair<T1, T2> > {
    static const unsigned value = 2;
    };

The template is a specialization of the template class tuple_size. It has a member value that is an integral constant expression whose value is 2.

See also the Table of Contents and the Index.