Intro(3C++std)

Intro -- introduction to Standard C++ Library classes

Description

This section contains manual pages for the functions contained in the Standard C++ Library. A C++ program can call on a these functions to perform essential services such as input and output. They also provide efficient implementations of frequently used operations. Numerous function and class definitions accompany these functions to help you to make better use of the library.

Using C++ library headers

All C++ library entities are declared or defined in one or more standard headers. To make use of a library entity in a program, write an include directive that names the relevant standard header. The Standard C++ library consists of 51 required headers. This implementation also includes two additional headers, hash_map and hash_set, not required by the C++ Standard, for a total of 53 headers. These include the 15 headers which constitute the Standard Template Library (STL) which establishes uniform standards for the application of iterators to STL containers or other sequences that you define, by STL algorithms or other functions that you define. The conventions used in the STL are described on iterator(3C++std) and algorithm(3C++std).

You include the contents of a standard header by naming it in an include directive, as in:

   #include <iostream>  /* include I/O facilities */

You can include the standard headers in any order, a standard header more than once, or two or more standard headers that define the same macro or the same type. Do not include a standard header within a declaration. Do not define macros that have the same names as keywords before you include a standard header.

A C++ library header includes any other C++ library headers it needs to define needed types. (Always include explicitly any C++ library headers needed in a translation unit, however, lest you guess wrong about its actual dependencies.)

Every function in the library is declared in a standard header. Unlike in Standard C, the standard header never provides a masking macro with the same name as the function, that masks the function declaration and achieves the same effect.

All names other than operator delete and operator new in the C++ library headers are defined in the std namespace, or in a namespace nested within the std namespace. Including a C++ library header does not introduce any library names into the current namespace. You refer to the name cin, for example, std::cin. Alternatively, you can write the declaration:

   using namespace std;

which promotes all library names into the current namespace. If you write this declaration immediately after all include directives, you can otherwise ignore namespace considerations in the remainder of the translation unit. Note that macro names are not subject to the rules for nesting namespaces.

Unless specifically indicated otherwise, you may not define names in std namespace, or in a namespace nested within the std namespace.

iostreams conventions

The iostreams headers support conversions between text and encoded forms, and input and output to external files. There headers are: fstream(3C++std), iomanip(3C++std), ios(3C++std), iosfwd(3C++std), iostream(3C++std), istream(3C++std), ostream(3C++std), sstream(3C++std), streambuf(3C++std), and strstream(3C++std).

The simplest use of iostreams requires only that you include the header iostream. You can then extract values from cin, to read the standard input. The rules for doing so are outlined in the description of istream(3C++std). You can also insert values to cout, to write to the standard output. The rules for doing so are outlined in the description of ostream(3C++std). Format control common to both extractors and insertors is managed by ios(3C++std). Manipulating this format information in the guise of extracting and inserting objects is the province of several iomanip(3C++std) manipulators.

You can perform the same iostreams operations on files that you open by name, using the classes declared in fstream(3C++std). To convert between iostreams and string(3C++std) objects, use the classes declared in sstream(3C++std). To do the same with C strings, use the classes declared in strstream(3C++std).

The remaining headers provide support services, typically of direct interest to only the most advanced users of the iostreams classes.

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

If the expression ~T() 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
   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:

   pop_back
   pop_front

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 <I>all</I> 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.
References, pointers, and iterators that designate elements of the controlled sequences being swapped remain valid.</LI>

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:

All objects of class A compare equal.
Type A::const_pointer is the same as const T *.
Type A::const_reference is the same as const T&.
Type A::pointer is the same as T *.
Type 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:

All objects of class A need not compare equal. (You can maintain multiple pools of storage.)
Type A::const_pointer need not be the same as const T *. (A pointer can be a class.)
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.

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 throw an exception only if a copy operation throws 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).

References

CC(1C++)

The classes and routines of the pre-standard C++ libraries and the C++ Standard Components, see Intro(3C++).

Standards compliance

This library provides conformance to the ISO/IEC 14882:1998 C++ standard.