<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

exchange · index_sequence · index_sequence_for · integer_sequence · make_index_sequence · make_integer_sequence

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<.

These 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>
    constexpr pair<Ty1x, Ty2x> make_pair(Ty1 val1, Ty2 val2); [removed with C++11]
template<class Ty1, class Ty2>
    constexpr pair<Ty1x, Ty2x> make_pair(Ty1&& val1, Ty2&& val2); [added with C++11]

template<class Ty1, class Ty2>
    constexpr bool operator==(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    constexpr bool operator!=(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    constexpr bool operator<(const pair<Ty, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    constexpr bool operator>(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    constexpr bool operator<=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);
template<class Ty1, class Ty2>
    constexpr 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() noexcept; [added with C++11]
template<class Ty>
    constexpr Ty&& forward(
        typename remove_reference<Ty>::type& right); [added with C++11]
template<class Ty>
    constexpr Ty&& forward(
        typename remove_reference<Ty>::type&& right) noexcept; [added with C++11]
template<class Ty>
    constexpr typename remove_reference<Ty>::type&&
        move(Ty&& right) noexcept; [added with C++11]
template<class Ty>
	constexpr 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 TR1]
    constexpr RI& get(pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2> [added with TR1]
    constexpr const RI& get(const pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2> [added with C++11]
    constexpr RI&& get(pair<T1, T2>&& pr) noexcept;

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

template<class T1, class T2> [added with TR1]
    class tuple_size<pair<T1, T2> >;

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

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

template<class T1, class T2 = T1> [added with C++14]
    T1 exchange(T1& obj, T2& new_val);

    // SEQUENCES
template<class Ty, Ty... Index>
    struct integer_sequence; [added with C++14]
template<size_t... Index>
    using index_sequence = [added with C++14]
        integer_sequence<size_t, Index...>;
template<class... Ty, Ty Size>
    using make_integer_sequence = [added with C++14]
        integer_sequence<Ty, magic>;
template<size_t Size>
    using make_index_sequence = [added with C++14]
        make_integer_sequence<size_t, Size>;
template<class... Index>
    using index_sequence_for = [added with C++14]
        make_index_sequence<sizeof...(Index)>;

    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() noexcept; [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.

exchange

template<class T1, class T2 = T1> [added with C++14]
    T1 exchange(T1& obj, T2& new_val);

The function executes:

T1 old_val = std::move(obj);
obj = std::forward<T2>(new_val);
return (old_val);

forward

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

The template functions return 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 TR1]
    constexpr RI& get(pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2> [added with TR1]
    constexpr const RI& get(const pair<T1, T2>& pr) noexcept;
template<int Idx, class T1, class T2> [added with C++11]
    constexpr RI&& get(pair<T1, T2>&& pr) noexcept;

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

template<class T2, class T1> [added with C++14]
    constexpr RI& get(pair<T1, T2>& pr) noexcept;
template<class T2, class T1> [added with C++14]
    constexpr const RI& get(const pair<T1, T2>& pr) noexcept;
template<class T2, class T1> [added with C++14]
    constexpr 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 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&&.

For the first three template functions, 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.

The remaining functions require that T1 and T2 are different types. The second group of three template functions return pr.first, and the third group of three template functions return pr.second.

index_sequence

template<size_t... Index>
    using index_sequence = [added with C++14]
        integer_sequence<size_t, Index...>;

The template alias specifies an integer_sequence whose first parameter is size_t.

index_sequence_for

template<size_t... Index>
    using index_sequence_for = [added with C++14]
        make_index_sequence<sizeof...Index>;

The template alias specifies an index_sequence whose parameter list has the same length as Index.

integer_sequence

template<class Ty, Ty... Index>
    struct integer_sequence [added with C++14]
    { // zero or more Index parameters of type Ty
    typedef integer_sequence<Ty, Index...> type;
    typedef Ty value_type;
    constexpr size_t size() noexcept
        { // get length of parameter list
        return (sizeof...(Index));
        }
    };

The template struct is characterized by its list of zero or more Index parameters of type Ty.

make_index_sequence

template<size_t Size>
    using make_index_sequence = [added with C++14]
        make_integer_sequence<size_t, Size>;

The template alias has the same effect as make_integer_sequence<size_t, Size>.

make_integer_sequence

template<class... Ty, Ty Size>
    using integer_sequence = [added with C++14]
        integer_sequence<Ty, magic>;

The template alias has as base class an integer_sequence whose parameters are Ty followed by Size parameters with values 0, 1, ...

make_pair

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

The template functions return 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>
    constexpr 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>
	constexpr typename conditional<!is_nothrow_move_constructible<Ty>::value
		&& is_copy_constructible<Ty>::value,
			const Ty&, Ty&&>::type
	move_if_noexcept(Ty& right) noexcept; [added with C++11]

The template function returns move(right).

operator!=

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

The template functions return !(left == right).

operator==

template<class Ty1, class Ty2>
    constexpr 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>
    constexpr 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>
    constexpr bool operator<=(const pair<Ty1, Ty2>& left,
        const pair<Ty1, Ty2>& right);

The template functions return !(right < left).

operator>

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

The template functions return right < left.

operator>=

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

The template functions return !(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]
        constexpr 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]
        constexpr pair(const pair<Other1, Other2>& right);
    template<class Other1, class Other2> [added with C++11]
        constexpr 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);

    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);

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();
constexpr pair(const Ty1& val1, const Ty2& val2);
template<class Other1, class Other2> [added with C++11]
    constexpr 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]
    constexpr pair(const pair<Other1, Other2>& right);
template<class Other1, class Other2> [added with C++11]
    constexpr 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 and 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 Ty2

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 TR1]
    class tuple_element<0, pair<T1, T2> > {
    typedef T1 type;
    };
template<class T1, class T2> [added with TR1]
    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 TR1]
    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.

Copyright (c) by P.J. Plauger. All rights reserved.