[#bsl-pair-0b]
= xref:bsl.adoc[bsl]::pair
:relfileprefix: ../
:mrdocs:

The class template `pair` provides a pair of public data members, `first` and `second`, of type `T1` and `T2` respectively. If either `T1` or `T2` uses `bslma::Allocator` for memory management, then provide an optional `bslma::Allocator` argument for each constructor, to be passed through to the constructors of `first` and/or `second` as appropriate. The interface to this class is identical to the standard `std::pair` except for the addition of the allocators. Note that the implementation of this class provides `first` and `second` through multiple base classes in order to simplify construction of each member when allowing for the various rules for passing allocators in C++11.

== Synopsis

Declared in `<bslstl_pair.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class T1,
    class T2>
class pair
    : public xref:bsl/Pair_First-00.adoc[Pair_First<T1>]
    , public xref:bsl/Pair_Second-05e.adoc[Pair_Second<T2>]
----

== Base Classes

[cols="1,4"]
|===
| Name| Description
| `xref:bsl/Pair_First-00.adoc[Pair_First<T1>]`
| This component‐private `class` holds the `first` data member of a `pair` and constructs it appropriately. Note the partial specializations below for the cases that (template parameter) 'TYPE' is a reference.
| `xref:bsl/Pair_Second-05e.adoc[Pair_Second<T2>]`
| This component‐private `class` holds the `second` data member of a `pair` and constructs it appropriately. Note the partial specializations below for the cases that (template parameter) 'TYPE' is a reference.
|===

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/pair-0b/first_type.adoc[`first_type`] 
| This `typedef` is an alias to the type of the `first` data member.
| xref:bsl/pair-0b/second_type.adoc[`second_type`] 
| This `typedef` is an alias to the type of the `second` data member.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/pair-0b/2constructor-089.adoc[`pair`]         [.small]#[constructor]#
| Constructors
| xref:bsl/pair-0b/operator_assign-04.adoc[`operator=`] 
| Assignment operators
| xref:bsl/pair-0b/swap.adoc[`swap`] 
| Swap the value of this pair with the value of the specified `other` pair by applying `swap` to each of the `first` and `second` pair fields.
| xref:bsl/pair-0b/2conversion-057.adoc[`operator std::tuple<PARAM_1&, PARAM_2&>`] 
| Return an `std::tuple` object, holding references that provide modifiable access to the members of this object.
| xref:bsl/pair-0b/2conversion-0e.adoc[`operator std::tuple<PARAM_1&, decltype(std::ignore)&>`] 
| This overload of `template <class PARAM_1, class PARAM_2> operator std::tuple<PARAM_1&, PARAM_2&>()` is called when the (template parameter) `PARAM_2` (second element's type) is the type of `std::ignore`.
| xref:bsl/pair-0b/2conversion-054.adoc[`operator std::tuple<decltype(std::ignore)&, PARAM_2&>`] 
| This overload of `template <class PARAM_1, class PARAM_2> operator std::tuple<PARAM_1&, PARAM_2&>()` is called when the (template parameter) `PARAM_1` (first element's type) is the type of `std::ignore`.
| xref:bsl/pair-0b/2conversion-0c.adoc[`operator std::tuple<decltype(std::ignore)&, decltype(std::ignore)&>`] 
| This overload of `template <class PARAM_1, class PARAM_2> operator std::tuple<PARAM_1&, PARAM_2&>()` is called when the (template parameters) `PARAM_1` (first element's type) and `PARAM_2` (second element's type) are the type of `std::ignore`. Note that this method is defined within the class body intentionally to avoid build failure on MSVC 2015.
|===


== Using Declarations

[cols="1"]
|===
| Name
| xref:bsl/pair-0b/first.adoc[`first`] 
| xref:bsl/pair-0b/second.adoc[`second`] 
|===


== Protected Data Members

[cols="1,4"]
|===
| Name| Description
| xref:bsl/Pair_First-00/first.adoc[`first`] 
| First element of the pair.
| xref:bsl/Pair_Second-05e/second.adoc[`second`] 
| Second element of the pair.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/pair-04.adoc[`pair<T1, T2>`] 
| Deduce the specified types `T1` and `T2` from the corresponding template parameters of the `std::pair` supplied to the constructor of `pair`.
| xref:bsl/pair-09.adoc[`pair<T1, T2>`] 
| Deduce the specified types `T1` and `T2` from the corresponding types supplied to the constructor of `pair`.
| xref:bsl/pair-03.adoc[`pair<T1, T2>`] 
| Deduce the specified types `T1` and `T2` from the corresponding template parameters of the `bsl::pair` supplied to the constructor of `pair`. This guide does not participate in deduction unless the specified `ALLOC` inherits from `bslma::Allocator`.
| xref:bsl/pair-05.adoc[`pair<T1, T2>`] 
| Deduce the specified types `T1` and `T2` from the corresponding template parameters of the `std::pair` supplied to the constructor of `pair`. This guide does not participate in deduction unless the specified `ALLOC` inherits from `bslma::Allocator`.
| xref:bsl/pair-0f.adoc[`pair<T1, T2>`] 
| Deduce the specified types `T1` and `T2` from the corresponding types supplied to the constructor of `pair`. This guide does not participate in deduction unless the specified `ALLOC` inherits from `bslma::Allocator`.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/get-00c.adoc[`get`]
| Return a reference providing modifiable access to the element of the specified `p`, having the ordinal number specified by the (template parameter) `INDEX`. This function will not compile unless the `INDEX` is either 0 or 1.
| xref:bsl/get-034.adoc[`get`]
| Return a rvalue reference providing non‐modifiable access to the element of the specified `p`, having the (template parameter) `TYPE`. This function will not compile unless the types `T1` and `T2` are different and the `TYPE` is the same as either `T1` or `T2`.
| xref:bsl/get-052.adoc[`get`]
| Return a reference providing non‐modifiable access to the element of the specified `p`, having the ordinal number specified by the (template parameter) `INDEX`. This function will not compile unless the `INDEX` is either 0 or 1.
| xref:bsl/get-08.adoc[`get`]
| Return a reference providing non‐modifiable access to the element of the specified `p`, having the (template parameter) `TYPE`. This function will not compile unless the types `T1` and `T2` are different and the `TYPE` is the same as either `T1` or `T2`.
| xref:bsl/get-0b0.adoc[`get`]
| Return a reference providing modifiable access to the element of the specified `p`, having the (template parameter) `TYPE`. This function will not compile unless the types `T1` and `T2` are different and the `TYPE` is the same as either `T1` or `T2`.
| xref:bsl/get-0b3.adoc[`get`]
| Return a rvalue reference providing modifiable access to the element of the specified `p`, having the ordinal number specified by the (template parameter) `INDEX`. This function will not compile unless the `INDEX` is either 0 or 1.
| xref:bsl/get-0e8.adoc[`get`]
| Return a rvalue reference providing modifiable access to the element of the specified `p`, having the (template parameter) `TYPE`. This function will not compile unless the types `T1` and `T2` are different and the `TYPE` is the same as either `T1` or `T2`.
| xref:bsl/operator_3way-05.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of the specified `lhs` and the specified `rhs` pairs by using the comparison operators of `T1` and `T2`; return the result of that comparison.
| xref:bsl/operator_eq-0cf.adoc[`operator==`]
| Return true if the specified `lhs` and `rhs` pair objects have the same value and false otherwise. `lhs` has the same value as `rhs` if `lhs.first == rhs.first` and `lhs.second == rhs.second`. A call to this operator will not compile unless both `T1` and `T2` supply `operator==`.
| xref:bsl/swap-0ce.adoc[`swap`]
| Swap the values of the specified `a` and `b` pairs by applying `swap` to each of the `first` and `second` pair fields. Note that this method is no‐throw only if `swap` on each field is no‐throw.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#