Apache C++ Standard Library User's Guide

## 1.5 About This Manual

### 1.5.1 Assumptions

This manual assumes that you are familiar with the basic features of the C++ programming language. If you are new to C++, you may want to start with an introductory text, such as The C++ Programming Language by Bjarne Stroustrup (Addison-Wesley, 1997).

### 1.5.2 Conventions

This manual uses some distinctive terms and conventions.

Abbreviations are common. Template abbreviations are very common, since the C++ Standard Library contains so many long names for class and function templates. For example, in the iostreams part of the documentation, `fstream` stands for `template <class charT, class traits> class basic_fstream`. The term filestream stands for the abstract notion of the file stream class template. `badbit` stands for the state flag `std::ios_base::badbit`.

Hierarchy diagrams use the formal template declarations. In the hierarchy diagrams, the standard UML arrow:

indicates that class B inherits from class A.

The term algorithm indicates functions in the generic algorithms portion of the C++ Standard Library. This is intended to avoid confusion with member functions, argument functions, and user-defined functions.

An empty pair of parentheses `()` follows function names and algorithm names, so as to avoid emphasizing their arguments. Arguments may be omitted for clarity.

An underline character `_` is used as a separator in both class names and function names.

Special fonts set off class names, code samples, and special meanings, as shown in Table 2:.

#### Table 2: Typographic conventions

Convention | Purpose | Example
`Courier` | Code, examples, function names, file names, directory names, and operating system commands. | `return result;`
italic | Conventional uses such as emphasis, titles, and new terms. | A comparison function object is...
bold | Conventional uses such as emphasis. Commands from an interface. | Always read the manual. Click on the OK button.
bold italic | Class names. | priority_queue

Throughout this guide, we use the character `\` to separate directory names. If you use UNIX, change `\` to `/`.

### 1.5.3 Organization

This manual is organized into eight parts:

- Part I, "Introduction," provides overviews of the product, the documentation, and this manual, The Apache C++ Standard Library User Guide.

- Part II, "Fundamentals," explains the fundamental C++ Standard Library concepts of iterators, functions, and predicates.

- Part III, "Containers," gives an overview of the data structures called containers, and devotes a chapter to describing each container in detail, with an example.

- Part IV, "Algorithms," deals with the algorithms, devoting one chapter to the generic algorithms, and another to the generic algorithms specific to ordered collections. Within the two algorithm chapters, each kind of algorithm is explained in its own section, with an example and a reference to the file containing the complete source code.

- Part V, "Special Techniques," describes techniques such as using allocators, building containers and generic algorithms, using the traits technique, and dealing with exceptions.

- Part VI, "Special Classes," devotes a chapter to each of the four unique classes auto_ptr, complex, numeric_limits, and valarray.

- Part VII, "Locales," describes the basics of internationalization. It explains the differences between the C locale and the C++ locale. It defines a C++ locale and a facet, and tells how locales are created, composed, used, and replaced. It includes a complex example of a user-defined facet, which demonstrates how facets can be built and used in conjunction with iostreams.

- Part VIII, "Iostreams," explains the C++ stream input and output facilities commonly called iostreams. Beginning chapters cover the iostreams facility, how it works, and how it should be used; also, the iostreams architecture, its components, and class hierarchy. Middle chapters cover the basic operation of iostreams, and both simple and advanced techniques for extending the iostreams framework. Final chapters describe the main differences between the C++ Standard Library iostreams, the traditional iostreams, and the implementation of iostreams in the Apache C++ Standard Library.

### 1.5.4 Reading Suggestion

The first time you read this manual it may be hard to know where to start. The container definitions form the heart of the library, but you can't really appreciate them without understanding the algorithms that so greatly extend their functionality. On the other hand, you can't really understand the algorithms without some appreciation of the containers.

A good approach is to read Part II Fundamentals carefully. Next, skim the definitions of the containers in Part III Containers and the descriptions of the algorithms in Part IV Algorithms, then go back and read these parts in more detail. You can then proceed to the more specialized areas of the manual.