STL Free

Download as pdf or txt
Download as pdf or txt
You are on page 1of 181
At a glance
Powered by AI
The document discusses the main components of the C++ Standard Template Library (STL) including containers, algorithms, iterators and other concepts.

The main components of the C++ STL discussed are containers, algorithms, iterators, headers, allocators, adaptors and functors.

Iterators are objects that point to elements in a container and allow algorithms to operate on those elements. They are important in the C++ STL because algorithms require iterators to access container elements.

Taris presents

Free words concerning C++ STL

This document is under GNU FDL

Contents
I Presentation of the C++ STL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

11
12 12 12 12 12 13 14 14 14 15 15 15

1 What is the C++ STL ? 1.1 Introduction to C++ STL 1.2 Why use the STL ? . . . . 1.3 Why not use the STL ? . 1.4 What is a template class ? 1.5 STL headers . . . . . . . . 1.6 STL algorithms . . . . . . 1.7 STL containers . . . . . . 1.8 Iterators . . . . . . . . . . 1.9 Allocators . . . . . . . . . 1.10 Adaptors . . . . . . . . . 1.11 Functors . . . . . . . . . .

II

Iterators

16
17 17 17 18

1 What is an iterator ? 1.1 Why are iterators so important ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 Iterators example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 What are the dierent types of iterator ? . . . . . . . . . . . . . . . . . . . . . . .

III

Algorithms

19
20 21 21 22 23 23 23 23 24 24 24 25 25 25

1 Introduction on STL algorithms 2 Comparing algorithms 2.1 Lexicographical compare . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Equal and mismatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Copying 3.1 copy 3.2 copy 3.3 copy algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . backward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4 Counting algorithms 4.1 count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4.2 count if . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 Filling algorithms 5.1 ll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5.2 ll n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CONTENTS

6 for each 6.1 for each . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 generate 7.1 generate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7.2 generate n . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Heap algorithms 8.1 push heap . . 8.2 pop heap . . . 8.3 make heap . . 8.4 sort heap . . 8.5 is heap . . . .

26 26 27 27 27 28 28 28 29 29 29 30 30 30 31 31 31 31 31 33 33 34 34 35 35 35 35 36 36 38 38 38 39 39 40 40 40 40 40 42 42 42 42 42

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

9 Merging algorithms 9.1 Merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9.2 Inplace merge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Minimum and maximum 10.1 Min . . . . . . . . . . . 10.2 Max . . . . . . . . . . . 10.3 Min element . . . . . . . 10.4 Max element . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

11 Mismatch 11.1 Mismatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 nth element 12.1 Nth element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Numeric algorithms 13.1 Accumulate . . . . 13.2 Adjacent dierence 13.3 Inner product . . . 13.4 Partial sum . . . . 13.5 Power . . . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

14 partition and stable partition 14.1 partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2 stable partition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Randomizing algorithms 15.1 Random shue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Removing algorithms 16.1 remove . . . . . . . 16.2 remove if . . . . . 16.3 remove copy . . . . 16.4 remove copy if . . 17 Replacing algorithms 17.1 replace . . . . . . . 17.2 replace if . . . . . 17.3 replace copy . . . . 17.4 replace copy if . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

CONTENTS

18 Reversing and rotating 18.1 reverse . . . . . . . . 18.2 reverse copy . . . . . 18.3 rotate . . . . . . . . 18.4 rotate copy . . . . . 19 Searching algorithms 19.1 adjacent nd . . . 19.2 binary search . . . 19.3 equal range . . . . 19.4 nd . . . . . . . . 19.5 nd end . . . . . . 19.6 nd rst of . . . . 19.7 lower bound . . . . 19.8 search . . . . . . . 19.9 search n . . . . . . 19.10upper bound . . . .

algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

44 44 44 44 44 46 46 46 46 47 47 47 48 48 48 49 50 50 50 51 51 51 53 53 53 54 54 55 55 55 55 56 56 57 57 57

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

20 Set algorithms 20.1 includes . . . . . . . . . 20.2 set dierence . . . . . . 20.3 set intersection . . . . . 20.4 set symmetric dierence 20.5 set union . . . . . . . . 21 Sorting algorithms 21.1 sort . . . . . . . 21.2 partial sort copy 21.3 partial sort . . . 21.4 stable sort . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

22 Swaping algorithms 22.1 iter swap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.2 swap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22.3 swap ranges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 transform 23.1 Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 unique 24.1 unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.2 unique copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

IV

Sequence Containers

58
59 59 59 59

1 Introduction on STL containers 1.1 What is a container ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 What is an associative container ? . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 What is a container adaptor ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CONTENTS

2 Bit 2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9

vector : <bvector.h> Bvector types . . . . . . . . . . Bvector constructors . . . . . . Bvector destructor . . . . . . . Bvector operators . . . . . . . . Bvector iterators . . . . . . . . Bvector size and capacity . . . Accessing elements . . . . . . . Inserting and deleting elements Misc functions . . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

60 60 60 61 61 61 62 62 63 63 65 65 65 66 66 66 67 67 68 69 70 70 71 71 71 71 72 72 73 73 76 76 76 76 77 77 77 78 78 78 80 82 82 82 83 83 83 84 85 85

3 Deque : <deque> 3.1 Deque types . . . . . . . . . . . 3.2 Deque constructors . . . . . . . 3.3 Deque destructor . . . . . . . . 3.4 Deque operators . . . . . . . . 3.5 Deque iterators . . . . . . . . . 3.6 Deque size and capacity . . . . 3.7 Accessing elements . . . . . . . 3.8 Inserting and deleting elements 3.9 Misc functions . . . . . . . . . 4 List 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 : <list> List types . . . . . . . . . . . . List constructors . . . . . . . . List destructor . . . . . . . . . List operators . . . . . . . . . . List iterators . . . . . . . . . . List size and capacity . . . . . Accessing elements . . . . . . . Inserting and deleting elements Misc functions . . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

5 SList : <slist> 5.1 How to know if I should use list 5.2 Slist types . . . . . . . . . . . . 5.3 Slist constructors . . . . . . . . 5.4 Slist destructor . . . . . . . . . 5.5 Slist operators . . . . . . . . . 5.6 Slist iterators . . . . . . . . . . 5.7 Slist size and capacity . . . . . 5.8 Accessing elements . . . . . . . 5.9 Inserting and deleting elements 5.10 Misc functions . . . . . . . . . 6 Vector : <vector> 6.1 Vector types . . . . . . . . . . . 6.2 Vector constructors . . . . . . . 6.3 Vector destructor . . . . . . . . 6.4 Vector operators . . . . . . . . 6.5 Vector iterators . . . . . . . . . 6.6 Vector size and capacity . . . . 6.7 Accessing elements . . . . . . . 6.8 Inserting and deleting elements

or slist ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

CONTENTS

6.9

Misc functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

86 87 87 87 88 88 89 89 89 89

7 Bitset : <bitset> 7.1 Bitset types . . . . . . . . 7.2 Bitset constructors . . . . 7.3 Bitset destructor . . . . . 7.4 Bitset operators . . . . . . 7.5 Bitset iterators . . . . . . 7.6 Bitset size and capacity . 7.7 Testing and changing bits 7.8 Converting a bitset . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

Associative Containers

91
92 92 92 93 93 93 94 94 94 95 95 95 96 97 99 99 99 100 100 101 101 101 101 102 103 104 104 104 105 105 105 105 106 106 106

1 What are associative containers ? 1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 When use an associative container ? . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Hash : <hashtable.h> 2.1 What is a hash table ? . . . . . 2.2 Hash types . . . . . . . . . . . 2.3 Hash constructors . . . . . . . 2.4 Hash destructor . . . . . . . . . 2.5 Hash operators . . . . . . . . . 2.6 Hash iterators . . . . . . . . . . 2.7 Hash size and capacity . . . . . 2.8 Inserting and deleting elements 2.9 Misc functions . . . . . . . . . 2.10 Hash table exemple . . . . . . . 3 Hash map : <hash map> 3.1 What is a hash map ? . . . . . 3.2 Hash map types . . . . . . . . . 3.3 Hash map constructors . . . . . 3.4 Hash map destructor . . . . . . 3.5 Hash map operators . . . . . . 3.6 Hash Map iterators . . . . . . . 3.7 Hash map size and capacity . . 3.8 Inserting and deleting elements 3.9 Misc functions . . . . . . . . . 3.10 Hash map exemple . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

4 Hash multimap : <hash map> 4.1 What is a hash multimap ? . . . 4.2 Hash multimap types . . . . . . . 4.3 Hash multimap constructors . . . 4.4 Hash multimap destructor . . . . 4.5 Hash multimap operators . . . . 4.6 Hash Multimap iterators . . . . . 4.7 Hash multimap size and capacity 4.8 Inserting and deleting elements . 4.9 Misc functions . . . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

CONTENTS

5 Hash set : <hash set> 5.1 What is a hash set ? . . . . . . 5.2 Hash set types . . . . . . . . . 5.3 Hash set constructors . . . . . 5.4 Hash set destructor . . . . . . . 5.5 Hash set operators . . . . . . . 5.6 Hash set iterators . . . . . . . . 5.7 Hash set size and capacity . . . 5.8 Inserting and deleting elements 5.9 Misc functions . . . . . . . . . 6 Hash multiset : <hash set> 6.1 What is a hash multiset ? . . . 6.2 Hash multiset types . . . . . . 6.3 Hash multiset constructors . . . 6.4 Hash multiset destructor . . . . 6.5 Hash multiset operators . . . . 6.6 Hash multiset iterators . . . . . 6.7 Hash multiset size and capacity 6.8 Inserting and deleting elements 6.9 Misc functions . . . . . . . . . 7 Map : <map> 7.1 What is a map ? . . . . . . . . 7.2 Map types . . . . . . . . . . . . 7.3 Map constructors . . . . . . . . 7.4 Map destructor . . . . . . . . . 7.5 Map operators . . . . . . . . . 7.6 Map iterators . . . . . . . . . . 7.7 Map size and capacity . . . . . 7.8 Inserting and deleting elements 7.9 Misc functions . . . . . . . . . 8 Multimap : <multimap.h> 8.1 What is a multimap ? . . . . . 8.2 Multimap types . . . . . . . . . 8.3 Multimap constructors . . . . . 8.4 Multimap destructor . . . . . . 8.5 Multimap operators . . . . . . 8.6 Multimap iterators . . . . . . . 8.7 Multimap size and capacity . . 8.8 Inserting and deleting elements 8.9 Misc functions . . . . . . . . . 8.10 Multimap exemple . . . . . . . 9 Multiset : <set> 9.1 What is a multiset ? . . . . . . 9.2 Multiset types . . . . . . . . . . 9.3 Multiset constructors . . . . . . 9.4 Multiset destructor . . . . . . . 9.5 Multiset operators . . . . . . . 9.6 Multiset iterators . . . . . . . . 9.7 Multiset size and capacity . . . 9.8 Inserting and deleting elements

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

108 108 108 109 109 109 110 110 110 111 112 112 112 113 113 113 114 114 114 115 116 116 116 117 117 117 117 118 118 119 120 120 120 121 121 121 121 122 122 123 123 125 125 125 126 126 126 126 126 127

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

CONTENTS

9.9

Misc functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 129 129 129 130 130 130 130 131 131 132 132

10 Set : <set> 10.1 The set container . . . . . . . . 10.2 Set types . . . . . . . . . . . . 10.3 Set constructors . . . . . . . . . 10.4 Set destructor . . . . . . . . . . 10.5 Set operators . . . . . . . . . . 10.6 Set iterators . . . . . . . . . . . 10.7 Set size and capacity . . . . . . 10.8 Inserting and deleting elements 10.9 Misc functions . . . . . . . . . 10.10Set table exemple . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

VI

Container adaptors
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

134
135 135 135 136 136 136 136 136 136 137 137 137 138 138 138 138 138 139 140 140 140 141 141 141 141 141 141

1 Priority queue : <queue> 1.1 Priority queue types . . . . . . . 1.2 Priority queue constructors . . . 1.3 Priority queue destructor . . . . 1.4 Priority queue operators . . . . . 1.5 Priority queue iterators . . . . . 1.6 Priority queue size and capacity . 1.7 Accessing elements . . . . . . . . 1.8 Inserting and deleting elements . 2 Queue : <queue> 2.1 Queue types . . . . . . . . . . . 2.2 Queue constructors . . . . . . . 2.3 Queue destructor . . . . . . . . 2.4 Queue operators . . . . . . . . 2.5 Queue iterators . . . . . . . . . 2.6 Queue size and capacity . . . . 2.7 Accessing elements . . . . . . . 2.8 Inserting and deleting elements 3 Stack 3.1 Stack types . . . . . . . . . . . 3.2 Stack constructors . . . . . . . 3.3 Stack destructor . . . . . . . . 3.4 Stack operators . . . . . . . . . 3.5 Stack iterators . . . . . . . . . 3.6 Stack size and capacity . . . . . 3.7 Accessing elements . . . . . . . 3.8 Inserting and deleting elements

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

. . . . . . . .

VII

Functors

143
144 145 146

1 Introduction on functors 2 Unary function 3 logical not

CONTENTS

4 Binary function 5 plus 6 minus 7 multiplies 8 divides 9 modulus 10 negate 11 equal to and not equal to 12 less and greater 13 logical and and logical or

147 148 149 150 151 152 153 154 155 156

14 binder1st and binder2nd 157 14.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 15 ptr fun, pointer to unary function and pointer to binary function 159 15.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 16 unary negate and binary negate 161 16.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 17 Member function adaptors 163 17.1 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

VIII

Misc

167
168

1 auto ptr

IX

Frequently Asked Question

169
170 172 173 174

1 FAQ about iterators 2 FAQ about containers 3 FAQ about algorithms 4 FAQ about relations between C and C++

GNU Free Documentation License


. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

175
176 176 177 178 178 179

1 GNU Free Documentation License 1.1 APPLICABILITY AND DEFINITIONS 1.2 VERBATIM COPYING . . . . . . . . . 1.3 COPYING IN QUANTITY . . . . . . . 1.4 MODIFICATIONS . . . . . . . . . . . . 1.5 COMBINING DOCUMENTS . . . . . .

CONTENTS

1.6 1.7 1.8 1.9 1.10

COLLECTIONS OF DOCUMENTS . . . . . . . . . AGGREGATION WITH INDEPENDENT WORKS TRANSLATION . . . . . . . . . . . . . . . . . . . . TERMINATION . . . . . . . . . . . . . . . . . . . . FUTURE REVISIONS OF THIS LICENSE . . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

. . . . .

180 180 180 181 181

10

Part I

Presentation of the C++ STL

11

Chapter 1

What is the C++ STL ?


1.1 Introduction to C++ STL

The C++ STL (which stands for Standard templates library ) is a collection of classes and functions. These are very useful in many cases and allow developers to use them instead of creating their own classes to do the same work. The STL is dierent depending on the platform you are working on. However the basic classes and functions are the same. This documentation is about GNU STL provided with the gcc compiler. Most of the classes described in this document exist on all good C++ compilers.

1.2

Why use the STL ?

There are many reasons to use it. First of all, compiler creators have had many reexions on how to improve the STL implementation. Probably more than any developers who wants to use some classes or functions for just one project. Moreover, your STL implementation may have some bugs (in fact, almost all libraries and programs have). But, generally, due to the number of developers using it, those bugs are known. You can probably browse the website of the creator of your STL and see what is not implemented and what is not working like it should be. Finally, the STL is generally optimized for the system your working on. In many cases, the STL provided with your compiler will be faster than anything (portable) you can write on your own.

1.3

Why not use the STL ?

Perhaps you are a very strong developer. Perhaps the STL you have is very buggy and very slow. Or perhaps, you think you can write your own STL, using some assembly lines, which will be faster than the basic STL. In all those cases, you can join the GNU project (see www.gnu.org ) and improve your STL or create your own. All the developers using it will gladly receive your contribution.

1.4

What is a template class ?

A template class is a class that can be instantiated with any type, unless this type does not satisfy the constraints required to be used by the template class. In other words, a template class is a class which will be given a type in argument at the creation of an object.

12

The C++ STL

For example, the vector class can contain objects of a given type. This type is given when a new vector object is created. If you want your vector to contain int s, you can declare it like this : vector<int> v; But the same class vector can be used to contain oat or to contain a vector of int : vector<oat> v f; vector< vector<int> > v of v int; Thus, a template class has only one implementation but can be used with multiple types. The problem is that creating a template class generally creates constraints on the type. In the vector case the type must have a public copy constructor. Many classes have it, but not all. So, you cannot store all classes in a vector.

1.5

STL headers

Here is a description of all STL headers and their contents : deque : double access queue functional : template and utility function denitions hash map : hash map container denition hash set : hash set container denition iomanip : input and output stream manipulation functions iosfwd : input and output types forward declaration iostream : input and output stream classes iterator : various iterator types list : double linked list map : associative array structure memory : auto ptr class denition numeric : numeric functions queue : a queue structure (rst in, rst out) rope : rope class denition set : a set structure (in the mathematical way) slist : slist class denition sstream : stringbuf class denition stack : a stack structure (rst in, last out) stdexcept : standard exceptions string : string class denition 13

The C++ STL

strstream : string stream class denition utility : utility classes valarray : valarray class denition vector : equivalent of an array structure with an automatic reallocation

1.6

STL algorithms

The C++ STL provide an entire set of algorithms : from searching to sorting, the most used algorithms are included with an optimized implementation. Those algorithms are mostly used on STL containers. Thus, you can create your own container and apply the STL algorithms on it if you follow a few rules in your implementation.

1.7

STL containers

A container is an object that contains objects. Containers are data structures useful in many cases. There is some algorithms which performances depend only of the container used in the implementation. The C++ STL oers many containers. Each container grants fast operations of one type : fast access to the beginning and the end, fast random access, etc.

1.8

Iterators

An iterator is something pretty much like a pointer on an element of a container. Exactly, an iterator is an object which oers the same operations as a C pointer : ++, != and =. For example, consider the use of an array of int. If you use the following code to display all the array elements : int array[10]; int* p; for(p = &array[0]; p != &array[10]; p++) { cout << *p << endl; } With a STL container (say vector ) and an iterator you can write : vector<int> array; vector<int>::iterator it; for(it = array.begin(); it != array.end(); it++) { cout << *it << endl; } Thus, iterators allow you to use all STL containers the same way.

