[#bsl-set-0d]
= xref:bsl.adoc[bsl]::set
:relfileprefix: ../
:mrdocs:

This class template implements a value‐semantic container type holding an ordered sequence of unique keys (of the template parameter type, `KEY`).

== Synopsis

Declared in `<bslstl_set.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
template<
    class KEY,
    class COMPARATOR = std::less<KEY>,
    class ALLOCATOR = xref:bsl/allocator-0df.adoc[allocator<KEY>]>
class set;
----

== Description

This class: * supports a complete set of _value‐semantic_ operations except for `BDEX` serialization * is _exception‐neutral_ (agnostic except for the `at` method) * is _alias‐safe_ * is `const` _thread‐safe_ For terminology see {`bsldoc_glossary`}.

== Type Aliases

[cols="1,4"]
|===
| Name| Description
| xref:bsl/set-0d/allocator_type.adoc[`allocator_type`] 
| This `typedef` is an alias to the (template parameter) `ALLOCATOR`.
| xref:bsl/set-0d/const_iterator.adoc[`const_iterator`] 
| This `typedef` is an alias to `iterator`.
| xref:bsl/set-0d/const_pointer.adoc[`const_pointer`] 
| This `typedef` is an alias to the allocator const‐pointer type.
| xref:bsl/set-0d/const_reference.adoc[`const_reference`] 
| This `typedef` is an alias for `const_reference`.
| xref:bsl/set-0d/const_reverse_iterator.adoc[`const_reverse_iterator`] 
| This `typedef` is an alias to the const reverse iterator type.
| xref:bsl/set-0d/difference_type.adoc[`difference_type`] 
| This `typedef` is an alias to the allocator difference type.
| xref:bsl/set-0d/iterator.adoc[`iterator`] 
| This `typedef` is an alias to the red‐black tree iterator type.
| xref:bsl/set-0d/key_compare.adoc[`key_compare`] 
| This `typedef` is an alias to the (template parameter) `COMPARATOR`.
| xref:bsl/set-0d/key_type.adoc[`key_type`] 
| This `typedef` is an alias to the (template parameter) `KEY` type.
| xref:bsl/set-0d/pointer.adoc[`pointer`] 
| This `typedef` is an alias to the allocator pointer type.
| xref:bsl/set-0d/reference.adoc[`reference`] 
| This `typedef` is an alias to `value_type&`.
| xref:bsl/set-0d/reverse_iterator.adoc[`reverse_iterator`] 
| This `typedef` is an alias to the reverse iterator type.
| xref:bsl/set-0d/size_type.adoc[`size_type`] 
| This `typedef` is an alias to the allocator size type.
| xref:bsl/set-0d/value_compare.adoc[`value_compare`] 
| This `typedef` is an alias to `key_compare`.
| xref:bsl/set-0d/value_type.adoc[`value_type`] 
| This `typedef` is an alias to `key_type`.
|===


== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/set-0d/2constructor-006.adoc[`set`]         [.small]#[constructor]#
| Constructors
| xref:bsl/set-0d/2destructor.adoc[`~set`] [.small]#[destructor]#
| Destroy this object.
| xref:bsl/set-0d/operator_assign-06.adoc[`operator=`] 
| Assignment operators
| xref:bsl/set-0d/begin-054.adoc[`begin`] 
| `begin` overloads
| xref:bsl/set-0d/cbegin.adoc[`cbegin`] 
| Return an iterator providing non‐modifiable access to the first `value_type` object in the ordered sequence of `value_type` objects maintained by this set, or the `cend` iterator if this set is empty.
| xref:bsl/set-0d/cend.adoc[`cend`] 
| Return an iterator providing non‐modifiable access to the past‐the‐end element in the ordered sequence of `value_type` objects maintained by this set.
| xref:bsl/set-0d/clear.adoc[`clear`] 
| Remove all entries from this set. Note that the set is empty after this call, but allocated memory may be retained for future use.
| xref:bsl/set-0d/contains-0b.adoc[`contains`] 
| Return `true` if this map contains an element whose key is equivalent to the specified `key`.
| xref:bsl/set-0d/count-0a3.adoc[`count`] 
| `count` overloads
| xref:bsl/set-0d/crbegin.adoc[`crbegin`] 
| Return a reverse iterator providing non‐modifiable access to the last `value_type` object in the ordered sequence of `value_type` objects maintained by this set, or `crend` if this set is empty.
| xref:bsl/set-0d/crend.adoc[`crend`] 
| Return a reverse iterator providing non‐modifiable access to the prior‐to‐the‐beginning element in the ordered sequence of `value_type` objects maintained by this set.
| xref:bsl/set-0d/emplace.adoc[`emplace`] 
| Insert into this set a newly created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value_type`, if a key equivalent to such a value does not already exist in this set; otherwise, this method has no effect (other than possibly creating a temporary `value_type` object). Return a pair whose `first` member is an iterator referring to the (possibly newly created and inserted) object in this set whose value is equivalent to that of an object constructed from `arguments`, and whose `second` member is `true` if a new value was inserted, and `false` if an equivalent key was already present. This method requires that the (template parameter) type `KEY` be `emplace‐constructible` from `arguments` (see {Requirements on `KEY`}).
| xref:bsl/set-0d/emplace_hint.adoc[`emplace_hint`] 
| Insert into this set a newly created `value_type` object, constructed by forwarding `get_allocator()` (if required) and the specified (variable number of) `arguments` to the corresponding constructor of `value_type`, (in amortized constant time if the specified `hint` is a valid immediate successor to the `value_type` object constructed from `arguments`), if a key equivalent to such a value does not already exist in this set; otherwise, this method has no effect (other than possibly creating a temporary `value_type` object). Return an iterator referring to the (possibly newly created and inserted) object in this set whose value is equivalent to that of an object constructed from `arguments`. If `hint` is not a valid immediate successor to the `value_type` object implied by `arguments`, this operation has `O[log(N)]` complexity where `N` is the size of this set. This method requires that the (template parameter) type `KEY` be `emplace‐constructible` from `arguments` (see {Requirements on `KEY`}). The behavior is undefined unless `hint` is an iterator in the range `[begin() .. end()]` (both endpoints included).
| xref:bsl/set-0d/empty.adoc[`empty`] 
| Return `true` if this set contains no elements, and `false` otherwise.
| xref:bsl/set-0d/end-0c.adoc[`end`] 
| `end` overloads
| xref:bsl/set-0d/equal_range-07.adoc[`equal_range`] 
| `equal_range` overloads
| xref:bsl/set-0d/erase-05.adoc[`erase`] 
| `erase` overloads
| xref:bsl/set-0d/find-0a.adoc[`find`] 
| `find` overloads
| xref:bsl/set-0d/get_allocator.adoc[`get_allocator`] 
| Return (a copy of) the allocator used for memory allocation by this set.
| xref:bsl/set-0d/insert-00a.adoc[`insert`] 
| `insert` overloads
| xref:bsl/set-0d/insert_range.adoc[`insert_range`] 
| Insert into this set the value of each `value_type` object in the specified `range` if the key equivalent of that object is not already contained in this map. The (template parameter) type `RANGE` must meet the requirements the C++20 standard [ranges]providing access to values of a type convertible to `value_type`, and `value_type` must be `emplace‐constructible` from `*i` into this map, where `i` is a dereferenceable iterator obtained from `range` (see {Requirements on `KEY`}). The behavior is undefined if `range` overlaps this set.
| xref:bsl/set-0d/key_comp.adoc[`key_comp`] 
| Return the key‐comparison functor (or function pointer) used by this set; if a comparator was supplied at construction, return its value, otherwise return a default constructed `key_compare` object. Note that this comparator compares objects of type `KEY`, which is the type of the `value_type` objects contained in this set.
| xref:bsl/set-0d/lower_bound-0b.adoc[`lower_bound`] 
| `lower_bound` overloads
| xref:bsl/set-0d/max_size.adoc[`max_size`] 
| Return a theoretical upper bound on the largest number of elements that this set could possibly hold. Note that there is no guarantee that the set can successfully grow to the returned size, or even close to that size without running out of resources.
| xref:bsl/set-0d/rbegin-08.adoc[`rbegin`] 
| `rbegin` overloads
| xref:bsl/set-0d/rend-0b.adoc[`rend`] 
| `rend` overloads
| xref:bsl/set-0d/size.adoc[`size`] 
| Return the number of elements in this set.
| xref:bsl/set-0d/swap.adoc[`swap`] 
| Exchange the value and comparator of this object with those of the specified `other` object; also exchange the allocator of this object with that of `other` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This method provides the no‐throw exception‐safety guarantee if and only if the (template parameter) type `COMPARATOR` provides a no‐throw swap operation, and provides the basic exception‐safety guarantee otherwise; if an exception is thrown, both objects are left in valid but unspecified states. This operation has `O[1]` complexity if either this object was created with the same allocator as `other` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in this object and `other`, respectively. Note that this method`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
| xref:bsl/set-0d/upper_bound-0c.adoc[`upper_bound`] 
| `upper_bound` overloads
| xref:bsl/set-0d/value_comp.adoc[`value_comp`] 
| Return a functor for comparing two `value_type` objects using `key_comp()`. Note that since `value_type` is an alias to `KEY` for `set`, this method returns the same functor as `key_comp()`.
|===


== Deduction Guides

[cols="1,4"]
|===
| Name| Description
| xref:bsl/set-03.adoc[`set<KEY>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `set`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/set-051.adoc[`set<KEY>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `set`. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/set-09.adoc[`set<KEY, COMPARATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `set`. Deduce the template parameter `COMPARATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/set-0f9.adoc[`set<KEY, COMPARATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `set`. Deduce the template parameter `COMPARATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the specified `ALLOC` is convertible to `bsl::allocator<KEY>`.
| xref:bsl/set-0f6.adoc[`set<KEY, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `set`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor.
| xref:bsl/set-0a.adoc[`set<KEY, COMPARATOR, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `set`. Deduce the template parameters `COMPARATOR` and `ALLOCATOR` from the other parameters passed to the constructor. This guide does not participate unless the supplied (or defaulted) `ALLOCATOR` meets the requirements of a standard allocator.
| xref:bsl/set-05a.adoc[`set<KEY, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the initializer_list supplied to the constructor of `set`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor.
| xref:bsl/set-0b.adoc[`set<KEY, std::less<KEY>, ALLOCATOR>`] 
| Deduce the template parameter `KEY` from the `value_type` of the iterators supplied to the constructor of `set`. Deduce the template parameter `ALLOCATOR` from the other parameter passed to the constructor. This deduction guide does not participate unless the supplied allocator meets the requirements of a standard allocator.
|===


== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:bsl/erase_if-04.adoc[`erase_if`]
| Erase all the elements in the specified set `s` that satisfy the specified predicate `predicate`. Return the number of elements erased.
| xref:bsl/operator_3way-0da.adoc[`operator<=>`]
| Perform a lexicographic three‐way comparison of the specified `lhs` and the specified `rhs` sets by using the comparison operators of `KEY` on each element; return the result of that comparison.
| xref:bsl/operator_eq-045.adoc[`operator==`]
| Return `true` if the specified `lhs` and `rhs` objects have the same value, and `false` otherwise. Two `set` objects `lhs` and `rhs` have the same value if they have the same number of keys, and each element in the ordered sequence of keys of `lhs` has the same value as the corresponding element in the ordered sequence of keys of `rhs`. This method requires that the (template parameter) type `KEY` be `equality‐comparable` (see {Requirements on `KEY`}).
| xref:bsl/swap-0c8.adoc[`swap`]
| Exchange the value and comparator of the specified `a` object with those of the specified `b` object; also exchange the allocator of `a` with that of `b` if the (template parameter) type `ALLOCATOR` has the `propagate_on_container_swap` trait, and do not modify either allocator otherwise. This function provides the no‐throw exception‐safety guarantee if and only if the (template parameter) type `COMPARATOR` provides a no‐throw swap operation, and provides the basic exception‐safety guarantee otherwise; if an exception is thrown, both objects are left in valid but unspecified states. This operation has `O[1]` complexity if either `a` was created with the same allocator as `b` or `ALLOCATOR` has the `propagate_on_container_swap` trait; otherwise, it has `O[n + m]` complexity, where `n` and `m` are the number of elements in `a` and `b`, respectively. Note that this function`s support for swapping objects created with different allocators when `ALLOCATOR` does not have the `propagate_on_container_swap` trait is a departure from the C++ Standard.
|===


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