STL Container

# STL Container STL Container # STL Containers * * * A **[container](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Containers)** is an [STL](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#STL) template class that manages a sequence of elements. Such elements can be of any object type that supplies a copy constructor, a destructor, and an assignment operator (all with sensible behavior, of course). The destructor may not throw an exception. This document describes the properties required of all such containers, in terms of a generic template class `Container`. An actual container template class may have additional template parameters. It will certainly have additional member functions. The STL template container classes are: deque hash_map hash_multimap hash_multiset hash_set list map multimap multiset set slist vectorCopy to clipboard The four hash containers and `slist` are not required by the C++ Standard. The Standard C++ library template class `basic_string` also meets the requirements for a template container class. namespace std { template class Container; // TEMPLATE FUNCTIONS template bool operator==( const Container& left, const Container& right); template bool operator!=( const Container& left, const Container& right); template bool operator<( const Container& left, const Container& right); template bool operator>( const Container& left, const Container& right); template bool operator<=( const Container& left, const Container& right); template bool operator>=( const Container& left, const Container& right); template void swap( Container& left, Container& right); } // namespace stdCopy to clipboard ## `Container` * * * **`begin· clear· const_iterator· const_reference· const_reverse_iterator· difference_type· empty· end· erase· iterator· max_size· rbegin· reference· rend· reverse_iterator· size· size_type· swap· value_type`** * * * template class Container { public: typedef T0 size_type; typedef T1 difference_type; typedef T2 reference; typedef T3 const_reference; typedef T4 value_type; typedef T5 iterator; typedef T6 const_iterator; typedef T7 reverse_iterator; typedef T8 const_reverse_iterator; iterator begin(); const_iterator begin() const; iterator end(); const_iterator end() const; reverse_iterator rbegin(); const_reverse_iterator rbegin() const; reverse_iterator rend(); const_reverse_iterator rend() const; size_type size() const; size_type max_size() const; bool empty() const; iterator erase(iterator where); iterator erase(iterator first, iterator last); void clear(); void swap(Container& right); };Copy to clipboard The template class describes an object that controls a varying-length sequence of elements, typically of type `Ty`. The sequence is stored in different ways, depending on the actual container. A container constructor or member function may find occasion to call the constructor `Ty(const Ty&)` or the function `Ty::operator=(const Ty&)`. If such a call throws an exception, the container object is obliged to maintain its integrity, and to rethrow any exception it catches. You can safely swap, assign to, erase, or destroy a container object after it throws one of these exceptions. In general, however, you cannot otherwise predict the state of the sequence controlled by the container object. A few additional caveats: - If the expression `~Ty()` throws an exception, the resulting state of the container object is undefined. - If the container stores an allocator object `al`, and `al` throws an exception other than as a result of a call to `al.allocate`, the resulting state of the container object is undefined. - If the container stores a function object `comp`, to determine how to order the controlled sequence, and `comp` throws an exception of any kind, the resulting state of the container object is undefined. The container classes defined by STL satisfy several additional requirements, as described in the following paragraphs. Container template class `list` provides deterministic, and useful, behavior even in the presence of the exceptions described above. For example, if an exception is thrown during the insertion of one or more elements, the container is left unaltered and the exception is rethrown. For *all* the container classes defined by STL, if an exception is thrown during calls to the following member functions: insert // single element inserted at end push_back push_frontCopy to clipboard the container is left unaltered and the exception is rethrown. For *all* the container classes defined by STL, no exception is thrown during calls to the following member functions: pop_back pop_frontCopy to clipboard The member function `erase` throws an exception only if a **copy operation** (assignment or copy construction) throws an exception. Moreover, no exception is thrown while copying an iterator returned by a member function. The member function `swap` makes additional promises for *all* container classes defined by STL: - The member function throws an exception only if the container stores an allocator object `al`, and `al` throws an exception when copied, or if the container stores a function object `comp`, to determine how to order the controlled sequence, and `comp` throws an exception when copied. - References, pointers, and iterators that designate elements of the controlled sequences being swapped remain valid. An object of a container class defined by STL allocates and frees storage for the sequence it controls through a stored object of type `Alloc`, which is typically a template parameter. Such an [allocator object](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator%20object) must have the same external interface as an object of class [`allocator`<Ty>](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_memory.html#allocator). In particular, `Alloc` must be the same type as `Alloc::rebind::other` For *all* container classes defined by STL, the member function: Alloc get_allocator() const;Copy to clipboard returns a copy of the stored allocator object. Note that the stored allocator object is *not* copied when the container object is assigned. All constructors initialize the value stored in `allocator`, to `Alloc()` if the constructor contains no allocator parameter. According to the C++ Standard a container class defined by STL can assume that: - All objects of class `Alloc` compare equal. - Type `Alloc::const_pointer` is the same as `const Ty *`. - Type `Alloc::const_reference` is the same as `const Ty&`. - Type `Alloc::pointer` is the same as `Ty *`. - Type `Alloc::reference` is the same as `Ty&`. In this [implementation](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#implementation), however, containers do *not* make such simplifying assumptions. Thus, they work properly with allocator objects that are more ambitious: - All objects of class `Alloc` need not compare equal. (You can maintain multiple pools of storage.) - Type `Alloc::const_pointer` need not be the same as `const Ty *`. (A const pointer can be a class.) - Type `Alloc::pointer` need not be the same as `Ty *`. (A pointer can be a class.) ### `Container::begin` const_iterator begin() const; iterator begin();Copy to clipboard The member function returns an iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). ### `Container::clear` void clear();Copy to clipboard The member function calls `erase( begin(), end())`. ### `Container::const_iterator` typedef T6 const_iterator;Copy to clipboard The type describes an object that can serve as a constant iterator for the controlled sequence. It is described here as a synonym for the unspecified type `T6`. ### `Container::const_reference` typedef T3 const_reference;Copy to clipboard The type describes an object that can serve as a constant reference to an element of the controlled sequence. It is described here as a synonym for the unspecified type `T3` (typically `Alloc::const_reference`). ### `Container::const_reverse_iterator` typedef T8 const_reverse_iterator;Copy to clipboard The type describes an object that can serve as a constant reverse iterator for the controlled sequence. It is described here as a synonym for the unspecified type `T8` (typically `reverse_iterator `). ### `Container::difference_type` typedef T1 difference_type;Copy to clipboard The signed integer type describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. It is described here as a synonym for the unspecified type `T1` (typically `Alloc::difference_type`). ### `Container::empty` bool empty() const;Copy to clipboard The member function returns true for an empty controlled sequence. ### `Container::end` const_iterator end() const; iterator end();Copy to clipboard The member function returns an iterator that points just beyond the end of the sequence. ### `Container::erase` iterator erase(iterator where); iterator erase(iterator first, iterator last);Copy to clipboard The first member function removes the element of the controlled sequence pointed to by `where`. The second member function removes the elements of the controlled sequence in the range `[first, last)`. Both return an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. The member functions throw an exception only if a copy operation throws an exception. ### `Container::iterator` typedef T5 iterator;Copy to clipboard The type describes an object that can serve as an iterator for the controlled sequence. It is described here as a synonym for the unspecified type `T5`. An object of type `iterator` can be cast to an object of type `const_iterator`. ### `Container::max_size` size_type max_size() const;Copy to clipboard The member function returns the length of the longest sequence that the object can control, in constant time regardless of the length of the controlled sequence. ### `Container::rbegin` const_reverse_iterator rbegin() const; reverse_iterator rbegin();Copy to clipboard The member function returns a reverse iterator that designates the last element of the controlled sequence. Hence, it designates the beginning of the reverse sequence. ### `Container::reference` typedef T2 reference;Copy to clipboard The type describes an object that can serve as a reference to an element of the controlled sequence. It is described here as a synonym for the unspecified type `T2` (typically `Alloc::reference`). An object of type `reference` can be cast to an object of type `const_reference`. ### `Container::rend` const_reverse_iterator rend() const; reverse_iterator rend();Copy to clipboard The member function returns a reverse iterator that designates the (fictitious) element before the first element of the controlled sequence. Hence, it points just beyond the end of the reverse sequence. ### `Container::reverse_iterator` typedef T7 reverse_iterator;Copy to clipboard The type describes an object that can serve as a reverse iterator for the controlled sequence. It is described here as a synonym for the unspecified type `T7` (typically `reverse_iterator `). ### `Container::size` size_type size() const;Copy to clipboard The member function returns the length of the controlled sequence, in constant time regardless of the length of the controlled sequence. ### `Container::size_type` typedef T0 size_type;Copy to clipboard The unsigned integer type describes an object that can represent the length of any controlled sequence. It is described here as a synonym for the unspecified type `T0` (typically `Alloc::size_type`). ### `Container::swap` void swap(Container& right);Copy to clipboard The member function swaps the controlled sequences between `*this` and `right`. If `get_allocator() == right.get_allocator()`, it does so in constant time. Otherwise, it performs a number of element assignments and constructor calls proportional to the number of elements in the two controlled sequences. ### `Container::value_type` typedef T4 value_type;Copy to clipboard The type is a synonym for the template parameter `Ty`. It is described here as a synonym for the unspecified type `T4` (typically `Alloc::value_type`). ## `operator!=` template bool operator!=( const Container & left, const Container & right);Copy to clipboard The template function returns `!(left == right)`. ## `operator==` template bool operator==( const Container & left, const Container & right);Copy to clipboard The template function overloads `operator==` to compare two objects of template class [`Container`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Container). The function returns `left.size() == right.size() && equal(left. begin(), left. end(), right.begin())`. ## `operator<` template bool operator<( const Container & left, const Container & right);Copy to clipboard The template function overloads `operator<` to compare two objects of template class [`Container`](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_lib_cont.html#Container). The function returns `lexicographical_compare(left. begin(), left. end(), right.begin(), right.end())`. ## `operator<=` template bool operator<=( const Container & left, const Container & right);Copy to clipboard The template function returns `!(right < left)`. ## `operator>` template bool operator>( const Container & left, const Container & right);Copy to clipboard The template function returns `right < left`. ## `operator>=` template bool operator>=( const Container & left, const Container & right);Copy to clipboard The template function returns `!(left < right)`. ## `swap` template void swap( Container & left, Container & right);Copy to clipboard The template function executes `left.swap(right)`. * * * See also the **[Table of Contents](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_index.html#Table%20of%20Contents)** and the **[Index](https://docs.qualcomm.com/doc/80-N3040-23/topic/_cpp_index.html)**. *[Copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_pjp.html) © 1992-2006by P.J. Plauger. Portions derived from work[copyright](https://docs.qualcomm.com/doc/80-N3040-23/topic/cpp_crit_hp.html) © 1994by Hewlett-Packard Company. All rights reserved.* Last Published: Oct 06, 2026 [Previous Topic STL Conventions](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cpp_lib_stl.md) [Next Topic Functions](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/cpp_function.md)