14

The C++ STL

1.9

Allocators

An allocator is an object used to allocate and deallocate memory. The allocators encapsulate these operations. The STL oers standard allocators but it may be interesting to implement your own. For example, you can implement your own allocator for allocating small objects, because the standard ones are not very eective in allocating small objects.

1.10

Adaptors

An adaptor is a class that uses another underlying class to work. An adaptor usually takes a class name in a template parameter. Then, it can use any class that provides the functions called by the adaptor.

1.11

Functors

A functor is an object used like a function. The class implements the operator(). Then you can use the object as if it was a function. For example : #include <iostream> class succ functor { public: int operator()(int an int) { return an int + 1; } }; int main(void) { int i = 12; succ functor succ; /* Displays 13 */ cout << succ(i) << endl; } There is a great terminology problem with the word functor. Firstly, function object is often used for objects that are used like functions and functor for both classes that are used like functions and their objects. So, often you will see the term function object instead of functor. Secondly, many C++ users prefer the term function object to functor, because functor has a dened meaning in mathematics, and it is not exactly the same in C++. In spite of this problem, the word functor will be used in this documentation : there is nothing in this documentation concerning the mathematical functors, so you can be sure that the word functor means C++ functor.

15

Part II

Iterators

16

Chapter 1

What is an iterator ?
An iterator is an abstraction used to represent a pointer on a sequence. It means that you can access sequence elements by using iterators without knowing anything about element type or position. You can use anything as an iterator. But, usually, to be called an iterator an object implements three basic operations : indirection (done by operator * and ->) incrementation (operator ++) comparison (operator == and ! =)

1.1

Why are iterators so important ?

Iterators are important because they provide an abstraction that makes all containers identical when viewed from the outside. For example, almost all STL algorithm use iterators to work using the same manner on all container avour.

1.2

Iterators example

Usually, the rst time you see a C++ code part using an iterator you cannot miss the huge word used to declare the iterator. Although it seems complicated at rst sight, it is really very simple. You just have to remember that iterator types is often contained within a class declaration. For example, if you want to create an iterator on a vector of int you can use : vector<int>::iterator it; It means : I want to use the iterator type declared within the class vector . Now you can use your iterator to go across the vector by using operator++ and you can display an element by dereferencing the iterator : vector<int> my vector; vector<int>::iterator it; for(it = my vector.begin(); it != my vector.end(); it++) { cout << *it << endl; 17

The C++ STL

} /* Another way to write it */ it = my vector.begin(); while(it != my vector.end()) { cout << *it << endl; it++; } This can be read : From the beginning of my vector and while the iterator does not reach the end, send the current element on cout.

1.3

What are the dierent types of iterator ?

There are dierent types of iterator. Each type provides a dierent set of access operations. All iterator types provide the operations ==, != and =. In the following array it and it2 are iterators and x is a variable pointed to by an iterator. n is a variable of type int : Operations provided by the dierent types of iterator are : Iterator type Operations provided InputIterator ++it, it++, x = *it OutputIterator ++it, it++, *it = x ForwardIterator ++it, it++, x = *it, *it = x BidirectionalIterator ++it, it++, it, it, x = *it, *it = x RandomAccessIterator ++it, it++, it, it, x = *it, *it = x, it + n, it - n, it += n, it -= n, it < it2, it > it2, it <= it2, it >= it2

18

Part III

Algorithms

19

Chapter 1

Introduction on STL algorithms


The STL library provides a complete set of algorithms that can be used to avoid painful reimplementations. All algorithms can be used by including the header <algorithm>.

20

Chapter 2

Comparing algorithms
2.1 Lexicographical compare

Lexicographical algorithms use operator< to compare iterators of two sequences /* Compares two sequences. When a dierence is found, returns true if the rst sequence is less than the second (using operator< to compare iterators) or false in the other case . If the sequences are the same it returns false. */ template <class InputIter1, class InputIter2> bool lexicographical compare(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2); /* Uses comp instead of operator< */ template <class InputIter1, class InputIter2, class Compare> bool lexicographical compare(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, Compare comp); /* This one uses memcmp */ bool lexicographical compare(const unsigned char* rst1, const unsigned char* last1, const unsigned char* rst2, const unsigned char* last2); /* Calls the previous function */ bool lexicographical compare(const char* rst1, const char* last1, const char* rst2, const char* last2); /* This function is not part of the C++ standard. It returns -1 if the rst sequence is less than the second. 0 if they are the same. Or 1 in the other case. */ template <class InputIter1, class InputIter2> int lexicographical compare 3way(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2);

21

The C++ STL

2.2

Equal and mismatch

Those algorithms can be used to compare two sequences : /* Returns the rst identical iterators (using operator== of the iterator) */ template <class InputIter1, class InputIter2> pair<InputIter1, InputIter2> mismatch(InputIter1 rst1, InputIter1 last1, InputIter2 rst2); /* Uses bin pred instead of operator== */ template <class InputIter1, class InputIter2> pair<InputIter1, InputIter2> mismatch(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, BinaryPredicate bin pred); /* Returns true if sequences are equal or false either (using operator== of the iterator) */ template <class InputIter1, class InputIter2> bool equal(InputIter1 rst1, InputIter1 last1, InputIter2 rst2); /* Uses bin pred instead of operator== */ template <class InputIter1, class InputIter2> bool equal(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, BinaryPredicate bin pred);

22

Chapter 3

Copying algorithms
3.1 copy

The copy function copies a sequence to another location, this new sequence will start at result : /* Returns an iterator on the element following the last copied element */ template <class InputIter, class OutputIter> OutputIter copy(InputIter rst, InputIter last, OutputIter result);

3.2

copy backward

This function is the same as copy, but the copy is made from the end of the source sequence to its beginning : /* Returns an iterator on the element following the last copied element */ template <class BidirectionalIter1, class BidirectionalIter2> BidirectionalIter2 copy backward(BidirectionalIter1 rst, BidirectionalIter1 last, BidirectionalIter2 result);

3.3

copy n

This function is not part of the C++ standard, it copies n elements from the source sequence to another sequence : /* Returns a pair composed with the element following the last element in the source sequence and the element following the last in the destination sequence */ template <class InputIter, class Size, class OutputIter> pair<InputIter, OutputIter> copy n(InputIter rst, Size count, OutputIter result);

23

Chapter 4

Counting algorithms
4.1 count

The count algorithm counts the element in a range equals to a value using operator== : /* Return the number of element equals to value using T::operator== */ template <class InputIter, class T> iterator traits<InputIter>::dierence type count(InputIter rst, InputIter last, const T& value);

4.2

count if

The count if algorithm counts the element in a range using a predicate instead of operator== : /* Return the number of element equals to value using pred */ template <class InputIter, class Predicate> iterator traits<InputIter>::dierence type count if(InputIter rst, InputIter last, Predicate pred);

24

Chapter 5

Filling algorithms
5.1 ll

This algorithm lls a range with a given value by using operator= : template <class ForwardIter, class T> void ll(ForwardIter rst, ForwardIter last, const T& value);

5.2

ll n

This algorithms does the same thing that ll but lls n elements : /* Returns an iterator on the last lled element */ template <class OutputIter, class Size, class T> OutputIter ll n(OutputIter rst, Size n, const T& value);

25

Chapter 6

for each
6.1 for each

This algorithm applies a function to every element of a range : /* f will be applied to each element. This function returns f */ template <class InputIter, class Function> Function for each(InputIter rst, InputIter last, Function f);

26

Chapter 7

generate
7.1 generate

This algorithm uses a generator to generate each element of a range : /* Uses operator= of the element contained in the range to set elements. gen is called by simply using gen() */ template <class ForwardIter, class Generator> void generate(ForwardIter rst, ForwardIter last, Generator gen);

7.2

generate n

This algorithm does the same thing that generate but with n elements after the rst : /* Returns an iterator on the last element generated */ template <class OutputIter, class Size, class Generator> OutputIter generate n(OutputIter rst, Size n, Generator gen);

27

Chapter 8

Heap algorithms
All heap algorithms work on a range assumed to be a heap created by make heap. A heap is a particular way of ordering elements. The rst element is the greatest and the last is the lowest. Adding and deleting element from a heap is done in a logarithmic time. Sorting a heap by using the sort heap function is done in N log (N ) in the worst case (where N is the number of elements in the heap).

8.1

push heap

push heap adds an element to a heap. The element added is *(last - 1). /* Uses operator< to compare elements */ template <class RandomAccessIterator> void push heap(RandomAccessIterator rst, RandomAccessIterator last); /* Uses comp instead of operator< to compare elements */ template <class RandomAccessIterator, class Compare> void push heap(RandomAccessIterator rst, RandomAccessIterator last, Compare comp);

8.2

pop heap

This function removes the greatest element from the heap (the rst element). /* Uses operator< to compare elements */ template <class RandomAccessIterator> void pop heap(RandomAccessIterator rst, RandomAccessIterator last); /* Uses comp instead of operator< */ template <class RandomAccessIterator, class Compare> void pop heap(RandomAccessIterator rst, RandomAccessIterator last, Compare comp);

28

The C++ STL

8.3

make heap

This function reorders the elements between rst and last in order to create a heap. /* Uses operator< to compare elements */ template <class RandomAccessIterator> void make heap(RandomAccessIterator rst, RandomAccessIterator last); /* Uses comp instead of operator< */ template <class RandomAccessIterator, class Compare> void make heap(RandomAccessIterator rst, RandomAccessIterator last, Compare comp);

8.4

sort heap

This function uses a heap to create a sorted range. It does the same thing than doing a pop heap on the heap until no more element is in the heap. /* Uses operator< to compare elements */ template <class RandomAccessIterator> void sort heap(RandomAccessIterator rst, RandomAccessIterator last); /* Uses comp instead of operator< */ template <class RandomAccessIterator, class Compare> void sort heap(RandomAccessIterator rst, RandomAccessIterator last, Compare comp);

8.5

is heap

This function checks if a range is a heap or not. It returns true if the range is a heap or false otherwise. template <class RandomAccessIter> bool is heap(RandomAccessIter rst, RandomAccessIter last); template <class RandomAccessIter, class StrictWeakOrdering> bool is heap(RandomAccessIter rst, RandomAccessIter last, StrictWeakOrdering comp);

29

Chapter 9

Merging algorithms
9.1 Merge

The merge function merges two ranges and returns an iterator on the rst element of the merged range. It assumes that the two ranges are sorted. The output range is sorted. /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2, class OutputIter> OutputIter merge(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result); /* Uses comp instead of operator< */ template <class InputIter1, class InputIter2, class OutputIter, class Compare> OutputIter merge(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result, Compare comp);

9.2

Inplace merge

This functions takes two parts of a range, each one sorted, and returns a new sorted range by merging the two parts. /* Uses operator< to compare elements */ template <class BidirectionalIter> void inplace merge(BidirectionalIter rst, BidirectionalIter middle, BidirectionalIter last); /* Uses comp instead of operator< */ template <class BidirectionalIter, class Compare> void inplace merge(BidirectionalIter rst, BidirectionalIter middle, BidirectionalIter last, Compare comp);

30

Chapter 10

Minimum and maximum


10.1 Min

This function returns the lowest of its two arguments. template <class T> const T& min(const T& a, const T& b); /* Uses comp to compare a and b */ template <class T, class Compare> const T& min(const T& a, const T& b, Compare comp);

10.2

Max

This function returns the greatest of its two arguments. template <class T> const T& max(const T& a, const T& b); /* Uses comp to compare a and b */ template <class T, class Compare> const T& max(const T& a, const T& b, Compare comp);

10.3

Min element

This function returns the lowest element of a range. template <class ForwardIter> ForwardIter min element(ForwardIter rst, ForwardIter last); /* Uses comp to compare elements of the range */ template <class ForwardIter, class Compare> ForwardIter min element(ForwardIter rst, ForwardIter last, Compare comp);

10.4

Max element

This function returns the greatest element of a range.

31

The C++ STL

template <class ForwardIter> ForwardIter max element(ForwardIter rst, ForwardIter last); /* Uses comp to compare elements of the range */ template <class ForwardIter, class Compare> ForwardIter max element(ForwardIter rst, ForwardIter last, Compare comp);

32

Chapter 11

Mismatch
11.1 Mismatch

This function crosses two ranges and stops when the two ranges dier. It returns a pair containing two iterators on the diering elements. /* Uses operator== to compare elements */ template <class InputIter1, class InputIter2> pair<InputIter1, InputIter2> mismatch(InputIter1 rst1, InputIter1 last1, InputIter2 rst2); /* Uses pred instead of operator== */ template <class InputIter1, class InputIter2, class BinaryPredicate> pair<InputIter1, InputIter2> mismatch(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, BinaryPredicate pred);

33

Chapter 12

nth element
12.1 Nth element

This function sorts the elements between the rst and the nth element in ascendant order. The elements between the nth element and the last are not sorted, however no element in between the nth and the last is smaller than an element between the rst and the nth element. /* Uses operator< to compare elements */ template <class RandomAccessIter> void nth element(RandomAccessIter rst, RandomAccessIter nth, RandomAccessIter last); /* Uses comp to compare elements */ template <class RandomAccessIter, class Compare> void nth element(RandomAccessIter rst, RandomAccessIter nth, RandomAccessIter last, Compare comp);

34

Chapter 13

Numeric algorithms
13.1 Accumulate

This function does a sum of all elements in a range and add a given value to it. The sum may be replaced by a given binary operation. The function returns the sum : template <class InputIterator, class T> T accumulate(InputIterator rst, InputIterator last, T init); /* Makes a bin op instead of a sum */ template <class InputIterator, class T, class BinaryOperation> T accumulate(InputIterator rst, InputIterator last, T init, BinaryOperation bin op);

13.2

Adjacent dierence

This function makes the dierence of adjacent elements between rst and last, then stores the result, starting at result. Thus, *result is equal to *rst, *(result + 1) is equal to *(rst + 1) - *rst and so on. The function returns an iterator on the element following the last : template <class InputIterator, class OutputIterator> OutputIterator adjacent dierence(InputIterator rst, InputIterator last, OutputIterator result); /* Uses bin op instead of a dierence */ template <class InputIterator, class OutputIterator, class BinaryOperation> OutputIterator adjacent dierence(InputIterator rst, InputIterator last, OutputIterator result, BinaryOperation bin op);

13.3

Inner product

This function computes the inner product of two ranges and adds the result to the init value. Inner product is the sum of the product of all elements at the same position in each range. For two ranges of size 3, say rst1 and rst2 the inner product is : [f irst1] [f irst2] + [(f irst1 + 1)] [(f irst2 + 1)] + [(f irst1 + 2)] [(f irst2 + 2)]

35

The C++ STL

The function returns the result of the inner product : template <class InputIterator1, class InputIterator2, class T> T inner product(InputIterator1 rst1, InputIterator1 last1, InputIterator2 rst2, T init); /* Uses bin op1 instead of a sum and bin op2 instead of a product */ template <class InputIterator1, class InputIterator2, class T, class BinaryOperation1, class BinaryOperation2> T inner product(InputIterator1 rst1, InputIterator1 last1, InputIterator2 rst2, T init, BinaryOperation1 bin op1, BinaryOperation2 bin op2);

13.4

Partial sum

This function goes through a range and sums all elements between the current and the rst. Here is an example : #include <algo.h> #include <iostream> int main(int argc, char* argv[]) { int v1[] = { 1, 1, 1, 1, 1, 1}; int v2[] = { 0, 0, 0, 0, 0, 0 }; partial sum(v1, v1 + 6, v2); /* Displays : 123456 */ for(int i = 0; i < 6; i++) { cout << v2[i] << ; } cout << endl; } The function returns an iterator on the element following the last : template <class InputIterator, class OutputIterator> OutputIterator partial sum(InputIterator rst, InputIterator last, OutputIterator result); /* Does a bin op instead of a sum */ template <class InputIterator, class OutputIterator, class BinaryOperation> OutputIterator partial sum(InputIterator rst, InputIterator last, OutputIterator result, BinaryOperation bin op);

13.5

Power

This function raises a value to a given power :

36

The C++ STL

template <class T, class Integer> T power(T x, Integer n); /* Uses oper instead of a power */ template <class T, class Integer, class MonoidOperation> T power(T x, Integer n, MonoidOperation oper);

37

Chapter 14

partition and stable partition


14.1 partition

This function cuts a range in two parts : all elements in the rst part satisfy a predicate and elements in the second part doesnt. This function returns the rst element that doesnt satisfy the predicate. After a call to partition, relative order between elements may be changed. template <class ForwardIter, class Predicate> ForwardIter partition(ForwardIter rst, ForwardIter last, Predicate pred);

14.2

stable partition

This function does the same thing that partition, except that the relative order between elements is kept. Thus, stable partition uses more computation time than partition. template <class ForwardIter, class Predicate> ForwardIter stable partition(ForwardIter rst, ForwardIter last, Predicate pred);

38

Chapter 15

Randomizing algorithms
15.1 Random shue

This function reorders the elements of a range by putting them at random places : template <class RandomAccessIter> void random shue(RandomAccessIter rst, RandomAccessIter last); /* Uses rand instead of the default random number generator */ template <class RandomAccessIter, class RandomNumberGenerator> void random shue(RandomAccessIter rst, RandomAccessIter last, RandomNumberGenerator& rand);

39

Chapter 16

Removing algorithms
16.1 remove

This function removes from a range all elements equal to a given value : /* Returns the last removed element, or rst if rst and last are equal. Uses operator!= to compare elements */ ForwardIter remove(ForwardIter rst, ForwardIter last, const T& value);

16.2

remove if

This function removes all elements from a range that returns true using a given predicate. template <class ForwardIter, class Predicate> ForwardIter remove if(ForwardIter rst, ForwardIter last, Predicate pred);

16.3

remove copy

This function copies all elements not equal to a given value to result : /* Returns an iterator on element following the last element of result */ template <class InputIter, class OutputIter, class Tp> OutputIter remove copy(InputIter rst, InputIter last, OutputIter result, const T& value);

16.4

remove copy if

This function copies all elements that doesnt verify the predicate pred into result : /* Returns an iterator on element following the last element of result */ template <class InputIter, class OutputIter, class Predicate>

40

The C++ STL

OutputIter remove copy if(InputIter rst, InputIter last, OutputIter result, Predicate pred);

41

Chapter 17

Replacing algorithms
17.1 replace

This function replaces all value equal to old value (using operator== of the iterator) by the value new value in a range. The replacement is done by using operator= of the iterator. template <class ForwardIter, class T> void replace(ForwardIter rst, ForwardIter last, const T& old value, const T& new value);

17.2

replace if

This function does the same thing that the replace function but uses the pred predicate instead of operator== : template <class ForwardIter, class Predicate, class T> void replace if(ForwardIter rst, ForwardIter last, Predicate pred, const T& new value);

17.3

replace copy

This function makes a copy of a range and replaces all old value values by the value new value into it. It uses operator= to make the copy and operator== to compare elements. /* Returns an iterator on the element following the last copied element */ template <class InputIter, class OutputIter, class Tp> OutputIter replace copy(InputIter rst, InputIter last, OutputIter result, const T& old value, const T& new value);

17.4

replace copy if

This function does the same thing that replace copy but uses the predicate pred instead of operator== to compare elements :

42

The C++ STL

template <class Iterator, class OutputIter, class Predicate, class T> OutputIter replace copy if(Iterator rst, Iterator last, OutputIter result, Predicate pred, const T& new value);

43

Chapter 18

Reversing and rotating algorithms


18.1 reverse

This function reverses a range : template <class BidirectionalIter> void reverse(BidirectionalIter rst, BidirectionalIter last);

18.2

reverse copy

This function makes a reversed copy of a range. It returns an iterator on the element following the last element copied : /* Returns an iterator on the element following the last copied element */ template <class BidirectionalIter, class OutputIter> OutputIter reverse copy(BidirectionalIter rst, BidirectionalIter last, OutputIter result);

18.3

rotate

This function rotates a sequence. It means the sequence will start at the element in the middle of the source sequence and the last element will be followed by the rst (it appends the element between the rst and the middle element to the elements between the middle and the last element). template <class ForwardIter> ForwardIter rotate(ForwardIter rst, ForwardIter middle, ForwardIter last);

18.4

rotate copy

This function make a rotated copy of a sequence. It means the resulting sequence will start at the element in the middle of the source sequence and the last element will be followed by the rst (it

44

The C++ STL

appends the element between the rst and the middle element to the elements between the middle and the last element). /* Returns an iterator on the element following the last copied element */ template <class ForwardIter, class OutputIter> OutputIter rotate copy(ForwardIter rst, ForwardIter middle, ForwardIter last, OutputIter result);

45

Chapter 19

Searching algorithms
19.1 adjacent nd

adjacent nd searches two adjacent elements in a range that are equal (or satisfy a binary predicate) and returns an iterator on the rst of those two elements. If such elements do not exist, it returns an iterator on the element following the last (that is, it returns last ) : /* Uses operator== to compare elements */ template <class ForwardIter> ForwardIter adjacent nd(ForwardIter rst, ForwardIter last); /* Calls bin pred instead of operator== */ template <class ForwardIter, class BinaryPredicate> ForwardIter adjacent nd(ForwardIter rst, ForwardIter last, BinaryPredicate bin pred);

19.2

binary search

binary search searches the element val in an ordered range and returns true if it is in the range or false otherwise : /* Uses operator< to compare elements */ template <class ForwardIter, class T> bool binary search(ForwardIter rst, ForwardIter last, const T& val); /* Uses comp instead of operator< */ template <class ForwardIter, class T, class Compare> bool binary search(ForwardIter rst, ForwardIter last, const T& val, Compare comp);

19.3

equal range

This function returns the lower bound and the upper bound of a range where a new value can be inserted without misordering the elements between rst and last :

46

The C++ STL

/* Uses operator< to compare elements */ template <class ForwardIter, class T> pair<ForwardIter, ForwardIter> equal range(ForwardIter rst, ForwardIter last, const T& val); /* Uses comp instead of operator< */ template <class ForwardIter, class T, class Compare> pair<ForwardIter, ForwardIter> equal range(ForwardIter rst, ForwardIter last, const T& val, Compare comp);

19.4

nd

This function searches an element in a range and returns an iterator on it. If the element wasnt found it returns an iterator on the element following the last (that is, the last iterator) : /* Uses operator!= to compare elements */ template <class InputIter, class T> InputIter nd(InputIter rst, InputIter last, const T& val); /* Uses pred instead of operator!= */ template <class InputIter, class Predicate> InputIter nd if(InputIter rst, InputIter last, Predicate pred);

19.5

nd end

This function nds the last subsequence (elements between rst2 and last2 ) contained into a sequence (elements between rst1 and last1 ). It returns an iterator on the rst element of the last occurence of the subsequence. /* Uses operator== to compare elements */ template <class ForwardIter1, class ForwardIter2> ForwardIter1 nd end(ForwardIter1 rst1, ForwardIter1 last1, ForwardIter2 rst2, ForwardIter2 last2); /* Uses comp instead of operator== */ template <class ForwardIter1, class ForwardIter2, class BinaryPredicate> ForwardIter1 nd end(ForwardIter1 rst1, ForwardIter1 last1, ForwardIter2 rst2, ForwardIter2 last2, BinaryPredicate comp);

19.6

nd rst of

This function searches any element of a sequence (elements between rst2 and last2 ) in another sequence (between rst and last ). It returns an iterator on the element found in the sequence (between rst1 and last1 ) or an iterator on the element following the last (that is, last1 ) if none of the elements was found in the range.

47

The C++ STL

/* Uses operator== to compare elements */ template <class InputIter, class ForwardIter> InputIter nd rst of(InputIter rst1, InputIter last1, ForwardIter rst2, ForwardIter last2); /* Uses comp instead of operator== */ template <class InputIter, class ForwardIter, class BinaryPredicate> InputIter nd rst of(InputIter rst1, InputIter last1, ForwardIter rst2, ForwardIter last2, BinaryPredicate comp);

19.7

lower bound

This function returns the lower bound of a range. That is, the rst position where a new value can be inserted without misordering the elements between rst and last : /* Uses operator< to compare elements */ template <class ForwardIter, class T> ForwardIter lower bound(ForwardIter rst, ForwardIter last, const T& val); /* Uses comp instead of operator< */ template <class ForwardIter, class T, class Compare> ForwardIter lower bound(ForwardIter rst, ForwardIter last, const T& val, Compare comp);

19.8

search

This function searches a subsequence (elements from rst2 to last2 ) into sequence (elements from rst1 to last1 ). This function returns an iterator on the rst element of the subsequence found in the sequence. If the subsequence wasnt found, last1 is returned : /* Uses operator== to compare elements */ template <class ForwardIter1, class ForwardIter2> ForwardIter1 search(ForwardIter1 rst1, ForwardIter1 last1, ForwardIter2 rst2, ForwardIter2 last2); /* Uses predicate instead of operator== */ template <class ForwardIter1, class ForwardIter2, class BinaryPred> ForwardIter1 search(ForwardIter1 rst1, ForwardIter1 last1, ForwardIter2 rst2, ForwardIter2 last2, BinaryPred predicate);

19.9

search n

This function searches count identical consecutive elements in a sequence, all equal to val :

48

The C++ STL

/* Uses operator!= to compare elements */ template <class ForwardIter, class Integer, class T> ForwardIter search n(ForwardIter rst, ForwardIter last, Integer count, const T& val); /* Uses binary pred instead of operator!= */ template <class ForwardIter, class Integer, class T, class BinaryPred> ForwardIter search n(ForwardIter rst, ForwardIter last, Integer count, const T& val, BinaryPred binary pred);

19.10

upper bound

This function returns the upper bound of a range. That is, the last position where a new value can be inserted without misordering the elements between rst and last : /* Uses operator< to compare elements */ template <class ForwardIter, class T> ForwardIter upper bound(ForwardIter rst, ForwardIter last, const T& val); /* Uses comp instead of operator< */ template <class ForwardIter, class T, class Compare> ForwardIter upper bound(ForwardIter rst, ForwardIter last, const T& val, Compare comp);

49

Chapter 20

Set algorithms
All set operations assume that the used ranges are sorted.

20.1

includes

This functions returns true if the elements between rst2 and last2 are included between rst1 and last1, or false otherwise : /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2> bool includes(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2); /* Uses comp instead of operator< */ template <class InputIter1, class InputIter2, class Compare> bool includes(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, Compare comp);

20.2

set dierence

This function creates the set dierence of two sequences. It returns an iterator on the element following the last of the build sequence : /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2, class OutputIter> OutputIter set dierence(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result); /* Uses comp instead of operator */ template <class InputIter1, class InputIter2, class OutputIter, class Compare> OutputIter set dierence(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result, Compare comp);

50

The C++ STL

20.3

set intersection

This function creates the set intersection of two sequences. It returns an iterator on the element following the last of the build sequence : /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2, class OutputIter> OutputIter set intersection(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result); /* Uses comp instead of operator */ template <class InputIter1, class InputIter2, class OutputIter, class Compare> OutputIter set intersection(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result, Compare comp);

20.4

set symmetric dierence

This function creates the set symmetric dierenct of two sequences. It returns an iterator on the element following the last of the build sequence. The symmetric dierence of two sets A and B is the union of (A B ) and (B A). /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2, class OutputIter> OutputIter set symmetric dierence(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result); /* Uses comp instead of operator */ template <class InputIter1, class InputIter2, class OutputIter, class Compare> OutputIter set symmetric dierence(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result, Compare comp);

20.5

set union

This function creates the set union of two sequences. It returns an iterator on the element following the last of the build sequence : /* Uses operator< to compare elements */ template <class InputIter1, class InputIter2, class OutputIter> OutputIter set union(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, InputIter2 last2, OutputIter result); /* Uses comp instead of operator */ template <class InputIter1, class InputIter2, class OutputIter, class Compare> OutputIter set union(InputIter1 rst1, InputIter1 last1,

51

The C++ STL

InputIter2 rst2, InputIter2 last2, OutputIter result, Compare comp);

52

Chapter 21

Sorting algorithms
21.1 sort

This function sorts a range in ascending order : /* Uses operator< to compare elements */ template <class RandomAccessIter> void sort(RandomAccessIter rst, RandomAccessIter last); /* Uses comp to compare elements */ template <class RandomAccessIter, class Compare> void sort(RandomAccessIter rst, RandomAccessIter last, Compare comp);

21.2

partial sort copy

This function partially sort a range and put the result in a new range (to know what means partially sort see partial sort on page 54). The number of elements copied is the minimum of result last - result rst and last - rst. It returns an iterator on the element following the last element copied. /* Uses operator< to compare elements */ template <class InputIter, class RandomAccessIter> RandomAccessIter partial sort copy(InputIter rst, InputIter last, RandomAccessIter result rst, RandomAccessIter result last); /* Uses comp to compare elements */ template <class InputIter, class RandomAccessIter, class Compare> RandomAccessIter partial sort copy(InputIter rst, InputIter last, RandomAccessIter result rst, RandomAccessIter result last, Compare comp);

53

The C++ STL

21.3

partial sort

This function partially sorts a range. After calling this function, the elements between rst and middle will be sorted and the elements between middle and last will be in an unspecied order. That is, this function sorts a range of size middle - rst by taking its elements between rst and last : /* Uses operator< to compare elements */ template <class RandomAccessIter> void partial sort(RandomAccessIter rst, RandomAccessIter middle, RandomAccessIter last); /* Uses comp to compare elements */ template <class RandomAccessIter, class Compare> void partial sort(RandomAccessIter rst, RandomAccessIter middle, RandomAccessIter last, Compare comp);

21.4

stable sort

This function sorts a range (like the sort function) but keeps the order of equivalent elements : /* Uses operator< to compare elements */ template <class RandomAccessIter> void stable sort(RandomAccessIter rst, RandomAccessIter last); /* Uses comp to compare elements */ template <class RandomAccessIter, class Compare> void stable sort(RandomAccessIter rst, RandomAccessIter last, Compare comp);

54

Chapter 22

Swaping algorithms
22.1 iter swap

This functions swaps two values by taking iterators on them : /* Equivalent to swap(*a, *b) */ template <class ForwardIter1, class ForwardIter2> void iter swap(ForwardIter1 a, ForwardIter2 b);

22.2

swap

This functions swaps the value of its two parameters : /* Uses T::operator= to swap elements */ template <class T> void swap(T& a, T& b);

22.3

swap ranges

This function swaps the elements of two sequence, that is each element at a position in the rst sequence is replaced by the element at the same position in the second sequence and vice-versa : /* Returns on the element following the last of the second sequence */ template <class ForwardIter1, class ForwardIter2> ForwardIter2 swap ranges(ForwardIter1 rst1, ForwardIter1 last1, ForwardIter2 rst2);

55

Chapter 23

transform
23.1 Transform

This algorithm applies a function to each element of a sequence and puts the result starting at the result iterator : template <class InputIter, class OutputIter, class UnaryOperation> OutputIter transform(InputIter rst, InputIter last, OutputIter result, UnaryOperation oper); /* Applies a binary operation with in rst parameter an element from the rst sequence and in second parameter an element from the second sequence */ template <class InputIter1, class InputIter2, class OutputIter, class BinaryOperation> OutputIter transform(InputIter1 rst1, InputIter1 last1, InputIter2 rst2, OutputIter result, BinaryOperation bin op);

56

Chapter 24

unique
24.1 unique

This function transforms a sequence such as each duplicate consecutive elements become a unique element : /* Returns an iterator on the element following the last (that is last) (uses operator!= to compare elements) */ template <class ForwardIter> ForwardIter unique(ForwardIter rst, ForwardIter last); /* Uses pred to compare element */ template <class ForwardIter, class BinaryPredicate> ForwardIter unique(ForwardIter rst, ForwardIter last, BinaryPredicate binary pred);

24.2

unique copy

This function copies a sequence such as each duplicate consecutive elements become a unique element. /* Returns an iterator on the element following the last (uses operator!= to compare elements) */ template <class InputIter, class OutputIter> OutputIter unique copy(InputIter rst, InputIter last, OutputIter result); /* Uses bin pred to compare elements */ template <class InputIter, class OutputIter, class BinaryPredicate> OutputIter unique copy(InputIter rst, InputIter last, OutputIter result, BinaryPredicate bin pred);

57

Part IV

Sequence Containers

58

Chapter 1

Introduction on STL containers


1.1 What is a container ?

A container is a structure designed to contain other objects. In the C++ case, containers contain objects of the same type. This type is xed when the container is rst created and cannot be changed after. What is so interesting about STL containers ? The thing is that all STL containers have the same interface (only a few functions are specic to a type of container). Moreover, all containers are optimized for the type of operation they were created for. All the containers are dened in the namespace std. Note that STL containers take an object by reference when adding it to them. It means that the type used your container must have a public copy constructor.

1.2

What is an associative container ?

An associative container is a template class with two types : the type of the keys and the type of the values. Each value can be accessed using a unique key.

1.3

What is a container adaptor ?

A container adaptor is a template class which use a sequence container (vector, list or deque ) to create a new type of container without implementing new containers. The container adaptors only use member function to access their content. They do not have iterators like sequence containers.

59

Chapter 2

Bit vector : <bvector.h>


The bit vector is used like a vector<bool>, nevertheless, the bit vector is optimized in space : it requires only one bit per element. If the header <bvector.h> does not exist on your system, it means that the class is implemented by specializing the vector class. All systems does not oer support for partially specialized template, so some compiler still use the <bvector.h> header.

2.1

Bvector types

A bvector container has the following types : /* Type typedef typedef typedef of the elements */ bool value type; bool* pointer; const bool* const pointer;

/* Iterator types are implementation dependant */ typedef Bit iterator iterator; typedef const Bit const iterator const iterator; typedef Bit reference reference; typedef Bit const reference const reference; typedef reverse iterator<const iterator> const reverse iterator; typedef reverse iterator<iterator> reverse iterator; /* This is implementation dependant */ typedef size t size type; typedef ptrdi t dierence type; typedef typename Bvector base::allocator type allocator type;

2.2

Bvector constructors

A bvector container has the following constructors : explicit bit vector(const allocator type& a = allocator type()); /* Inits the bit vector with n copies of the value */ bit vector(size type n, bool value, const allocator type& a = allocator type());

60

The C++ STL

/* Allocates n area of memory */ explicit bit vector(size type n); /* Copy constructor */ bit vector(const bit vector& x); /* rst and last are iterators on a sequence. The values between rst and last are copied in the new bit vector */ template <class InputIterator> bit vector(InputIterator rst, InputIterator last, const allocator type& a = allocator type());

2.3

Bvector destructor

A bvector container has the following destructor : bit vector();

2.4

Bvector operators

A bvector container has the following operators : /* Unchecked access */ reference operator[](size type n); /* Constant access */ const reference operator[](size type n) const; /* Copy operator */ bit vector& operator=(const bit vector& v); /* Compares two bit vectors using equal function */ bool operator==(const bit vector& x, const bit vector& y); /* Lexicographical compare between bit vectors */ bool operator<(const bit vector& x, const bit vector& y);

2.5

Bvector iterators

A bvector has the following iterators : /* Returns an iterator on the rst element */ iterator begin(); const iterator begin() const; /* Returns an iterator on the element following the last */ iterator end(); const iterator end() const;

61

The C++ STL

/* Returns an iterator on the last element */ reverse iterator rbegin(); const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ reverse iterator rend(); const reverse iterator rend() const;

2.6

Bvector size and capacity

A bvector size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this bit vector (based on the size of boolean type) */ size type max size() const; /* Number of allocated elements (initialized elements plus non initialized) */ size type capacity() const; /* Returns true if this bit vector contains no element, in this case begin() == end() */ bool empty() const; /* Tries to allocate more memory for n more elements. If n is less than or equal to capacity() this call does nothing */ void reserve(size type n); /* If the new size is less than the current size it erases element from the end to set the size to new size. If the new size is greater then the current size it inserts elements at the end (initialized with x value). */ void resize(size type new size, bool x = bool());

2.7

Accessing elements

Elements of a bvector can be accessed using those functions : /* Returns the rst element */ reference front(); /* Returns the rst element */ const reference front();

62

The C++ STL

/* Returns the last element */ reference back(); /* Returns the last element */ const reference back();

2.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Appends the element x at the end */ void push back(bool x); /* Appends a new unitialized element at the end */ void push back(); /* Inserts x after pos and return x position */ iterator insert(iterator pos, bool x); /* Adds a new non initialized element */ iterator insert(iterator pos); /* Inserts all the elements between rst and last immediatly after pos */ void insert(iterator pos, const iterator rst, const iterator last); /* Inserts n copies of x immediatly after pos */ void insert(iterator pos, size type n, bool x); /* Erases the last element */ void pop back(); /* Erases the element at pos. Returns the new element at pos */ iterator erase(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion */ iterator erase(iterator rst, iterator last); /* Equivalent to erase(begin(), end()) */ void clear();

2.9

Misc functions

The bvector class has those functions too : /* Destroys the content of this bit vector and replaces it by n copies of val */ void assign(size type n, bool val); /* Destroys the content of this bit vector

63

The C++ STL

and replaces it by the elements between rst and last */ template <class InputIterator> void assign(InputIterator rst, InputIterator last); /* Swaps the content of this bit vector with the content of x */ void swap(bit vector& x); /* Swaps the content of x and y */ void swap(bit vector& x, bit vector& y); /* Returns this bit vector allocator */ allocator type get allocator() const;

64

Chapter 3

Deque : <deque>
The deque container is pretty much like the vector container. It can be used like an array (any element given by his index can be accessed). Like vector, insertion and deletion are done in a constant time at the end of a deque. Unlike vector, the insertion and deletion of element at the beginning of a deque are done in a constant time. Operations on others position are done in linear time. In the following sections, we will consider a deque constructed with the template <T, A>. Where T is the value type of the deque and A is the allocator type. The allocator type is optionnal.

3.1

Deque types

A deque container has the following types : /* Type typedef typedef typedef of the elements */ T value type; value type* pointer; const value type* const pointer;

/* Iterator types are implementation dependant */ typedef value type* iterator; typedef const value type* const iterator; typedef value type& reference; typedef const value type& const reference; typedef reverse iterator<const iterator> const reverse iterator; typedef reverse iterator<iterator> reverse iterator; /* This is implementation dependant */ typedef size t size type; typedef ptrdi t dierence type; typedef typename Vector base::allocator type allocator type;

3.2

Deque constructors

A deque container has the following constructors :

65

The C++ STL

explicit deque(const allocator type& a = allocator type()); /* Copy constructor */ deque(const deque& x); /* Inits the deque with n copies of the value */ deque(size type n, const T& value, const allocator type& a = allocator type()); /* Allocates n area of memory */ explicit deque(size type n); /* rst and last are iterators on a sequence. The values between rst and last are copied in the new vector */ template <class InputIterator> deque(InputIterator rst, InputIterator last, const allocator type& a = allocator type());

3.3

Deque destructor

A deque container has the following destructor : deque();

3.4

Deque operators

A deque container has the following operators : /* Unchecked access */ reference operator[](size type n); /* Constant access */ const reference operator[](size type n) const; /* Copy operator */ deque<T, A>& operator=(const deque<T, A>& d); /* Compare two vectors using equal function */ bool operator==(const deque<T, A>& x, const deque<T, A>& y); bool operator!=(const deque<T, A>& x, const deque<T, A>& y); /* Lexicographical compare between vectors */ bool operator<(const deque<T, A>& x, const deque<T, A>& y);

3.5

Deque iterators

A deque has the following iterators :

66

The C++ STL

/* Returns an iterator on the rst element */ iterator begin(); const iterator begin() const; /* Returns an iterator on the element following the last */ iterator end(); const iterator end() const; /* Returns an iterator on the last element */ reverse iterator rbegin(); const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ reverse iterator rend(); const reverse iterator rend() const;

3.6

Deque size and capacity

A deque size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this deque (based on the size of elements type) */ size type max size() const; /* Returns true if this vector contains no element, in this case begin() == end() */ bool empty() const; /* If the new size is less than the current size it erases element from the end to set the size to new size. If the new size is greater then the current size it inserts elements at the end (initialized with x value). */ void resize(size type new size, const T& x); /* Calls resize(size type, value type()) */ void resize(size type new size);

3.7

Accessing elements

Elements of a deque can be accessed using those functions : /* Returns the rst element */ reference front(); /* Returns the rst element */ const reference front();

67

The C++ STL

/* Returns the last element */ reference back(); /* Returns the last element */ const reference back();

3.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Appends the element x at the end */ void push back(const T& x); /* Appends a new unitialized element at the end */ void push back(); /* Appends the element x at the beginning */ void push front(const value type& x); /* Appends a new unitialized element at the beginning */ void push front(); /* Inserts x after pos and return x position */ iterator insert(iterator pos, const T& x); /* Adds a new non initialized element */ iterator insert(iterator pos); /* Inserts all the elements between rst and last immediatly after pos */ void insert(iterator pos, const iterator rst, const iterator last); /* Inserts n copies of x immediatly after pos */ void insert(iterator pos, size type n, const T& x); /* Erases the last element */ void pop back(); /* Erases the rst element */ void pop front(); /* Erases the element at pos. Returns the new element at pos */ iterator erase(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion */ iterator erase(iterator rst, iterator last); /* Equivalent to erase(begin(), end()) */ void clear();

68

The C++ STL

3.9

Misc functions

The deque class has those functions too : /* Destroys the content of this deque and replaces it by n copies of val */ void assign(size type n, const T& val); /* Destroys the content of this deque and replaces it by the elements between rst and last */ template <class InputIterator> void assign(InputIterator rst, InputIterator last); /* Swaps the content of this deque with the content of x */ void swap(deque<T, A>& x); /* Swaps the content of x and y */ void swap(deque<T, A>& x, deque<T, A>& y); /* Returns this list allocator */ allocator type get allocator() const;

69

Chapter 4

List : <list>
The list container is a double linked list. For each element of the list, the rst link corresponds to the previous element and the second link corresponds to the next element. The list is circular, thus, the element following the last is the rst ; and the element preceding the rst is the last. The insertion and deletion in the list are done in constant time, no matter the position. In the following sections, we will consider a list constructed with the template <T, A>. Where T is the value type of the list and A is the allocator type. The allocator type is optionnal.

4.1

List types

A list container has the following types : /* Type typedef typedef typedef typedef typedef of the elements */ T value type; value type* pointer; const value type* const pointer; value type& reference; const value type& const reference;

/* Iterator types are implementation dependant */ typedef List iterator<T, T&, T*>* iterator; typedef List iterator<T, const T&, const T*> const iterator; typedef reverse iterator<const iterator> const reverse iterator; typedef reverse iterator<iterator> reverse iterator; /* Bidirectionnal iterators */ typedef reverse bidirectional iterator<const iterator, value type, const reference, dierence type> const reverse iterator; typedef reverse bidirectional iterator<iterator, value type, reference, dierence type> reverse iterator; /* This is implementation dependant */ typedef size t size type; typedef ptrdi t dierence type; typedef typename List base::allocator type allocator type;

70

The C++ STL

4.2

List constructors

A list container has the following constructors : explicit list(const allocator type& a = allocator type()); /* Inits the list with n copies of the value */ list(size type n, const T& value, const allocator type& a = allocator type()); /* Allocates n area of memory */ explicit list(size type n); /* Copy constructor */ list(const list<T, A>& x); /* rst and last are iterators on a sequence. The values between rst and last are copied in the new list */ template <class InputIterator> list(InputIterator rst, InputIterator last, const allocator type& a = allocator type());

4.3
list();

List destructor

A list container has the following destructor :

4.4

List operators

A list container has the following operators : /* Copy operator */ list<T, A>& operator=(const list<T, A>& l); /* Compares two lists */ bool operator==(const list<T, A>& x, const list<T, A>& y); /* Lexicographical compare between lists */ bool operator<(const list<T, A>& x, const list<T, A>& y);

4.5

List iterators

A list has the following iterators : /* Returns an iterator on the rst element */ iterator begin(); const iterator begin() const;

71

The C++ STL

/* Returns an iterator on the element following the last */ iterator end(); const iterator end() const; /* Returns an iterator on the last element */ reverse iterator rbegin(); const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ reverse iterator rend(); const reverse iterator rend() const;

4.6

List size and capacity

A list size and capacity can be checked and changed using those functions : /* The number of elements */ size type size() const; /* The largest possible size of this list (based on the size of elements type) */ size type max size() const; /* Returns true if this list contains no element, in this case begin() == end() */ bool empty() const; /* If the new size is less than the current size it erases element from the end to set the size to new size. If the new size is greater then the current size it inserts elements at the end (initialized with x value). */ void resize(size type new size, const T& x); /* Calls resize(size type, value type()) */ void resize(size type new size);

4.7

Accessing elements

Elements of a list can be accessed using those functions : /* Returns the rst element */ reference front(); /* Returns the rst element */ const reference front(); /* Returns the last element */ reference back(); /* Returns the last element */

72

The C++ STL

const reference back();

4.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Appends the element x at the end */ void push back(const T& x); /* Appends a new unitialized element at the end */ void push back(); /* Appends the element x at the beginning */ void push front(const value type& x); /* Appends a new unitialized element at the beginning */ void push front(); /* Inserts x after pos and return x position */ iterator insert(iterator pos, const T& x); /* Inserts all the elements between rst and last immediatly after pos */ void insert(iterator pos, const iterator rst, const iterator last); /* Inserts n copies of x immediatly after pos */ void insert(iterator pos, size type n, const T& x); /* Erases the last element */ void pop back(); /* Erases the rst element */ void pop front(); /* Erases the element at pos. Returns the new element at pos */ iterator erase(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion */ iterator erase(iterator rst, iterator last); /* Equivalent to erase(begin(), end()) */ void clear();

4.9

Misc functions

The list class has those functions too : /* Destroys the content of this list and replaces it by n copies of

73

The C++ STL

val */ void assign(size type n, const T& val); /* Destroys the content of this list and replaces it by the elements between rst and last */ template <class InputIterator> void assign(InputIterator rst, InputIterator last); /* Swaps the content of this list with the content of x */ void swap(list<T, A>& x); /* Swaps the content of x and y */ void swap(list<T, A>& x, list<T, A>& y); /* Returns this list allocator */ allocator type get allocator() const; /* Transfers all elements from x to this list, placing them at position pos */ void splice(iterator pos, list<T, A>& x); /* Transfers all elements in a list starting at position i to this list, starting at position pos. x is unused in many implementations */ void splice(iterator pos, list<T, A>& x, iterator i); /* Transfers all elements in a list starting at position rst stopping at last, to this list, starting at position pos. x is unused in many implementations */ void splice(iterator pos, list<T, A>& x, iterator rst, iterator last); /* Removes all elements from this list of value value. Uses operator== of type T */ void remove(const T& value); /* Removes all elements from this list who gives a positive result when passed to p */ template<class Pred> void remove if(Pred p); /* Deletes all element with the same value except one (generally the rst). Same elements are recognized using operator== of the type T) */ void unique(); /* Uses b instead of operator== */ template<class BinPred> void unique(BinPred b); /* Merges x with this. Both lists must be sorted. This function uses operator< of type T */ void merge(list<T, A>& x); 74

The C++ STL

/* Uses cmp instead of operator< */ void merge(list<T, A>& x, cmp); /* Reverses this list */ void reverse(); /* Sorts this list using operator< of type T */ void sort(); /* Uses cmp instead of operator< */ void sort(cmp);

75

Chapter 5

SList : <slist>
The slist container corresponds to a single linked list. Each element is linked to the next. Compared to list, which has a bidirectionnal iterator, slist has a forward iterator. Thus, if you do not need the fonctionnalities of a double linked list, you should use slist instead of list.

5.1

How to know if I should use list or slist ?

The main dierence between list slist is the time of function like insert and erase. If you need to work on element that are far from the beginning, all the slist must be crossed before nding the position to put the element at. Thus, if you need to work on position far from the beginning of the list you should use a list container.

5.2

Slist types

A slist container has the following types : /* Type typedef typedef typedef typedef typedef of the elements */ T value type; value type* pointer; const value type* const pointer; value type& reference; const value type& const reference;

/* Iterator types are implementation dependant */ typedef Slist iterator<T, T&, T*>* iterator; typedef Slist iterator<T, const T&, const T*> const iterator; /* This is implementation dependant */ typedef size t size type; typedef ptrdi t dierence type; typedef typename Slist base::allocator type allocator type;

5.3

Slist constructors

A slist container has the following constructors : 76

The C++ STL

explicit slist(const allocator type& a = allocator type()); /* Inits the slist with n copies of the value */ slist(size type n, const T& value, const allocator type& a = allocator type()); /* Allocates n area of memory */ explicit slist(size type n); /* Copy constructor */ slist(const slist<T, A>& x); /* rst and last are iterators on a sequence. The values between rst and last are copied in the new slist */ template <class InputIterator> slist(InputIterator rst, InputIterator last, const allocator type& a = allocator type());

5.4
slist();

Slist destructor

A slist container has the following destructor :

5.5

Slist operators

A slist container has the following operators : /* Copy operator */ slist<T, A>& operator=(const slist<T, A>& l); /* Compares two slists */ bool operator==(const slist<T, A>& x, const slist<T, A>& y); /* Lexicographical compare between slists */ bool operator<(const slist<T, A>& x, const slist<T, A>& y);

5.6

Slist iterators

A slist has the following iterators : /* Returns an iterator on the rst element */ iterator begin(); const iterator begin() const; /* Returns an iterator on the element following the last */ iterator end(); const iterator end() const;

77

The C++ STL

5.7

Slist size and capacity

A slist size and capacity can be checked and changed using those functions : /* The number of elements */ size type size() const; /* The largest possible size of this slist (based on the size of elements type) */ size type max size() const; /* Returns true if this slist contains no element, in this case begin() == end() */ bool empty() const; /* If the new size is less than the current size it erases element from the end to set the size to new size. If the new size is greater then the current size it inserts elements at the end (initialized with x value). */ void resize(size type new size, const T& x); /* Calls resize(size type, value type()) */ void resize(size type new size);

5.8

Accessing elements

Elements of a slist can be accessed using those functions : /* Returns the rst element */ reference front(); /* Returns the rst element */ const reference front(); /* Returns an iterator on the element preceding pos*/ iterator previous(const iterator pos); const iterator previous(const iterator pos);

5.9

Inserting and deleting elements

Insertion and deletion are provided by those functions :

78

The C++ STL

/* Appends the element x at the beginning */ void push front(const value type& x); /* Appends a new unitialized element at the beginning */ void push front(); /* Erases the rst element */ void pop front(); /* Returns an iterator on the element preceding pos */ iterator previous(const iterator pos); const iterator previous(const iterator pos); /* Inserts x after pos and returns x position */ iterator insert after(iterator pos, const value type& x); /* Inserts an unitialized element immediatly after pos and returns its position */ iterator insert after(iterator pos); /* Inserts n copies of x immediatly after pos */ void insert after(iterator pos, size type n, const value type& x); /* Inserts all the elements between rst and last immediatly after pos */ void insert after(iterator pos, InIter rst, InIter last); /* Inserts x after pos and returns x position Calls insert after */ iterator insert(iterator pos, const T& x); /* Inserts n copies of x immediatly after pos Calls insert after */ void insert(iterator pos, size type n, const T& x); /* Inserts an unitialized element immediatly after pos and returns its position Calls insert after */ iterator insert(iterator pos); /* Inserts all the elements between rst and last immediatly after pos Calls insert after */ void insert(iterator pos, InIter rst, InIter last);

/* Erases the element after pos. Returns the an iterator on the new element at pos */ iterator erase after(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion */ iterator erase after(iterator rst, iterator last); /* Erases the element at pos.

79

The C++ STL

Returns the new element at pos Calls erase after */ iterator erase(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion Calls erase after */ iterator erase(iterator rst, iterator last); /* Equivalent to erase(begin(), end()) */ void clear();

5.10

Misc functions

The slist class has those functions too : /* Destroys the content of this slist and replaces it by n copies of val */ void assign(size type n, const T& val); /* Destroys the content of this slist and replaces it by the elements between rst and last */ template <class InputIterator> void assign(InputIterator rst, InputIterator last); /* Swaps the content of this slist with the content of x */ void swap(slist<T, A>& x); /* Swaps the content of x and y */ void swap(slist<T, A>& x, slist<T, A>& y); /* Returns this slist allocator */ allocator type get allocator() const;

/* Transfers all elements in a slist starting at position rst + 1 stopping at last - 1, to this slist, immediatly after pos */ void splice after(iterator pos, iterator before rst, iterator before last); /* Moves the element that follows prev to this slist, inserting it immediately after pos. This is done in constant time */ void splice after(iterator pos, iterator prev); /* Transfers all elements from x to this slist, placing them at position pos */ void splice(iterator pos, slist<T, A>& x); /* Transfers all elements in a slist starting at position i to this slist, starting at position pos. 80

The C++ STL

x is unused in many implementations */ void splice(iterator pos, slist<T, A>& x, iterator i); /* Transfers all elements in a slist starting at position rst stopping at last, to this slist, starting at position pos. x is unused in many implementations */ void splice(iterator pos, slist<T, A>& x, iterator rst, iterator last); /* Removes all elements from this slist of value value. Uses operator== of type T */ void remove(const T& value); /* Removes all elements from this slist who gives a positive result when passed to p */ template<class Pred> void remove if(Pred p); /* Deletes all element with the same value except one (generally the rst). Same elements are recognized using operator== of the type T) */ void unique(); /* Uses b instead of operator== */ template<class BinPred> void unique(BinPred b); /* Merges x with this. Both slists must be sorted. This function uses operator< of type T */ void merge(list<T, A>& x); /* Uses cmp instead of operator< */ void merge(list<T, A>& x, cmp); /* Reverses this slist */ void reverse(); /* Sorts this list using operator< of type T */ void sort(); /* Uses cmp instead of operator< */ void sort(cmp);

81

Chapter 6

Vector : <vector>
The vector container is the more generic container. It can be assimilated to an array (it may be used like an array). The main dierence is the possibility of the vector to be extended while adding more elements. The two important thing with a vector is its capacity and its size. The size is the number of elements in the vector. The vector is the number of elements that can be added to a vector before resizing it (to allocate more memory to add the new elements). The time of insertion and removal of elements at the end of a vector is constant. At the beginning and at any other position the time of insertions and removals are linear. In the following sections, we will consider a vector constructed with the template <T, A>. Where T is the value type of the vector and A is the allocator type. The allocator type is optionnal.

6.1

Vector types

A vector container has the following types : /* Type typedef typedef typedef of the elements */ T value type; value type* pointer; const value type* const pointer;

/* Iterator types are implementation dependant */ typedef value type* iterator; typedef const value type* const iterator; typedef value type& reference; typedef const value type& const reference; typedef reverse iterator<const iterator> const reverse iterator; typedef reverse iterator<iterator> reverse iterator; /* This is implementation dependant */ typedef size t size type; typedef ptrdi t dierence type; typedef typename Vector base::allocator type allocator type;

6.2

Vector constructors

A vector container has the following constructors :

82

The C++ STL

explicit vector(const allocator type& a = allocator type()); /* Inits the vector with n copies of the value */ vector(size type n, const T& value, const allocator type& a = allocator type()); /* Allocates n area of memory */ explicit vector(size type n); /* Copy constructor */ vector(const vector<T, A>& x); /* rst and last are iterators on a sequence. The values between rst and last are copied in the new vector */ template <class InputIterator> vector(InputIterator rst, InputIterator last, const allocator type& a = allocator type());

6.3

Vector destructor

A vector container has the following destructor : vector();

6.4

Vector operators

A vector container has the following operators : /* Unchecked access */ reference operator[](size type n); /* Constant access */ const reference operator[](size type n) const; /* Copy operator */ vector<T, A>& operator=(const vector<T, A>& v); /* Compares two vectors using equal function */ bool operator==(const vector<T, A>& x, const vector<T, A>& y); /* Lexicographical compare between vectors */ bool operator<(const vector<T, A>& x, const vector<T, A>& y);

6.5

Vector iterators

A vector has the following iterators :

83

The C++ STL

/* Returns an iterator on the rst element */ iterator begin(); const iterator begin() const; /* Returns an iterator on the element following the last */ iterator end(); const iterator end() const; /* Returns an iterator on the last element */ reverse iterator rbegin(); const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ reverse iterator rend(); const reverse iterator rend() const;

6.6

Vector size and capacity

A vector size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this vector (based on the size of elements type) */ size type max size() const; /* Number of allocated elements (initialized elements plus non initialized) */ size type capacity() const; /* Returns true if this vector contains no element, in this case begin() == end() */ bool empty() const; /* Tries to allocate more memory for n more elements. If n is less than or equal to capacity() this call does nothing */ void reserve(size type n); /* If the new size is less than the current size it erases element from the end to set the size to new size. If the new size is greater then the current size it inserts elements at the end (initialized with x value). */ void resize(size type new size, const T& x); /* Calls resize(size type, value type()) */ void resize(size type new size);

84

The C++ STL

6.7

Accessing elements

Elements of a vector can be accessed using those functions : /* Returns the rst element */ reference front(); /* Returns the rst element */ const reference front(); /* Returns the last element */ reference back(); /* Returns the last element */ const reference back();

6.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Appends the element x at the end */ void push back(const T& x); /* Appends a new unitialized element at the end */ void push back(); /* Inserts x after pos and return x position */ iterator insert(iterator pos, const T& x); /* Adds a new non initialized element */ iterator insert(iterator pos); /* Inserts all the elements between rst and last immediatly after pos */ void insert(iterator pos, const iterator rst, const iterator last); /* Inserts n copies of x immediatly after pos */ void insert(iterator pos, size type n, const T& x); /* Erases the last element */ void pop back(); /* Erases the element at pos. Returns the new element at pos */ iterator erase(iterator pos); /* Erases all elements between rst and last. Returns rst after deletion */ iterator erase(iterator rst, iterator last); /* Equivalent to erase(begin(), end()) */ void clear();

85

The C++ STL

6.9

Misc functions

The vector class has those functions too : /* Destroys the content of this vector and replaces it by n copies of val */ void assign(size type n, const T& val); /* Destroys the content of this vector and replaces it by the elements between rst and last */ template <class InputIterator> void assign(InputIterator rst, InputIterator last); /* Swaps the content of this vector with the content of x */ void swap(vector<T, A>& x); /* Swaps the content of x and y */ void swap(vector<T, A>& x, vector<T, A>& y); /* Returns this vector allocator */ allocator type get allocator() const;

86

Chapter 7

Bitset : <bitset>
The bitset container is pretty much like a vector<bool>. It is a container optimized to contain bits and to oer constant access to each element. A bitset does not follow the STL container way. It is a special container, which is between a real container and an unsigned int. In the following sections we will consider a bitset constructed with the template <N, WordT> where : N is the size of the bitset (must be superior to 0) WordT is a type used to know the size of a word, it must be an unsigned type (this parameter is optionnal, default is unsigned long )

7.1

Bitset types

A bitset has the following types : class reference { public: reference& operator=(const reference&); reference& operator=(bool b); bool operator() const; operator bool() const; reference& ip(); }; /* 0 is the least signicant word */ WordT M w[N];

7.2

Bitset constructors

A bitset has the following constructors : bitset(); bitset(unsigned long val); 87

The C++ STL

/* Creates a bitset using characters in a string (begins at pos and using n as the size of the element contained in the string) */ template<class CharT, class Traits, class Alloc> explicit bitset(const basic string<CharT, Traits, Alloc>& s, size t pos = 0, size t n = size t(basic string<CharT, Traits, Alloc>::npos));

7.3

Bitset destructor

A bitset uses the default destructor.

7.4

Bitset operators

A bitset has the following operators : /* Bitwise operators */ bitset<N, WordT>& operator&=(const bitset<N, WordT>& bs); bitset<N, WordT>& operator|=(const bitset<N, WordT>& bs); bitset<N, WordT>& operator=(const bitset<N, WordT>& bs); bitset<N, WordT>& operator<<=(const bitset<N, WordT>& bs); bitset<N, WordT>& operator>>=(const bitset<N, WordT>& bs); template <size t N, class WordT> bitset<N, WordT> operator&(const bitset<N, WordT>& x, const bitset<N, WordT>& y); template <size t N, class WordT> bitset<N, WordT> operator|(const bitset<N, WordT>& x, const bitset<N, WordT>& y); template <size t N, class WordT> bitset<N, WordT> operator(const bitset<N, WordT>& x, const bitset<N, WordT>& y); bitset<N, WordT> operator<<(size t pos) const; bitset<N, WordT> operator>>(size t pos) const; bitset<N, WordT> operator() const;

reference operator[](size t pos); bool operator[](size t pos) const; bool operator==(const bitset<N, WordT>& bs) const; template <size t N, class WordT> istream& operator>>(istream& is, bitset<N, WordT>& x); template <size t N, class WordT> ostream& operator<<(ostream& os, const bitset<N, WordT>& x);

88

The C++ STL

7.5

Bitset iterators

You cannot iterate on a bitset.

7.6

Bitset size and capacity

A bitset size and capacity can be checked and changed using those functions : /* Returns the number of bits that are set */ size t count() const; /* Returns the template parameter N */ size t size() const;

7.7

Testing and changing bits

Bits value can be tested and changed using those functions : /* Returns true if bit at pos is set */ bool test(size t pos) const; /* Returns true if any bit is set */ bool any() const; /* Returns true if none of the bit is set */ bool none() const; /* Sets all bits */ bitset<N, WordT>& set(); /* Set bit at pos */ bitset<N, WordT>& set(size t pos); /* Set the bit at pos making it becomes value */ bitset<N, WordT>& set(size t pos, int val); /* Unsets all bits */ bitset<N, WordT>& reset(); /* Unset bit at pos */ bitset<N, WordT>& reset(size t pos); /* Flips all bits */ bitset<N, WordT>& ip(); /* Flips bit at pos */ bitset<N, WordT>& ip(size t pos);

7.8

Converting a bitset

A bitset can be converted in a string or in an unsigned long using those function :

89

The C++ STL

unsigned long to ulong() const; template <class CharT, class Traits, class Alloc> basic string<CharT, Traits, Alloc> to string() const;

90

Part V

Associative Containers

91

Chapter 1

What are associative containers ?


Associative containers are containers like sequence container, but each value contained in it is associated with something called a key.

1.1 1.2

Introduction When use an associative container ?

92

Chapter 2

Hash : <hashtable.h>
2.1 What is a hash table ?

A hash table (shortly known as hash), is an associative container. It is a container that associates a value and a key. Each key can have more than one value. The keys and their values are put into place known as buckets. Each bucket corresponds to a unique key. The dierence between a hash table and others associative containers is that you MUST specify the functions used by the hash table on its creation. The advantage of this, is that you can choose yourself the type of the argument and of the returned object of those functions. The only constraint is that your operator() must be const because the hash table will pass constant references to it when doing something. The table is lled by using a hash function (called hf in constructors). This function returns a position in the table by doing something on the key. The function equals (called eql in constructors) is used to test if two keys are equal. The function extract key (called ext in constructors) is used to obtain a key by giving it a value. The prototypes of those functors are choosen on the hash table creation (you put it in the template). In the following sections, all hash tables will be constructed with the template : <val, key, hf, ext, eql, a>. Where : val is the value type key is the key type hf is the hash function ext is the extract key function eql is the equals function a is the allocator type (optionnal)

2.2

Hash types

A hash container has the following types : typedef Key key type; typedef T value type; typedef EqualKey key equal;

93

The C++ STL

/* Hash function */ typedef HashFcn hasher; typedef typedef typedef typedef typedef typedef size t size type; ptrdi t dierence type; value type* pointer; const value type* const pointer; value type& reference; const value type& const reference;

2.3

Hash constructors

A hash container has the following constructors : hashtable(size type n, const HashFcn& hf, const EqualKey& eql, const ExtractKey& ext, const allocator type& a = allocator type()); hashtable(size type n, const HashFcn& hf, const EqualKey& eql, const allocator type& a = allocator type()); /* Copy constructor */ hashtable(const hashtable& ht);

In those constructors hf is a hash function, ext allow to extract a key by giving it a complete bucket.

2.4

Hash destructor

A hash container has the following destructor : hashtable();

2.5

Hash operators

A hash container has the following operators : /* For each common key check if the values are equal. Returns false if the number of key is dierent, if there is key which is not in common or if two values are not equal but have the same key */ bool operator==(const hashtable<val, key, hf, ext, eql, a>& ht1, const hashtable<val, key, hf, ext, eql, a>& ht2);

94

The C++ STL

/* Copy operator */ hashtable& operator=(const hashtable& ht);

2.6

Hash iterators

Hash iterators can be used to move accross the value contained in a hash table. To get the key corresponding to a value, you may use the extract function that you used to create your hash table. typedef hashtable iterator<val, key, hf, ext, eql, a> iterator; typedef hashtable const iterator<val, key, hf, ext, eql, a> const iterator; /* Returns an iterator on the rst element */ iterator begin(); const iterator begin(); /* Returns an iterator on the element following the last */ iterator end(); const iterator end();

2.7

Hash size and capacity

A hash size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash table (based on the size of elements type) */ size type max size() const; /* Returns true if this hash table contains no element, in this case begin() == end() */ bool empty() const; void resize(size type num element hint);

2.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* If the value corresponding to obj already exists, returns it. In other case inserts it then returns an iterator on it. The boolean is the pair is false if

95

The C++ STL

the value existed or true in other case */ pair<iterator, bool> insert unique(const value type& obj); /* Do not resize the hash table (do not check the hash table size) */ pair<iterator, bool> insert unique no resize(const value type& obj); /* Uses insert unique to insert all element between f and l */ template<class InputIterator> void insert unique(InputIterator f, InputIterator l); /* The last argument species the iterator category (not used) */ template<class InputIterator> void insert unique(InputIterator f, InputIterator l, input iterator tag); template<class ForwardIterator> void insert unique(ForwardIterator f, ForwardIterator l, forward iterator tag); /* If the value corresponding to obj already exists, add a new value corresponding to this key using a avor of linkes list. In other case inserts it then returns an iterator on it. */ iterator insert equal(const value type& obj); /* Do not resize the hash table (do not check the hash table size) */ iterator insert equal no resize(const value type& obj); /* Uses insert equal to insert all element between f and l */ template<class InputIterator> void insert equal(InputIterator f, InputIterator l); /* The last argument species the iterator category (not used) */ template<class InputIterator> void insert equal(InputIterator f, InputIterator l, input iterator tag); template<class ForwardIterator> void insert equal(ForwardIterator f, ForwardIterator l, forward iterator tag); /* Seeks for a value in this. If founded returns it. In other case inserts it then returns it */ reference nd or insert(const value type& obj); /* Erases the bucket corresponding to key */ size type erase(const type& key); /* Erases the value pointed by it */ void erase(const iterator& it); void erase(const const iterator& it); /* Erases all elements between rst and last (in the same bucket) */ void erase(iterator rst, iterator last); void erase(const iterator rst, const iterator last); /* Empties the hash table */ void clear();

2.9

Misc functions

The hash class has those functions too : /* Swaps the content of this hash table with the content of x */ 96

The C++ STL

void swap(hashtable<val, key, hf, ext, eql, a>& x); /* Swaps the content of x and y */ void swap(hashtable<val, key, hf, ext, eql, a>& x, hashtable<val, key, hf, ext, eql, a>& y); /* Returns this hash table allocator */ allocator type get allocator() const; /* Returns the number of buckets allocated for this hash table */ size type bucket count() const; /* Returns the maximum number of buckets that can be allocated */ size type max bucket count() const; /* Returns the total number of elements in a bucket */ size type elems in bucket(size type bucket) const; /* Returns an iterator on the value corresponding tokey */ iterator nd(const key type& key); const iterator nd(const key type& key) const; /* Returns the number of elements in the bucket corresponding to key */ size type count(const key type& key) const; /* Returns a range of value where all elements correspond to key */ pair<iterator, iterator> equal range(const key type& key); pair<iterator, iterator> equal range(const key type& key) const; void resize(size type num element hint);

2.10

Hash table exemple

Here is an example of how to use a hash table. #include <hashtable.h> #include <iostream> class hash func { public: char operator()(const int& value) const { return static cast<char>(value); } }; class extractor

97

The C++ STL

{ public: int operator()(const char& value) const { return static cast<int>(value); } }; class equal key { public: bool operator()(const int& key1, const int& key2) const { return key1 == key2; } }; /* Main program */ int main(int argc, char* argv[]) { hash func hf; extractor ex; equal key eq; hashtable<char, int, hash func, extractor, equal key> ht(sizeof(char), hf, eq, ex); hashtable<char, int, hash func, extractor, equal key>::iterator it; ht.insert unique(a); ht.insert unique(b); ht.insert unique(x); /* Displays : 120 : x 97 : a 98 : b */ for(it = ht.begin(); it != ht.end(); it++) { cout << ex(*it) << : ; cout << *it << endl; } return 0; } /* >>> EOF <<< */

98

Chapter 3

Hash map : <hash map>


3.1 What is a hash map ?

A hash map is an associative container which contains element of type pair<const Key, value>. Each value is identied by a unique key. The hash map container use a hash table, thus the two container are very identical. In the following sections we will consider a hash map constructed with the template : <K, T, hf, eq, a> where : K is the key type T is the value type hf is the hash function. This argument is optionnal (default is hash<K>) eq is the equal function to compare values. This parameter is optionnal (default is equal to<T>) a is the hash map allocator. This argument is optionnal (default is the stl default allocator for type T )

3.2

Hash map types

A hash map container has the following types : /* This type is private */ typedef hashtable<pair<const K,T>, K, hf, select1st< pair<const K, T> >, eq, a> ht; /* This member is private */ ht ht; /* Type typedef /* Type typedef typedef typedef typedef typedef typedef typedef typedef typedef of the keys */ ht::Key key type; of the values */ T data type; T mapped type; ht::value type value type; ht::hasher hasher; ht::key equal key equal; ht::size type size type; ht::dierence type dierence type; ht::pointer pointer; ht::const pointer const pointer; 99

The C++ STL

typedef ht::reference reference; typedef ht::const reference const reference; typedef ht::iterator iterator; typedef ht::const itertator const iterator; typedef ht::allocator type allocator type; /* These functions return types of ht member (because it is a private member) */ /* Returns the hash function */ hasher hash funct() const; /* Returns the equal function */ key equal key eq() const;

3.3

Hash map constructors

A hash map container has the following constructors : /* Default constructor */ hash map() : ht(100, hasher(), key equal(), allocator type()); explicit hash map(size type n) : ht(n, hasher(), key equal(), allocator type()); hash map(size type n, const hasher& hf) : ht(n, hf, key equal(), allocator type()); hash map(size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type()): ht(n, hf, eql, a);

/* Inits the hash map with the elements bewteen rst and last */ template <class InputIterator> hash map(InputIterator rst, InputIterator last); template <class InputIterator> hash map(InputIterator rst, InputIterator last, size type n); template <class InputIterator> hash map(InputIterator rst, InputIterator last, size type n, const hasher& hf); template <class InputIterator> hash map(InputIterator rst, InputIterator last, size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type());

3.4

Hash map destructor

A hash map container uses the default destructor (it calls the destructor of hash ).

100

The C++ STL

3.5

Hash map operators

A hash map container has the following operators : /* Uses hash::operator== to compare h1. ht and h2. ht */ bool operator==(const hash map<K, T, hf, eq, a>& h1, const hash map<K, T, hf, eq, a>& h2); /* Returns a value by giving its key */ T& operator[](const key type& key);

3.6

Hash Map iterators

Hash map iterators are of type pair the rst element is the key and the second element is the value. Thus, if you want to get the key and the value contained in an iterator it use it-rst and it-second. Iterators can be obtained using the following functions : iterator begin(); const iterator begin() const; iterator end(); const iterator end() const;

3.7

Hash map size and capacity

A hash map size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash map (based on the size of elements type) */ size type max size() const; /* Returns true if this hash table contains no element, in this case begin() == end() */ bool empty() const; void resize(size type hint);

3.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts a new value in this hash map and returns a pair containing an iterator

101

The C++ STL

on the value in rst, and a bool in second. The second value is true if insertion was successful or false in other case */ pair<iterator, bool> insert(const value type& x); /* Inserts a new value with no size check */ pair<iterator, bool> insert no resize(const value type& obj); /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Returns the number of elements deleted (0 or 1) */ size type erase(const key type& key); void erase(iterator it); void erase(iterator rst, iterator last); void clear();

3.9

Misc functions

The hash map class has those functions too : /* Swaps the content of this hash map with the content of x */ void swap(hash map<K, T, hf, eq, a>& x); /* Swaps the content of x and y */ void swap(hash map<K, T, hf, eq, a>& h1, hash map<K, T, hf, eq, a>& h2); /* Returns this hash map allocator */ allocator type get allocator() const; /* Returns the number of buckets allocated for this hash map */ size type bucket count() const; /* Returns the maximum number of buckets that can be allocated */ size type max bucket count() const; /* Returns the total number of elements in a bucket */ size type elems in bucket(size type bucket) const; /* Returns an iterator on the value corresponding to key */ iterator nd(const key type& key); const iterator nd(const key type& key) const; /* Returns the number of elements in the bucket corresponding to key */ size type count(const key type& key) const;

102

The C++ STL

/* Returns a range of value where all elements correspond to key */ pair<iterator, iterator> equal range(const key type& key); pair<const iterator, const iterator> equal range(const key type& key) const;

3.10

Hash map exemple

Here is an example of how to use a hash map. #include <hash map> #include <string> int main(int argc, char* argv[]) { hash map<int, string> h; h[1] = toto; h[2] = tata; h[3] = titi; h.insert(pair<int, string>(4, toto is back)); /* Displays: 1 = toto 2 = tata 3 = titi 4 = toto is back */ for(hash map<int, string>::iterator it = h.begin(); it != h.end(); it++) { cout << it->rst << = << it->second << endl; } return 0; } /* >>> EOF <<< */

103

Chapter 4

Hash multimap : <hash map>


4.1 What is a hash multimap ?

The hash multimap is a hash map that can contain multiple for a same key. Most of hash multimap function call the corresponding hash map function (on his private member). In the following section, we will consider a hash multimap created with the template : <pair<const K, T>, K, hf, select1st<pair<const K, T>>, eq, A> where : K is the key type T is the value type hf is the hash function eq is the equal function to compare values. This parameter is optionnal (default is equal to<T>) a is the hash multimap allocator. This argument is optionnal (default is the stl default allocator for type T )

4.2

Hash multimap types

A hash multimap container has the following types : /* This type is private */ typedef hashtable<pair<const K, T>, K, hf, select1st<pair<const K, T> >, eq, A> ht; /* This member is private. It is used to dene hash multimap types */ ht M ht; typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef ht::key type key type; ht::value type value type; T data type; T mapped type; ht::hasher hasher; ht::key equal key equal; ht::size type size type; ht::dierence type dierence type; ht::pointer pointer; ht::const pointer const pointer; ht::reference reference; 104

The C++ STL

typedef typedef typedef typedef

ht::const reference const reference; ht::iterator iterator; ht::const iterator const iterator; ht::allocator type allocator type;

4.3

Hash multimap constructors

A hash multimap container has the following constructors : /* Default constructor */ hash multimap(); explicit hash multimap(size type n); hash multimap(size type n, const hasher& hf); hash multimap(size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type());

/* Inits the hash multimap with the elements bewteen rst and last */ template <class InputIterator> hash multimap(InputIterator rst, InputIterator last); template <class InputIterator> hash multimap(InputIterator rst, InputIterator last, size type n); template <class InputIterator> hash multimap(InputIterator rst, InputIterator last, size type n, const hasher& hf); template <class InputIterator> hash multimap(InputIterator rst, InputIterator last, size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type());

4.4

Hash multimap destructor

A hash multimap container uses the default destructor (it calls the destructor of hash map ).

4.5

Hash multimap operators

A hash multimap container has the following operators : bool operator==(const hash multimap& h1, const hash multimap& h2);

4.6

Hash Multimap iterators

Here is the hash multimap access functions to iterators : iterator begin(); const iterator begin() const; iterator end();

105

The C++ STL

const iterator end() const;

4.7

Hash multimap size and capacity

A hash multimap size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash multimap (based on the size of elements type) */ size type max size() const; /* Returns true if this hash multimap contains no element, in this case begin() == end() */ bool empty() const; void resize(size type hint);

4.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Inserts a new (key, value) couple use pair to insert it. */ iterator insert(const value type& obj); iterator insert no resize(const value type& obj); /* Returns the number of elements deleted */ size type erase(const key type& key); void erase(iterator it); void erase(iterator rst, iterator last); void clear();

4.9

Misc functions

The hash multimap class has those functions too : /* Swaps the content of this hash map with the content of x */ void swap(hash multimap& x); /* Swaps the content of x and y */

106

The C++ STL

void swap(hash multimap<K, T, hf, eq, a>& h1, hash map<K, T, hf, eq, a>& h2); /* Returns this hash multimap allocator */ allocator type get allocator() const; /* Returns the number of buckets allocated for this hash multimap */ size type bucket count() const; /* Returns the maximum number of buckets that can be allocated */ size type max bucket count() const; /* Returns the total number of elements in a bucket */ size type elems in bucket(size type bucket) const; /* Returns an iterator on the value corresponding to key */ iterator nd(const key type& key); const iterator nd(const key type& key) const; /* Returns the number of elements in the bucket corresponding to key */ size type count(const key type& key) const; /* Returns a range of value where all elements correspond to key */ pair<iterator, iterator> equal range(const key type& key); pair<iterator, iterator> equal range(const key type& key) const;

107

Chapter 5

Hash set : <hash set>


5.1 What is a hash set ?

A hash set is a set that uses a hash table to provide faster searching functionnality. In the following sections we will consider a hash set constructed with the template : <T, hf, eq, A> where : T is the value type (since set has no key value type and key type are the same) hf is the hash function. This parameter is optionnal (default is hash<T>) eq is the equal function to compare values. This parameter is optionnal (default is equal to<T>) A is the hash set allocator. This parameter is optionnal (default is the stl default allocator for type T )

5.2

Hash set types

A hash set container has the following types : /* This type is private */ typedef hashtable<T, T, hf, identity<T>, eq, A> ht; /* This member is private */ ht ht; /* Type typedef /* Type typedef typedef typedef typedef typedef of the keys */ ht::Key key type; of the values */ ht::value type value type; ht::hasher hasher; ht::key equal key equal; ht::size type size type; ht::dierence type dierence type;

typedef ht::const pointer pointer; typedef ht::const pointer const pointer; typedef ht::const reference reference; typedef ht::const reference const reference;

108

The C++ STL

typedef ht::const iterator iterator; typedef ht::const itertator const iterator; typedef ht::allocator type allocator type;

/* These functions return types of ht member (because it is a private member) */ /* Returns the hash function */ hasher hash funct() const; /* Returns the equal function */ key equal key eq() const;

5.3

Hash set constructors

A hash set container has the following constructors : /* Default constructor */ hash set() : ht(100, hasher(), key equal(), allocator type()); explicit hash set(size type n) : ht(n, hasher(), key equal(), allocator type()); hash set(size type n, const hasher& hf) : ht(n, hf, key equal(), allocator type()); hash set(size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type()): ht(n, hf, eql, a);

/* Inits the hash set with the elements bewteen rst and last */ template <class InputIterator> hash set(InputIterator rst, InputIterator last); template <class InputIterator> hash set(InputIterator rst, InputIterator last, size type n); template <class InputIterator> hash set(InputIterator rst, InputIterator last, size type n, const hasher& hf); template <class InputIterator> hash set(InputIterator rst, InputIterator last, size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type());

5.4

Hash set destructor

A hash set container uses the default destructor (it calls the destructor of hash ).

5.5

Hash set operators

A hash set container has the following operators :

109

The C++ STL

/* Uses hash::operator== to compare h1. ht and h2. ht */ bool operator==(const hash set<T, hf, eq, a>& h1, const hash set<T, hf, eq, a>& h2);

5.6

Hash set iterators

Hash set iterators can be obtained using the following functions : iterator begin() const; iterator end() const;

5.7

Hash set size and capacity

A hash set size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash set (based on the size of elements type) */ size type max size() const; /* Returns true if this hash set contains no element, in this case begin() == end() */ bool empty() const; void resize(size type hint);

5.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts a new value in this hash set and returns a pair containing an iterator on the value in rst, and a bool in second. The second value is true if insertion was successful or false in other case */ pair<iterator, bool> insert(const value type& x); /* Inserts a new element with no size check */ pair<iterator bool> insert no resize(const value type& obj); /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Returns the number of elements deleted (0 or 1) */

110

The C++ STL

size type erase(const key type& key); void erase(iterator it); void erase(iterator rst, iterator last); void clear();

5.9

Misc functions

The hash set class has those functions too : /* Swaps the content of this hash set with the content of x */ void swap(hash set<T, hf, eq, a>& x); /* Swaps the content of x and y */ void swap(hash set<T, hf, eq, a>& h1, hash set<T, hf, eq, a>& h2); /* Returns this hash set allocator */ allocator type get allocator() const; /* Returns the number of buckets allocated for this hash set */ size type bucket count() const; /* Returns the maximum number of buckets that can be allocated */ size type max bucket count() const; /* Returns the total number of elements in a bucket */ size type elems in bucket(size type bucket) const; /* Returns an iterator on the value corresponding to key */ iterator nd(const key type& key) const; /* Returns the number of elements in the bucket corresponding to key */ size type count(const key type& key) const; /* Returns a range of value where all elements correspond to key */ pair<iterator, iterator> equal range(const key type& key) const;

111

Chapter 6

Hash multiset : <hash set>


6.1 What is a hash multiset ?

The hash multiset is a hash set that can contain multiple identical values. In the following section, we will consider a hash multiset created with the template <T, hf, eq, A> where : T is the value type (since set has no key value type and key type are the same) hf is the hash function. This parameter is optionnal (default is hash<T>) eq is the equal function to compare values. This parameter is optionnal (default is equal to<T>) A is the hash multiset allocator. This parameter is optionnal (default is the stl default allocator for type T )

6.2

Hash multiset types

A hash multiset container has the following types : /* This type is private */ typedef hashtable<T, T, hf, identity<T>, eq, A> ht; /* This member is private */ ht ht; /* Type typedef /* Type typedef typedef typedef typedef typedef of the keys */ ht::Key key type; of the values */ ht::value type value type; ht::hasher hasher; ht::key equal key equal; ht::size type size type; ht::dierence type dierence type;

typedef ht::const pointer pointer; typedef ht::const pointer const pointer; typedef ht::const reference reference; typedef ht::const reference const reference;

112

The C++ STL

typedef ht::const iterator iterator; typedef ht::const itertator const iterator; typedef ht::allocator type allocator type;

/* These functions return types of ht member (because it is a private member) */ /* Returns the hash function */ hasher hash funct() const; /* Returns the equal function */ key equal key eq() const;

6.3

Hash multiset constructors

A hash multiset container has the following constructors : /* Default constructor */ hash multiset() : ht(100, hasher(), key equal(), allocator type()); explicit hash multiset(size type n) : ht(n, hasher(), key equal(), allocator type()); hash multiset(size type n, const hasher& hf) : ht(n, hf, key equal(), allocator type()); hash multiset(size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type()): ht(n, hf, eql, a);

/* Inits the hash multiset with the elements bewteen rst and last */ template <class InputIterator> hash multiset(InputIterator rst, InputIterator last); template <class InputIterator> hash multiset(InputIterator rst, InputIterator last, size type n); template <class InputIterator> hash multiset(InputIterator rst, InputIterator last, size type n, const hasher& hf); template <class InputIterator> hash multiset(InputIterator rst, InputIterator last, size type n, const hasher& hf, const key equal& eql, const allocator type& a = allocator type());

6.4

Hash multiset destructor

A hash multiset container uses the default destructor (it calls the destructor of hash ).

6.5

Hash multiset operators

A hash multiset container has the following operators :

113

The C++ STL

/* Uses hash::operator== to compare h1. ht and h2. ht */ bool operator==(const hash multiset<T, hf, eq, a>& h1, const hash multiset<T, hf, eq, a>& h2);

6.6

Hash multiset iterators

Hash multiset iterators can be obtained using the following functions : iterator begin() const; iterator end() const;

6.7

Hash multiset size and capacity

A hash multiset size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash multiset (based on the size of elements type) */ size type max size() const; /* Returns true if this hash multiset contains no element, in this case begin() == end() */ bool empty() const; void resize(size type hint);

6.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts a new value in this hash multiset and returns an iterator on it */ iterator insert(const value type& x); /* Inserts a new element with no size check */ iterator insert no resize(const value type& obj); /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Returns the number of elements deleted (0 or 1) */ size type erase(const key type& key); void erase(iterator it); void erase(iterator rst, iterator last);

114

The C++ STL

void clear();

6.9

Misc functions

The hash multiset class has those functions too : /* Swaps the content of this hash multiset with the content of x */ void swap(hash multiset<T, hf, eq, a>& x); /* Swaps the content of x and y */ void swap(hash multiset<T, hf, eq, a>& h1, hash multiset<T, hf, eq, a>& h2); /* Returns this hash multiset allocator */ allocator type get allocator() const; /* Returns the number of buckets allocated for this hash multiset */ size type bucket count() const; /* Returns the maximum number of buckets that can be allocated */ size type max bucket count() const; /* Returns the total number of elements in a bucket */ size type elems in bucket(size type bucket) const; /* Returns an iterator on the value corresponding to key */ iterator nd(const key type& key) const; /* Returns the number of elements in the bucket corresponding to key */ size type count(const key type& key) const; /* Returns a range of value where all elements correspond to key */ pair<iterator, iterator> equal range(const key type& key) const;

115

Chapter 7

Map : <map>
7.1 What is a map ?

A map is a container that associates a key and a value. All key are unique : two elements cannot have dierent keys. The element type is pair<const K, T> where K is the key type and T the data type. In the following sections we will consider a map constructed with the template <K, T, Compare, A> where : K is the key type T is the data type Compare is the comparator function. This parameter is optionnal (default is less<K> A is the allocator. This parameter is optionnal (default is the stl default allocator for type T)

7.2
typedef typedef typedef typedef typedef

Map types
K key type; T data type; T mapped type; pair<const K, T> value type; Compare key compare;

A map container has the following types :

/* Public internal class, used to compare two values by overloading operator() */ class value compare : public binary function<value type, value type, bool>; bool value compare::operator()(const value type& x, const value type& y); /* This type is private. It is used to store values */ typedef Rb tree<key type, value type, select1st<value type>, key compare, A> Rep type; /* This member is private */ Rep type M t;

116

The C++ STL

typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef typedef

Rep Rep Rep Rep Rep Rep Rep Rep Rep Rep Rep

type::pointer pointer; type::const pointer const pointer; type::reference reference; type::const reference const reference; type::iterator iterator; type::const iterator const iterator; type::reverse iterator reverse iterator; type::const reverse iterator const reverse iterator; type::size type size type; type::dierence type dierence type; type::allocator type allocator type;

7.3

Map constructors

A map container has the following constructors : map(); explicit map(const Compare& comp, const allocator type& a = allocator type()); template<class InputIterator> map(InputIterator rst, InputIterator last); template<class InputIterator> map(InputIterator rst, InputIterator last, const Compare& comp, const allocator type& a = allocator type()); /* Copy constructor */ map(const map<K, T, Compare, A>& x);

7.4

Map destructor

A map container uses the default destructor (it calls the destructor of rb tree ).

7.5

Map operators

A map container has the following operators : map<K, T, Compare, A>& operator=(const map<K, T, Compare, A>& x); T& operator[](const key type& k); bool operator==(const map<K, T, Compare, A>& m1, const map<K, T, Compare, A>& m2); bool operator<(const map<K, T, Compare, A>& m1, const map<K, T, Compare, A>& m2);

7.6

Map iterators

Map iterators can be obtained using the following functions : /* Returns an iterator on the rst element */ iterator begin(); 117

The C++ STL

const iterator begin() const; /* Returns an iterator on the element following the last */ iterator end(); const iterator end() const; /* Returns an iterator on the last element */ reverse iterator rbegin(); const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ reverse iterator rend(); const reverse iterator rend() const;

7.7

Map size and capacity

A map size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this map (based on the size of elements type) */ size type max size() const; /* Returns true if this map contains no element, in this case begin() == end() */ bool empty() const;

7.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : pair<iterator,bool> insert(const value type& x) iterator insert(iterator position, const value type& x); /* Inserts all element between rst and last */ template <class InputIterator> void insert(InputIterator rst, void erase(iterator position); /* Returns the number of deleted element (0 or 1) */ size type erase(const key type& x); void erase(iterator rst, iterator last); void clear();

InputIterator last);

118

The C++ STL

7.9

Misc functions

The map class has those functions too : /* Returns an iterator on x */ iterator nd(const key type& x); const iterator nd(const key type& x); /* Counts the number of x in this map (0 or 1) */ size type count(const key type& x) const; /* Returns an iterator on the rst element whose key is not less than x */ iterator lower bound(const key type& x); const iterator lower bound(const key type& x) const; /* Returns an iterator on the rst element whose key is greater the x */ iterator upper bound(const key type& x); const iterator upper bound(const key type& x) const; /* Returns a pair composed by the lower bound() and the upper bound() */ pair<iterator, iterator> equal range(const key type& x); pair<const iterator, const iterator> equal range(const key type& x) const; /* Swaps the content of x and y */ template <class K, class T, class compare, class A> inline void swap(map<K, T, compare, A>& x, map<K, T, compare, A>& y); /* Swaps the content of this map with the content of x */ void swap(map<K, T, compare, A>& x); /* Returns this map allocator */ allocator type get allocator() const; /* Returns this map key or value comparator */ key compare key comp() const; value compare value comp() const;

119

Chapter 8

Multimap : <multimap.h>
8.1 What is a multimap ?

A multimap is very similar to a map. The dierence is that you can store multiple values for a same key. In the following sections we will consider a multimap constructed with the template : <K, T, compare, A> where K is the key type T is the value type compare is a function used to compare keys. This parameter is optionnal (default is less<K>). A is the multimap allocator. This argument is optionnal (default is the stl default allocator for type T ) Like the set container, multimap uses a red-black tree. It uses the bucket mechanism like the set container.

8.2
typedef typedef typedef typedef typedef

Multimap types
K key type; T data type; T mapped type; pair<const K, T> value type; compare key compare;

A multimap container has the following types :

/* Hash multimap contains this utility class */ class value compare : public binary function<value type, value type, bool>; bool value compare::operator()(const value type& x, const value type& y) const; /* This type is private */ typedef rb tree<key type, value type, select1st<value type>, key compare, A> rep type; /* This member is private */ rep type m t;

120

The C++ STL

/* Public types are dened using rep type */ typedef rep type::pointer pointer; typedef rep type::const pointer const pointer; typedef rep type::reference reference; typedef rep type::const reference const reference; typedef rep type::iterator iterator; typedef rep type::const iterator const iterator; typedef rep type::reverser iterator reverse iterator; typedef rep type::const reverse iterator const reverse iterator; typedef rep type::size type size type; typedef rep type::dierence type dierence type; typedef rep type::allocator type allocator type;

8.3

Multimap constructors

A multimap container has the following constructors : multimap(); explicit multimap(const compare& comp, const allocator type& a = allocator type()); template <class InputIterator> multimap(InputIterator rst, InputIterator last); template <class InputIterator> multimap(InputIterator rst, InputIterator last, const compare& comp, const allocator type& a = allocator type()); /* Copy constructor */ multimap(const multimap<K, T, compare, A>& x);

8.4

Multimap destructor

A multimap container uses the default destructor (it calls the destructor of rb tree ).

8.5

Multimap operators

A multimap container has the following operators : multimap<K, T, compare, A>& operator=(const multimap<K, T, compare, A>& x); bool operator==(const multimap<K, T, compare, A>& m1, multimap<K, T, compare, A>& m2); /* Uses rb tree::operator< */ bool operator<(const multimap<K, T, compare, A>& m1, multimap<K, T, compare, A>& m2);

8.6

Multimap iterators

Multimap iterators use the type rb tree::iterator : 121

The C++ STL

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;

8.7

Multimap size and capacity

A multimap size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this hash multimap (based on the size of elements type) */ size type max size() const; /* Returns true if this hash multimap contains no element, in this case begin() == end() */ bool empty() const;

8.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Inserts a new (key, value) couple use pair to insert it. */ iterator insert(const value type& x); iterator insert(iterator position, const value type& x); /* Returns the number of elements deleted */ size type erase(const key type& key); void erase(iterator pos); void erase(iterator rst, iterator last); void clear();

122

The C++ STL

8.9

Misc functions

The multimap class has those functions too : /* Returns an iterator on x */ iterator nd(const key type& x); const iterator nd(const key type& x) const; /* Counts the number of x in this multimap (0 or 1) */ size type count(const key type& x) const; /* Returns an iterator on the rst element whose key is not less than x */ iterator lower bound(const key type& x); const iterator lower bound(const key type& x) const; /* Returns an iterator on the rst element whose key is greater the x */ iterator upper bound(const key type& x); const iterator upper bound(const key type& x) const; /* Returns a pair composed by the lower bound() and the upper bound() */ pair<iterator, iterator> equal range(const key type& x); pair<const iterator, const iterator> equal range(const key type& x) const; /* Swaps the content of x and y */ template <class K, class T, class compare, class A> inline void swap(multimap<K, T, compare, A>& x, multimap<K, T, compare, A>& y); /* Swaps the content of this multimap with the content of x */ void swap(multimap<K, T, compare, A>& x); /* Returns this multimap allocator */ allocator type get allocator() const; /* Returns this multimap key or value comparator */ key compare key comp() const; value compare value comp() const;

8.10

Multimap exemple

Here is an example of how to use a multimap. #include <multimap.h> #include <string> int main(int argc, char* argv[]) { multimap<int, char> h;

123

The C++ STL

h.insert(pair<int, h.insert(pair<int, h.insert(pair<int, h.insert(pair<int, h.insert(pair<int,

char>(1, char>(1, char>(1, char>(2, char>(5,

t)); o)); i)); b)); c));

/* Displays: 1=t 1=o 1=i 2=b 5=c */ for(multimap<int, char>::iterator it = h.begin(); it != h.end(); it++) { cout << it->rst << = << it->second << endl; } return 0; } /* >>> EOF <<< */

124

Chapter 9

Multiset : <set>
9.1 What is a multiset ?

A multiset is very similar to a set. The dierence is that you can store multiple identical values. In the following sections we will consider a multiset constructed with the template : <K, Compare, A> where K is the key type and the value type Compare is a function used to compare keys. less<K>). This parameter is optionnal (default is

A is the multiset allocator. This argument is optionnal (default is the stl default allocator for type T ) Like the set container, multiset uses a red-black tree.

9.2
typedef typedef typedef typedef

Multiset types
K key type; K value type; Compare key compare; Compare value compare;

A multiset container has the following types :

/* This type is private */ typedef Rb tree<key type, value type, Identity<value type>, key compare, A> Rep type; /* This member is private */ Rep type M t; /* Public types dened using M t types */ typedef Rep type::const pointer pointer; typedef Rep type::const pointer const pointer; typedef Rep type::const reference reference; typedef Rep type::const reference const reference; typedef Rep type::const iterator iterator; typedef Rep type::const iterator const iterator; typedef Rep type::const reverse iterator reverse iterator; typedef Rep type::const reverse iterator const reverse iterator; typedef Rep type::size type size type; 125

The C++ STL

typedef Rep type::dierence type dierence type; typedef Rep type::allocator type allocator type;

9.3

Multiset constructors

A multiset container has the following constructors : multiset(); explicit multiset(const Compare& comp, const allocator type& a = allocator type()); template <class InputIterator> multiset(InputIterator rst, InputIterator last); template <class InputIterator> multiset(InputIterator rst, InputIterator last, const Compare& comp, const allocator type& a = allocator type()); /* Copy constructor */ multiset(const multiset<K, Compare, A>& x);

9.4

Multiset destructor

A multiset container uses the default destructor (it calls the destructor of rb tree ).

9.5

Multiset operators

A multiset container has the following operators : multiset<K, Compare, A>& operator=(const multiset<K, Compare, A>& x); bool operator==(const multiset<K, Compare, A>& m1, const multiset<K, Compare, A>& m2); bool operator<(const multiset<K, Compare, A>& m1, const multiset<K, Compare, A>& m2);

9.6

Multiset iterators

Multiset iterators use the type rb tree::iterator : iterator begin() const; iterator end() const; reverse iterator rbegin() const; reverse iterator rend() const;

9.7

Multiset size and capacity

A multiset size and capacity can be checked and changed using those functions :

126

The C++ STL

/* The number of element */ size type size() const; /* The largest possible size of this multiset (based on the size of elements type) */ size type max size() const; /* Returns true if this multiset contains no element, in this case begin() == end() */ bool empty() const;

9.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Inserts the elements between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); iterator insert(const value type& x); iterator insert(iterator position, const value type& x); /* Returns the number of elements deleted */ size type erase(const key type& key); void erase(iterator pos); void erase(iterator rst, iterator last); void clear();

9.9

Misc functions

The multiset class has those functions too : /* Returns an iterator on x */ iterator nd(const key type& x); /* Counts the number of x in this multiset (0 or 1) */ size type count(const key type& x) const; /* Returns an iterator on the rst element whose key is not less than x */ iterator lower bound(const key type& x) const; /* Returns an iterator on the rst element whose key is greater the x */ iterator upper bound(const key type& x) const; /* Returns a pair composed by the lower bound() and the upper bound() */

127

The C++ STL

pair<iterator, iterator> equal range(const key type& x) const; /* Swaps the content of x and y */ template <class K, class Compare, class A> inline void swap(multiset<K, Compare, A>& x, multiset<K, Compare, A>& y); /* Swaps the content of this multiset with the content of x */ void swap(multiset<T, compare, A>& x); /* Returns this multiset allocator */ allocator type get allocator() const; /* Returns this multiset key or value comparator */ key compare key comp() const; value compare value comp() const;

128

Chapter 10

Set : <set>
10.1 The set container

The set container corresponds to the mathematical denition of a set of elements : each element is unique in a set. When adding or deleting an element, iterators on the set are not invalidated (unless the iterators were pointing on the deleted element). In the following sections we will consider all sets constructed with the template : <Key, Compare, Alloc> where Key is the key type, Compare is the function used to compare two keys and Alloc is the set allocator. The allocator is optionnal. The set is implemented using a red-black tree, thus many set types depending on how this tree is created.

10.2
typedef typedef typedef typedef

Set types
Key key type; Key value type; Compare key compare; Compare value compare;

A set container has the following types :

/* This type is private */ typedef rb tree<key type, value type, Identity<value type>, key compare, A> Rep type; /* This member is private, it is the true set content */ Rep type M t; /* Set types are dened using Rb tree types (contained in tree.h) */ typedef typename Rep type::const pointer pointer; typedef typename Rep type::const pointer const pointer; typedef typename Rep type::const reference reference; typedef typename Rep type::const reference const reference; typedef typename Rep type::const iterator iterator; typedef typename Rep type::const iterator const iterator; typedef typename Rep type::const reverse iterator iterator; typedef typename Rep type::const reverse iterator const iterator; typedef typename Rep type::size type size type;

129

The C++ STL

typedef typename Rep type::dierence type dierence type; typedef typename Rep type::allocator type allocator type;

10.3

Set constructors

A set container has the following constructors : /* Calls the default constructor of Compare and allocator type */ set(); explicit set(const Compare& comp, const allocator type& a = allocator type()); /* Fills the set with elements between rst and last */ template<class InputIterator> set(InputIterator rst, InputIterator last); template<class InputIterator> set(InputIterator rst, InputIterator last, const Compare& comp, const allocator type& a = allocator type()); /* Copy constructor */ set(const set<Key, Compare, Alloc>& x);

10.4

Set destructor

A set container uses the default destructor (it calls the destructor of rb tree ).

10.5

Set operators

A set container has the following operators : /* Copy operator */ set<Key, Compare, Alloc>& operator=(const set<Key, Compare, Alloc>& x); /* Calls rb tree operators */ friend bool operator==(const set& s1, const set& s2); friend bool operator<(const set& s1, const set& s2);

10.6

Set iterators

A set container has the following iterators : /* Returns an iterator on the rst element */ const iterator begin() const; 130

The C++ STL

/* Returns an iterator on the element following the last */ const iterator end() const; /* Returns an iterator on the last element */ const reverse iterator rbegin() const; /* Returns an iterator on the element preceding the rst */ const reverse iterator rend() const;

10.7

Set size and capacity

A set size and capacity can be checked and changed using those functions : /* The number of element */ size type size() const; /* The largest possible size of this set (based on the size of elements type) */ size type max size() const;

/* Returns true if this set contains no element, in this case begin() == end() */ bool empty() const;

10.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : /* Returns a pair composed with an iterator on the new element and a bool. The bool is true if the element was already in the set or false in other case */ pair<iterator, bool> insert(const value type& x); /* Returns an iterator on the new element */ iterator insert(iterator pos, const value type& x); /* Inserts the element between rst and last */ template <class InputIterator> void insert(InputIterator rst, InputIterator last); /* Erases the element at pos */ void erase(iterator pos); /* Returns the number of element deleted (1 if there was an element x or 0 in other case) */ size type erase(const key type& x); /* Erases the element between rst and last */ void erase(iterator rst, iterator last);

131

The C++ STL

/* Empties the set */ void clear();

10.9

Misc functions

The set class has those functions too : /* Returns an iterator on x */ iterator nd(const key type& x) const; /* Counts the number of x in this set (0 or 1) */ size type count(const key type& x) const; /* Returns an iterator on the rst element whose key is not less than x */ iterator lower bound(const key type& x) const; /* Returns an iterator on the rst element whose key is greater the x */ iterator upper bound(const key type& x) const; /* Returns a pair composed by the lower bound() and the upper bound() */ pair<iterator, iterator> equal range(const key type& x) const; /* Swaps the content of this set with the content of x */ void swap(set<Key, Compare, Alloc>& x); /* Returns this set allocator */ allocator type get allocator() const; /* Returns this set key or value comparator */ key compare key comp() const; value compare value comp() const;

10.10

Set table exemple

Here is an example of how to use a set table. #include <set> int main(int argc, char* argv[]) { set<int> a set; a set.insert(1); a set.insert(2); a set.insert(1); 132

The C++ STL

/* Displays : 1 2 */ for(set<int>::iterator it = a set.begin(); it != a set.end(); it++) { cout << *it << endl; } cout << a set.erase(1) << endl; /* Displays : 2 */ for(set<int>::iterator it = a set.begin(); it != a set.end(); it++) { cout << *it << endl; } return 0; } /* >>> EOF <<< */

133

Part VI

Container adaptors

134

Chapter 1

Priority queue : <queue>


The priority queue container is a queue that adapts a vector container. It is a rst in, rst out container but the elements are sorted using a compare predicate (given in third parameter of the template). In the following sections we will consider a priority queue constructed with the template <T, Sequence, Compare> where : T is the element type Sequence is the sequence adapted by the priority queue (this parameter is optionnal, by default vector ) Compare is used to make the comparisons between elements (this parameter is optionnal, by default less<Sequence::value type>

Like the queue container, priority queue has no equality operator.

1.1

Priority queue types

A priority queue container has the following types : typedef Sequence::value type value type; typedef Sequence::size type size type; typedef Sequence container type; typedef Sequence::reference reference; typedef Sequence::const reference const reference;

1.2

Priority queue constructors

A priority queue container has the following constructors : priority queue(); explicit priority queue(const Compare& x); priority queue(const Compare& x, const Sequence& s);

135

The C++ STL

/* Inits the priority queue with elements between rst and last */ template <class InputIterator> priority queue(InputIterator rst, InputIterator last); template <class InputIterator> priority queue(InputIterator rst, InputIterator last, const Compare& x); template <class InputIterator> priority queue(InputIterator rst, InputIterator last, const Compare& x, const Sequence& s);

1.3

Priority queue destructor

A priority queue container uses the default destructor (which calls the destructor of the Sequence member).

1.4

Priority queue operators

A priority queue has no comparison operator.

1.5

Priority queue iterators

You cannot iterate on a priority queue container.

1.6

Priority queue size and capacity

A priority queue size and capacity can be checked and changed using those functions : bool empty() const; size type size() const;

1.7

Accessing elements

Elements of a priority queue can be accessed using this function : const reference top() const;

1.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : void push(const value type& x); void pop();

136

Chapter 2

Queue : <queue>
The queue container is a container adaptor. By default, it uses the deque container, but you can build it with any container that provides the same interface. A queue is a rst in rst out container. Last element added is the rst to be removed. In the following sections we will consider a queue constructed with the template <T, Sequence> where : T is the element type Sequence is the sequence adapted by the queue (this parameter is optionnal, by default deque )

The queue operator has no equality operator.

2.1

Queue types

A queue container has the following types : typedef Sequence::value type value type; typedef Sequence::size type size type; typedef Sequence container type; typedef Sequence::reference reference; typedef Sequence::const reference const reference;

2.2

Queue constructors

A queue container has the following constructors : queue(); /* Inits the adapted container with the content of c */ explicit queue(const Sequence& c);

137

The C++ STL

2.3

Queue destructor

A queue container uses the default destructor (which calls the destructor of the Sequence member).

2.4

Queue operators

A queue container has the following operators : /* Those functions use the operator== of the Sequence type */ template <class T, class Sequence> bool operator==(const queue<T, Sequence>& x, const queue<T, Sequence>& y); template <class T, class Sequence> bool operator!=(const queue<T, Sequence>& x, const queue<T, Sequence>& y); /* Those functions use the operator< of the Sequence type */ template <class T, class Sequence> bool operator<(const queue<T, Sequence>& x, const queue<T, Sequence>& y); template <class T, class Sequence> bool operator>(const queue<T, Sequence>& x, const queue<T, Sequence>& y); template <class T, class Sequence> bool operator<=(const queue<T, Sequence>& x, const queue<T, Sequence>& y); template <class T, class Sequence> bool operator>=(const queue<T, Sequence>& x, const queue<T, Sequence>& y);

2.5

Queue iterators

You cannot iterate on a queue container.

2.6

Queue size and capacity

A queue size and capacity can be checked and changed using those functions : bool empty() const; size type size() const;

2.7

Accessing elements

Elements of a queue can be accessed using those functions : reference front(); const reference front() const; reference back();

138

The C++ STL

const reference back() const;

2.8

Inserting and deleting elements

Insertion and deletion are provided by those functions : void push(const value type& x); void pop();

139

Chapter 3

Stack
The stack container is a container adaptor. By default, it uses the deque container, but you can build it with any container that provides the same interface. A stack is a rst in, last out container. The last element addded is the rst to be removed. In the following sections we will consider a stack constructed with the template <T, Sequence> where : T is the element type Sequence is the sequence adapted by the stack (this parameter is optionnal, by default deque ) Like the queue container, stack has no equality operator.

3.1

Stack types

A stack container has the following types : typedef Sequence::value type value type; typedef Sequence::size type size type; typedef Sequence container type; typedef Sequence::reference reference; typedef Sequence::const reference const reference;

3.2

Stack constructors

A stack container has the following constructors : stack(); explicit stack(const Sequence& s);

140

The C++ STL

3.3

Stack destructor

A stack container uses the default destructor (which calls the destructor of the Sequence member).

3.4

Stack operators

A stack container has the following operators : template <class T, class Sequence> bool operator==(const stack<T, Sequence>& x, const stack<T, Sequence>& y); template <class T, class Sequence> bool operator<(const stack<T, Sequence>& x, const stack<T, Sequence>& y); /* Calls operator== */ template <class T, class Sequence> bool operator!=(const stack<T, Sequence>& x, const stack<T, Sequence>& y); /* Call operator< */ template <class T, class Sequence> bool operator>(const stack<T, Sequence>& x, const stack<T, Sequence>& y); template <class T, class Sequence> bool operator>=(const stack<T, Sequence>& x, const stack<T, Sequence>& y); template <class T, class Sequence> bool operator<=(const stack<T, Sequence>& x, const stack<T, Sequence>& y);

3.5

Stack iterators

You cannot iterate on a stack container.

3.6

Stack size and capacity

A stack size and capacity can be checked and changed using those functions : bool empty() const; size type size();

3.7

Accessing elements

Elements of a stack can be accessed using those functions : reference top(); const reference top() const;

3.8

Inserting and deleting elements

Insertion and deletion are provided by those functions :

141

The C++ STL

void push(const value type& x); void pop();

142

Part VII

Functors

143

Chapter 1

Introduction on functors
A functor (also called a function object), is an object that can be called as if it was a function. Generally speaking, a functor is an object that denes operator(). But it can also be a normal function or even a function pointer (called respectively Generator and Unary function or Binary function ). The STL uses only three types of functors, depending on the number of argument used to call them : no argument, one or two. An Adaptable function is an object that can be used as a function but is, in fact, an object, with operator() overloaded and nested argument and return types. Functors that return a boolean value are called Predicate. They are divided into two types of predicate : Predicate and Binary predicate. The rst is an unary functor and the second is a binary functor. On the following sections we will describe the functors provided by the C++ STL. All STL functors can be used including the functionnal header.

144

Chapter 2

Unary function
unary function is the type inherited by all unary functors : template <class Arg, class Result> struct unary function { typedef Arg argument type; typedef Result result type; };

145

Chapter 3

logical not
logical not is a unary function. It takes an object of type T and returns the value of a logical not on that object (using T::operator! ). template <class T> struct logical not : public unary function<T, bool> { bool operator()(const T& x) const; };

146

Chapter 4

Binary function
binary function is the type inherited by all binary functors : template <class Arg1, class Arg2, class Result> struct binary function { typedef Arg1 rst argument type; typedef Arg2 second argument type; typedef Result result type; };

147

Chapter 5

plus
plus is a binary function. It takes two objects of type T, say x and y, and returns x + y : template <class T> struct plus : public binary function<T, T, T> { T operator()(const T& x, const T& y) const; };

148

Chapter 6

minus
minus is a binary function. It takes two objects of type T, say x and y, and returns x - y : template <class T> struct minus : public binary function<T, T, T> { T operator()(const T& x, const T& y) const; };

149

Chapter 7

multiplies
multiplies is a binary function. It takes two objects of type T, say x and y, and returns x * y : template <class T> struct multiplies : public binary function<T, T, T> { T operator()(const T& x, const T& y) const; };

150

Chapter 8

divides
divides is a binary function. It takes two objects of type T, say x and y, and returns x / y : template <class T> struct divides : public binary function<T, T, T> { T operator()(const T& x, const T& y) const; };

151

Chapter 9

modulus
modulus is a binary function. It takes two objects of type T, say x and y, and returns x % y : template <class T> struct modulus : public binary function<T, T, T> { T operator()(const T& x, const T& y) const; };

152

Chapter 10

negate
negate is an unary function. It takes one object of type T, say x, and returns - x : template <class T> struct negate : public unary function<T, T> { T operator()(const T& x) const; };

153

Chapter 11

equal to and not equal to


equal to is a binary function. It takes two objects of type T and returns true if they are equal (using T::operator== ) or false otherwise : template <class T> struct equal to : public binary function<T, T,bool> { bool operator()(const T& x, const T& y) const; }; not equal to is like equal to but returns true if the two objects are dierent (using T::operator!= ) or false otherwise : template <class T> struct not equal to : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; };

154

Chapter 12

less and greater


less is a binary function. It takes two objects of type T, say x and y, and returns true if x < y (using T::operator<) or false otherwise. less equal returns true if x <= y (using T::operator<=). greater does the same thing than less but returns true if x > y (using T::operator>) or false otherwise. greater equal returns true if x >= y (using T::operator>=). template <class T> struct less : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; }; template <class T> struct greater : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; }; template <class T> struct greater equal : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; }; template <class T> struct less equal : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; };

155

Chapter 13

logical and and logical or


logical and is a binary function. It takes two objects of type T and returns the value of a logical and between the two objects (using T::operator&& ). logical or uses T::operator|| : template <class T> struct logical and : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; }; template <class T> struct logical or : public binary function<T, T, bool> { bool operator()(const T& x, const T& y) const; };

156

Chapter 14

binder1st and binder2nd


binder1st and binder2nd transform an adaptable binary function into an adaptable unary function by setting one of the function parameter : the rst for binder1st and the second for binder2nd. Often the constructor of those functors are not called : instead the helper functions bind1st and bind2nd are used : template <class Operation> class binder1st : public unary function<typename Operation::second argument type, typename Operation::result type> { protected: Operation op; typename Operation::rst argument type value; public: binder1st(const Operation& x, const typename Operation::rst argument type& y); operator()(const typename Operation::second argument type& x) const; typename Operation::result type }; template <class Operation, class T> binder1st<Operation> bind1st(const Operation& oper, const T& x); /* bind2nd */ template <class Operation> class binder2nd : public unary function<typename Operation::rst argument type, typename Operation::result type> { protected: Operation op; typename Operation::second argument type value; public: binder2nd(const Operation& x, const typename Operation::second argument type& y); operator()(const typename Operation::rst argument type& x) const; typename Operation::result type }; 157

The C++ STL

template <class Operation, class T> binder2nd<Operation> bind2nd(const Operation& oper, const T& x);

14.1

Example

158

Chapter 15

ptr fun, pointer to unary function and pointer to binary function


pointer to unary function and pointer to binary function are types to create adaptable functions. Often they are not used directly, but by calling ptr fun. ptr fun is used to create a function pointer adaptor using a function pointer. It returns either a pointer to unary function or a pointer to binary function depending of its argument type : template <class Arg, class Result> class pointer to unary function : public unary function<Arg, Result> { protected: Result (*ptr)(Arg); public: pointer to unary function(); explicit pointer to unary function(Result (*x)(Arg)); Result operator()(Arg x) const; }; template <class Arg1, class Arg2, class Result> class pointer to binary function : public binary function<Arg1, Arg2, Result> { protected: Result (*ptr)(Arg1, Arg2); public: pointer to binary function(); explicit pointer to binary function(Result (*x)(Arg1, Arg2)); Result operator()(Arg1 x, Arg2 y) const; }; /* ptr fun */ template <class Arg, class Result> 159

The C++ STL

pointer to unary function<Arg, Result> ptr fun(Result (*x)(Arg)); template <class Arg1, class Arg2, class Result> pointer to binary function<Arg1, Arg2, Result> ptr fun(Result (*x)(Arg1, Arg2));

