Containers:Cont::const_reference, difference_type, reverse_iterator

<< STL Conventions:Iterator Conventions, Algorithm Conventions

Preprocessing >>

Chapter 10. Containers

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 (page 1) 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 (page 274)

list (page 310)

map (page 321)

multimap (page 328)

multiset (page 354)

set (page 361)

vector (page 404)

The Standard C++ library template class basic_string also meets the requirements

for a template container class.

Cont

begin (page 44) · clear (page 44) · const_iterator (page 44) · const_reference (page

44) · const_reverse_iterator (page 44) · difference_type (page 44) · empty (page 44)

· end (page 45) · erase (page 45) · iterator (page 45) · max_size (page 45) · rbegin

(page 45) · reference (page 45) · rend (page 45) · reverse_iterator (page 46) · size

(page 46) · size_type (page 46) · swap (page 46) · value_type (page 46)

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

v If the expression ~T() throws an exception, the resulting state of the container

object is undefined.

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

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

Standard C++ Library

Container template class list (page 310) 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 (page 46) makes additional promises for all container

classes defined by STL:

v The member function throws an exception only if the container stores an

allocator object al, and al throws an exception when copied.

v 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 A, which is typically a template

parameter. Such an allocator object (page 337) must have the same external

interface as an object of class allocator (page 337). 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 (page 431) a container class defined by STL can

assume that:

v All objects of class A compare equal.

v Type A::const_pointer is the same as const T *.

v Type A::const_reference is the same as const T&.

v Type A::pointer is the same as T *.

v Type A::reference is the same as T&.

In this implementation (page 3), however, containers do not make such simplifying

assumptions. Thus, they work properly with allocator objects that are more

ambitious:

Chapter 10. Containers

v All objects of class A need not compare equal. (You can maintain multiple pools

of storage.)

v Type A::const_pointer need not be the same as const T *. (A pointer can be a

class.)

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

Standard C++ Library

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 (page 44).

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 (page 44).

Cont::rend

const_reverse_iterator rend() const;

reverse_iterator rend();

Chapter 10. Containers

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

Standard C++ Library

The template function overloads operator== to compare two objects of template

class Cont (page 42). 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 (page 46)(rhs).

reserved.

Chapter 10. Containers

Standard C++ Library

Table of Contents: