namespace std { template<class T> class Cont; // TEMPLATE FUNCTIONS template<class T> bool operator==( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> bool operator!=( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> bool operator<( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> bool operator>( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> bool operator<=( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> bool operator>=( const Cont<T>& lhs, const Cont<T>& rhs); template<class T> void swap( Cont<T>& lhs, Cont<T>& rhs); };
A container is an
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 Cont
.
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 vector
The four hash containers are not required by the C++ Standard.
The Standard C++ library template class basic_string
also
meets the requirements for a template container class.
Cont
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 T<T> > class Cont { 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 it); iterator erase(iterator first, iterator last); void clear(); void swap(Cont& x); };
The template class describes an object that controls a
varying-length sequence of elements,
typically of type T
.
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 T(const T&)
or the function
T::operator=(const T&)
. 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:
~T()
throws an exception, the
resulting state of the container object is undefined.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.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 push_back push_front
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:
erase // single element erased pop_back pop_front
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:
al
,
and al
throws an exception when copied.An object of a container class defined by STL
allocates and frees storage for the sequence it controls
through a stored object of type A
,
which is typically a template parameter. Such an
allocator object must have
the same external interface as an object of class
allocator
<T>.
In particular, A
must be the same type as
A::rebind<value_type>::other
For all container classes defined by STL, the member function:
A get_allocator() const;
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 A()
if the constructor contains
no allocator parameter.
According to the C++ Standard a container class defined by STL can assume that:
A
compare equal.A::const_pointer
is the same as
const T *
.A::const_reference
is the same as
const T&
.A::pointer
is the same as
T *
.A::reference
is the same as
T&
.In this implementation, however, containers do not make such simplifying assumptions. Thus, they work properly with allocator objects that are more ambitious:
A
need not compare equal.
(You can maintain multiple pools of storage.)A::const_pointer
need not be the same as
const T *
.
(A pointer can be a class.)A::pointer
need not be the same as
T *
.
(A const pointer can be a class.)Cont::begin
const_iterator begin() const; iterator begin();
The member function returns an iterator that points at the first element of the sequence (or just beyond the end of an empty sequence).
Cont::clear
void clear();
The member function calls
erase(
begin(),
end())
.
Cont::const_iterator
typedef T6 const_iterator;
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
.
Cont::const_reference
typedef T3 const_reference;
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 A::const_reference
).
Cont::const_reverse_iterator
typedef T8 const_reverse_iterator;
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
<const_iterator>
).
Cont::difference_type
typedef T1 difference_type;
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 A::difference_type
).
Cont::empty
bool empty() const;
The member function returns true for an empty controlled sequence.
Cont::end
const_iterator end() const; iterator end();
The member function returns an iterator that points just beyond the end of the sequence.
Cont::erase
iterator erase(iterator it); iterator erase(iterator first, iterator last);
The first member function removes the element of the controlled
sequence pointed to by it
. 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 never throw an exception.
Cont::iterator
typedef T5 iterator;
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
.
Cont::max_size
size_type max_size() const;
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.
Cont::rbegin
const_reverse_iterator rbegin() const; reverse_iterator rbegin();
The member function returns a reverse iterator that points just beyond the end of the controlled sequence. Hence, it designates the beginning of the reverse sequence.
Cont::reference
typedef T2 reference;
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 A::reference
).
An object of type reference
can be cast
to an object of type
const_reference
.
Cont::rend
const_reverse_iterator rend() const; reverse_iterator rend();
The member function returns a reverse iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). Hence, it designates the end of the reverse sequence.
Cont::reverse_iterator
typedef T7 reverse_iterator;
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
<iterator>
).
Cont::size
size_type size() const;
The member function returns the length of the controlled sequence, in constant time regardless of the length of the controlled sequence.
Cont::size_type
typedef T0 size_type;
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 A::size_type
).
Cont::swap
void swap(Cont& x);
The member function swaps the controlled sequences between
*this
and x
. If
get_allocator()
== x.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.
Cont::value_type
typedef T4 value_type;
The type is a synonym for the template parameter T
.
It is described here as a
synonym for the unspecified type T4
(typically A::value_type
).
operator!=
template<class T> bool operator!=( const Cont <T>& lhs, const Cont <T>& rhs);
The template function returns !(lhs == rhs)
.
operator==
template<class T> bool operator==( const Cont <T>& lhs, const Cont <T>& rhs);
The template function overloads operator==
to compare
two objects of template class
Cont
. The function returns
lhs.size() == rhs.size() &&
equal(lhs.
begin(), lhs.
end(), rhs.begin())
.
operator<
template<class T> bool operator<( const Cont <T>& lhs, const Cont <T>& rhs);
The template function overloads operator<
to compare
two objects of template class
Cont
. The function returns
lexicographical_compare(lhs.
begin(), lhs.
end(), rhs.begin(), rhs.end())
.
operator<=
template<class T> bool operator<=( const Cont <T>& lhs, const Cont <T>& rhs);
The template function returns !(rhs < lhs)
.
operator>
template<class T> bool operator*gt;( const Cont <T>& lhs, const Cont <T>& rhs);
The template function returns rhs < lhs
.
operator>=
template<class T> bool operator>=( const Cont <T>& lhs, const Cont <T>& rhs);
The template function returns !(lhs < rhs)
.
swap
template<class T> void swap( Cont <T>& lhs, Cont <T>& rhs);
The template function executes
lhs.swap(rhs)
.
See also the Table of Contents and the Index.
Copyright © 1992-1996 by P.J. Plauger. Portions derived from work copyright © 1994 by Hewlett-Packard Company. All rights reserved.