15.1

Examples

160

Chapter 16

unary negate and binary negate


unary negate is a functor construted by passing it a Unary predicate, say pred. When applying the constructed unary negate it is equivalent to call !pred. binary negate does the same thing than unary negate but with a Binary predicate : unary negate and binary negate are easily constructed by calling the not1 and not2 functions. template <class Predicate> class unary negate : public unary function<typename Predicate::argument type, bool> { protected: Predicate pred; public: explicit unary negate(const Predicate& pred); /* Returns !pred(x) */ bool operator()(const typename Predicate::argument type& x) const; }; template <class Predicate> unary negate<Predicate> not1(const Predicate& pred); /* binary negate */ template <class Predicate> class binary negate : public binary function<typename Predicate::rst argument type, typename Predicate::second argument type, bool> { protected: Predicate pred; public: explicit binary negate(const Predicate& pred); /* Returns !pred(x, y) */ bool operator()(const typename Predicate::rst argument type& x, const typename Predicate::second argument type& y) const;

161

The C++ STL

}; template <class Predicate> binary negate<Predicate> not2(const Predicate& pred);

16.1

Example

162

Chapter 17

Member function adaptors


All member function adaptors allow you to create a functor which will call a member function when using its operator(). Thus, you can use a member function as if it was a normal function. There are 16 functors in this family depending on the form of the member function : member function taking no arguments or one argument call through pointer of through reference member function returning a void type or member function returning non-void type1 const member function or non-const member function Often the constructor of those functors are not called : instead the helper functions mem fun and mem fun ref provides instances of member function adaptors. template <class Ret, class T> class mem fun t : public unary function<T*, Ret> { public: explicit mem fun t(Ret (T::*pf)()); Ret operator()(T* p) const; }; template <class Ret, class T> class const mem fun t : public unary function<const T*, Ret> { public: explicit const mem fun t(Ret (T::*pf)() const); Ret operator()(const T* p) const; };

template <class Ret, class T> class mem fun ref t : public unary function<T, Ret> { public:
1 According to the draft those cases should be handled the same way. But you can use member function returning void type only if your compiler supports partially specialized templates.

163

CHAPTER 17. MEMBER FUNCTION ADAPTORS

explicit mem fun ref t(Ret (T::*pf)()); Ret operator()(T& r) const; }; template <class Ret, class T> class const mem fun ref t : public unary function<T, Ret> { public: explicit const mem fun ref t(Ret (T::*pf)() const); Ret operator()(const T& r) const; }; template <class Ret, class T, class Arg> class mem fun1 t : public binary function<T*, Arg, Ret> { public: explicit mem fun1 t(Ret (T::*pf)(Arg)); Ret operator()(T* p, Arg x) const; }; template <class Ret, class T, class Arg> class const mem fun1 t : public binary function<const T*, Arg, Ret> { public: explicit const mem fun1 t(Ret (T::*pf)(Arg) const); Ret operator()(const T* p, Arg x) const; }; template <class Ret, class T, class Arg> class mem fun1 ref t : public binary function<T, Arg, Ret> { public: explicit mem fun1 ref t(Ret (T::*pf)(Arg)); Ret operator()(T& r, Arg x) const; }; template <class Ret, class T, class Arg> class const mem fun1 ref t : public binary function<T, Arg, Ret> { public: explicit const mem fun1 ref t(Ret (T::*pf)(Arg) const); Ret operator()(const T& r, Arg x) const; }; template <class T> class mem fun t<void, T> : public unary function<T*, void> { public: explicit mem fun t(void (T::*pf)()); void operator()(T* p) const; }; template <class T> class const mem fun t<void, T> : public unary function<const T*, void> 164

CHAPTER 17. MEMBER FUNCTION ADAPTORS

{ public: explicit const mem fun t(void (T::*pf)() const); void operator()(const T* p) const; }; template <class T> class mem fun ref t<void, T> : public unary function<T, void> { public: explicit mem fun ref t(void (T::*pf)()); void operator()(T& r) const; }; template <class T> class const mem fun ref t<void, T> : public unary function<T, void> { public: explicit const mem fun ref t(void (T::*pf)() const); void operator()(const T& r) const; }; template <class T, class Arg> class mem fun1 t<void, T, Arg> : public binary function<T*, Arg,void> { public: explicit mem fun1 t(void (T::*pf)(Arg)); void operator()(T* p, Arg x) const; }; template <class T, class Arg> class const mem fun1 t<void, T, Arg> : public binary function<const T*, Arg, void> { public: explicit const mem fun1 t(void (T::*pf)(Arg) const); void operator()(const T* p, Arg x) const; }; template <class T, class Arg> class mem fun1 ref t<void, T, Arg> : public binary function<T, Arg, void> { public: explicit mem fun1 ref t(void (T::*pf)(Arg)); void operator()(T& r, Arg x) const; }; template <class T, class Arg> class const mem fun1 ref t<void, T, Arg> : public binary function<T, Arg, void> { public: explicit const mem fun1 ref t(void (T::*pf)(Arg) const); void operator()(const T& r, Arg x) const; };

165

The C++ STL

/* Helper functions */ template <class Ret, class T> mem fun t<Ret, T> mem fun(Ret (T::*f)()); template <class Ret, class T> const mem fun t<Ret, T> mem fun(Ret (T::*f)() const); template <class Ret, class T> mem fun ref t<Ret, T> mem fun ref(Ret (T::*f)()); template <class Ret, class T> const mem fun ref t<Ret, T> mem fun ref(Ret (T::*f)() const); template <class Ret, class T, class Arg> mem fun1 t<Ret, T, Arg> mem fun(Ret (T::*f)(Arg)); template <class Ret, class T, class Arg> const mem fun1 t<Ret, T, Arg> mem fun(Ret (T::*f)(Arg) const); template <class Ret, class T, class Arg> mem fun1 ref t<Ret, T, Arg> mem fun ref(Ret (T::*f)(Arg)); template <class Ret, class T, class Arg> const mem fun1 ref t<Ret, T, Arg> mem fun ref(Ret (T::*f)(Arg) const);

17.1

Example

166

Part VIII

Misc

167

Chapter 1

auto ptr

168

Part IX

Frequently Asked Question

169

Chapter 1

FAQ about iterators


1 - But damned, why must I write this dusty template type. I know on which vector I will use my iterator, I know which data type this vector is containing. Why must I specify it again in the iterator declaration ? A good answer to this question is : Go on page 82 and look at the iterator type. As you can see the value type of the vector is used. So, how can your compiler know what to put in this type declaration if you do not tell him ? 2 - But I use an object oriented language where I do not have to do this type of thing. This language, which name comes from a coee (or something coming from Smalltalk family), allows me to play with the vectors without knowing the type(s) contained in it. Why cant I do the same thing with the C++ iterators ? It is because all C++ class does not inherit from a same great elder parent class (usually called Object or something like that). However, the C++ provides the templates to allow you to use multiple types with a same implementation. There are many reasons, but we are not here to discuss the advantage of one approach over the other. The thing is that , you are supposed to know the type contained in your container and declare you iterator keeping this type in mind. 3 - But why cant I use the same iterator type for all container. For example, if I have a vector<int> and a list<int>, I should only write : iterator<int> and reuse my iterator while doing something on the vector or on the list. Why cant I do that ?

4 - I dont feel right with all these templates around me. Id rather use the size of my container to go through it. Why do I have to use templates when I can make it more simple ? Yes, you can use something like : vector<int> v;

170

CHAPTER 1. FAQ ABOUT ITERATORS

for(int i = 0; i < v.size(); i++) { // Do something with v[i] } In some cases, iterators are faster. It is because when you use something like operator[], you must go through at least one element (unless you are using the rst). When using an iterator on element, say 19, you just have to increment the iterator from element 18 to element 19. Your iterator was already near the good place, so why restart the search from the beginning of your container ? Moreover, if your iterator is only a pointer, the operators are most likely inlined, so the iterator is as faster as if it was a pointer.

171

Chapter 2

FAQ about containers


1 - Why are queue, priority queue and stack container adaptors and not like all other containers ? It is to follow a basic principle of oriented object programming : reusability. 2 - Reusability ? But wasnt it possible to implement all container using a unique base class ? Or to implement some container, like list, using only one, like vector for example ? The main purpose of the STL is to provide ecient generic classes to be used instead of rewriting yours. It is possible to implement all containers using a base class. It is also possible to implement some containers using others. But it makes the implementation less ecient than those provided by compiler writers. For example, it is hard to use the same base class for all containers without having virtual functions. And virtual functions dont make the code very ecient. Thus, container adaptors are those container that could have been written without losing eciency and with reusing the existing classes.

172

Chapter 3

FAQ about algorithms

173

Chapter 4

FAQ about relations between C and C++


1 - What is the type of a pointer on a member function ?

2 - Can I use a pointer on a member function where a pointer on traditionnal function is required (for example, to use it in a callback or something like that) ?

174

Part X

GNU Free Documentation License

175

Chapter 1

GNU Free Documentation License


Version 1.2, November 2002 Copyright c 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

PREAMBLE
The purpose of this License is to make a manual, textbook, or other functional and useful document free in the sense of freedom: to assure everyone the eective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modications made by others. This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software. We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

1.1

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you. You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law. A Modied Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modications and/or translated into another language. A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Documents overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary

176

The C++ STL

Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them. The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not t the above denition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none. The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words. A Transparent copy of the Document means a machine-readable copy, represented in a format whose specication is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent le format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modication by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not Transparent is called Opaque. Examples of suitable formats for Transparent copies include plain ASCII without markup, A Texinfo input format, L TEX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modication. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only. The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the works title, preceding the beginning of the body of the text. A section Entitled XYZ means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specic section name mentioned below, such as Acknowledgements, Dedications, Endorsements, or History.) To Preserve the Title of such a section when you modify the Document means that it remains a section Entitled XYZ according to this denition. The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no eect on the meaning of this License.

1.2

VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 1.3. You may also lend copies, under the same conditions stated above, and you may publicly display copies.

177

The C++ STL

1.3

COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Documents license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: FrontCover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects. If the required texts for either cover are too voluminous to t legibly, you should put the rst ones listed (as many as t reasonably) on the actual cover, and continue the rest onto adjacent pages. If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public. It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

1.4

MODIFICATIONS

You may copy and distribute a Modied Version of the Document under the conditions of sections 1.2 and 1.3 above, provided that you release the Modied Version under precisely this License, with the Modied Version lling the role of the Document, thus licensing distribution and modication of the Modied Version to whoever possesses a copy of it. In addition, you must do these things in the Modied Version: A. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. B. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modications in the Modied Version, together with at least ve of the principal authors of the Document (all of its principal authors, if it has fewer than ve), unless they release you from this requirement. C. State on the Title page the name of the publisher of the Modied Version, as the publisher. D. Preserve all the copyright notices of the Document. E. Add an appropriate copyright notice for your modications adjacent to the other copyright notices. F. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modied Version under the terms of this License, in the form shown in the Addendum below.

178

The C++ STL

G. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Documents license notice. H. Include an unaltered copy of this License. I. Preserve the section Entitled History, Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modied Version as given on the Title Page. If there is no section Entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modied Version as stated in the previous sentence. J. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. K. For any section Entitled Acknowledgements or Dedications, Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. L. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. M. Delete any section Entitled Endorsements. Such a section may not be included in the Modied Version. N. Do not retitle any existing section to be Entitled Endorsements or to conict in title with any Invariant Section. O. Preserve any Warranty Disclaimers. If the Modied Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modied Versions license notice. These titles must be distinct from any other section titles. You may add a section Entitled Endorsements, provided it contains nothing but endorsements of your Modied Version by various partiesfor example, statements of peer review or that the text has been approved by an organization as the authoritative denition of a standard. You may add a passage of up to ve words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modied Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one. The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modied Version.

1.5

COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms dened in section 1.4 above for modied versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodied, and list them all as

179

The C++ STL

Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers. The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but dierent contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work. In the combination, you must combine any sections Entitled History in the various original documents, forming one section Entitled History; likewise combine any sections Entitled Acknowledgements, and any sections Entitled Dedications. You must delete all sections Entitled Endorsements.

1.6

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects. You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

1.7

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an aggregate if the copyright resulting from the compilation is not used to limit the legal rights of the compilations users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document. If the Cover Text requirement of section 1.3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Documents Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

1.8

TRANSLATION

Translation is considered a kind of modication, so you may distribute translations of the Document under the terms of section 1.4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail. If a section in the Document is Entitled Acknowledgements, Dedications, or History, the requirement (section 1.4) to Preserve its Title (section 1.1) will typically require changing the actual title.

180

The C++ STL

1.9

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

1.10

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may dier in detail to address new problems or concerns. See http://www.gnu.org/copyleft/. Each version of the License is given a distinguishing version number. If the Document species that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specied version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents


To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page: Copyright c YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled GNU Free Documentation License. If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the with...Texts. line with this: with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation. If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

181

You might also like