Dinkum C++11 Libraries

Table of Contents · Introduction · Standard C++ Library · Standard C Library · ISO Technical Reports · C++11 Library · Additional Libraries · Compatibility Extensions · Embedded C++ Library · C Locales · Overviews · This Implementation

The Dinkum C++11 Libraries are organized into a number of headers, files that you include in your program to declare or define library facilities. Thus, most of the material in this Library Reference is organized by headers, listed below to simplify top-down searching. To search bottom up for a specific name or term, see the Index.

C++ Headers:

Added C++11 headers:

· <atomic> · <chrono> · <codecvt> · <condition_variable> · <cstdalign> · <forward_list> · <future> · <initializer_list> · <mutex> · <ratio> · <scoped_allocator> · <system_error> · <thread> · <typeindex>

Added Dinkumware headers:

· "Dinkum/allocators" · "Dinkum/threads/condition" · "Dinkum/threads/exceptions" · "Dinkum/threads/mutex" · "Dinkum/threads/once" · "Dinkum/threads/recursive_mutex" · "Dinkum/threads/tss" · "Dinkum/codecvt/wbuffer" · "Dinkum/codecvt/wstring" · "Dinkum/threads/xtime"

C++ Code Conversion Headers (in Dinkum/codecvt):

"8859_1" · "8859_2" · "8859_3" · "8859_4" · "8859_5" · "8859_6" · "8859_7" · "8859_8" · "8859_9" · "8859_10" · "8859_13" · "8859_14" · "8859_15" · "8859_16" · "baltic" · "big5" · "cp037" · "cp1006" · "cp1026" · "cp1250" · "cp1251" · "cp1252" · "cp1253" · "cp1254" · "cp1255" · "cp1256" · "cp1257" · "cp1258" · "cp424" · "cp437" · "cp500" · "cp737" · "cp775" · "cp850" · "cp852" · "cp855" · "cp856" · "cp857" · "cp860" · "cp861" · "cp862" · "cp863" · "cp864" · "cp865" · "cp866" · "cp869" · "cp874" · "cp875" · "cp932" · "cp936" · "cp949" · "cp950" · "cyrillic" · "ebcdic" · "euc" · "euc_0208" · "gb12345" · "gb2312" · "greek" · "iceland" · "jis" · "jis0201" · "jis_0208" · "ksc5601" · "latin2" · "one_one" · "roman" · "sjis" · "sjis_0208" · "turkish" · "utf16" · "utf8" · "utf8_utf16"

C Headers:

<assert.h> · <complex.h> · <ctype.h> · <errno.h> · <fenv.h> · <float.h> · <inttypes.h> · <iohw.h> · <iso646.h> · <limits.h> · <locale.h> · <math.h> · <setjmp.h> · <signal.h> · <stdalign.h> · <stdarg.h> · <stdbool.h> · <stddef.h> · <stdfix.h> · <stdint.h> · <stdio.h> · <stdlib.h> · <string.h> · <tgmath.h> · "Dinkum/threads/threads.h" · <time.h> · <uchar.h> · <wchar.h> · <wctype.h> · "Dinkum/threads/xtime.h"

Overviews:

C++ Library Overview · C Library Overview · Characters · Files and Streams · Formatted Output · Formatted Input · Locale Definitions · STL Conventions · STL Containers · Random Number Generators · Regular Expressions · Thread Safety

Introduction

The Dinkum C++11 Libraries are a collection of several C and C++ libraries, all based on ISO standards. These libraries include a large number of functions that perform essential services such as input/output and storage allocation. They also provide efficient implementations of frequently used operations. Numerous other function and class definitions accompany these functions to help you to make better use of the library. In one coherent package, you get:

A completely conforming implementation of the Standard C++ library, ISO/IEC 14882:1998, as corrected through 2003, aka C++03.
The additions to the Standard C++ library mandated by C++11, the revised C++ Standard.
A completely conforming implementation of the Standard C library ISO/IEC 9899:1999, as corrected through 2003.
A completely conforming implementation of the C++ Library Technical Report #1, TR19768, or simply TR1 for short, which adds considerable functionality to the Standard C++ library.
A completely conforming implementation of the libraries for all other C and C++ Technical Reports approved and corrected through 2009.
Useful additions to the Standard C and C++ libraries to facilitate writing multithreaded code, converting between various forms of Unicode, and managing storage for containers.
Common extensions to the Standard C and C++ libraries to simplify adapting code written for Linux and Windows, for open-source Standard C++ libraries, and for pre-standard dialects.
A complete implementation of the Embedded C++ library, the most widely used C++ subset in embedded systems programming, that can also interoperate with the Standard Template Library (STL).
Dozens of definitions for C locales, so that the Standard C library can adapt to all major American and European cultures.

The Libraries have been tested on a variety of compilers:

Microsoft Visual C++ compilers from V6 onward.
GCC compilers from V3 onward.
Compilers that use the front end from Edison Design Group (EDG).

Note that not all compilers support the language features required to support all features in the Dinkum C++11 Libraries. The Library often provides reasonable alternative forms to avoid missing language features, but that is not always possible. As a general rule, you can expect reasonably complete library functionality when using Microsoft Visual C++ compilers from V10 onward, GCC compilers from V4.0 onward, and all compilers using the EDG front end.

Standard C++ Library

The Standard C++ library as revised through 2003 consists of 51 headers. Of these, 16 constitute the Standard Template Library, or STL. These are indicated below with the notation (STL):

<algorithm> -- (STL) for defining numerous templates that implement useful algorithms
<bitset> -- for defining a template class that administers sets of bits
<complex> -- for defining a template class that supports complex arithmetic
<deque> -- (STL) for defining a template class that implements a deque container
<exception> -- for defining several functions that control exception handling
<fstream> -- for defining several iostreams template classes that manipulate external files
<functional> -- (STL) for defining several templates that help construct predicates for the templates defined in <algorithm> and <numeric>
<iomanip> -- for declaring several iostreams manipulators that take an argument
<ios> -- for defining the template class that serves as the base for many iostreams classes
<iosfwd> -- for declaring several iostreams template classes before they are necessarily defined
<iostream> -- for declaring the iostreams objects that manipulate the standard streams
<istream> -- for defining the template class that performs extractions
<iterator> -- (STL) for defining several templates that help define and manipulate iterators
<limits> -- for testing numeric type properties
<list> -- (STL) for defining a template class that implements a doubly linked list container
<locale> -- for defining several classes and templates that control locale-specific behavior, as in the iostreams classes
<map> -- (STL) for defining template classes that implement associative containers that map keys to values
<memory> -- (STL) for defining several templates that allocate and free storage for various container classes
<new> -- for declaring several functions that allocate and free storage
<numeric> -- (STL) for defining several templates that implement useful numeric functions
<ostream> -- for defining the template class that performs insertions
<queue> -- (STL) for defining a template class that implements a queue container
<set> -- (STL) for defining template classes that implement associative containers
a singly linked list container
<sstream> -- for defining several iostreams template classes that manipulate string containers
<stack> -- (STL) for defining a template class that implements a stack container
<stdexcept> -- for defining several classes useful for reporting exceptions
<streambuf> -- for defining template classes that buffer iostreams operations
<string> -- for defining a template class that implements a string container
<strstream> -- for defining several iostreams classes that manipulate in-memory character sequences
<typeinfo> -- for defining class type_info, the result of the typeid operator
<utility> -- (STL) for defining several templates of general utility
<valarray> -- for defining several classes and template classes that support value-oriented arrays
<vector> -- (STL) for defining a template class that implements a vector container

The Standard C++ library works in conjunction with the headers from the Standard C library, sometimes with small alterations. The headers come in two forms, new (C++) and traditional (C). The new-form headers are:

<cassert> -- for enforcing assertions when functions execute
<ccomplex> -- for performing complex arithmetic
<cctype> -- for classifying characters
<cerrno> -- for testing error codes reported by library functions
<cfenv> -- for controlling IEEE-style floating-point arithmetic
<cfloat> -- for testing floating-point type properties
<cinttypes> -- for converting various integer types
<ciso646> -- for programming in ISO 646 variant character sets
<climits> -- for testing integer type properties
<clocale> -- for adapting to different cultural conventions
<cmath> -- for computing common mathematical functions
<csetjmp> -- for executing nonlocal goto statements
<csignal> -- for controlling various exceptional conditions
<cstdalign.h -- for ensuring that alignas is defined
<cstdarg> -- for accessing a varying number of arguments
<cstdbool -- for defining a convenient Boolean type name and constants
<cstddef> -- for defining several useful types and macros
<cstdint -- for defining various integer types with size constraints
<cstdio> -- for performing input and output
<cstdlib> -- for performing a variety of operations
<cstring> -- for manipulating several kinds of strings
<ctgmath -- for defining generic forms of math functions
<ctime> -- for converting between various time and date formats
<cwchar> -- for manipulating wide streams and several kinds of strings
<cwctype> -- for classifying wide characters

Standard C Library

The traditional Standard C library headers, which is also a part of the Standard C++ Library, are:

<assert.h> -- for enforcing assertions when functions execute
<complex.h> -- for performing complex arithmetic
<ctype.h> -- for classifying characters
<errno.h> -- for testing error codes reported by library functions
<fenv.h> -- for controlling IEEE-style floating-point arithmetic
<float.h> -- for testing floating-point type properties
<inttypes.h> -- for converting various integer types
<iohw.h> [added with TR18015/TR18037] -- for writing portable I/O hardware drivers in C
<iso646.h> -- for programming in ISO 646 variant character sets
<limits.h> -- for testing integer type properties
<locale.h> -- for adapting to different cultural conventions
<math.h> -- for computing common mathematical functions
<setjmp.h> -- for executing nonlocal goto statements
<signal.h> -- for controlling various exceptional conditions
<stdalign.h> -- for ensuring that alignas is defined [added with C11]
<stdarg.h> -- for accessing a varying number of arguments
<stdbool.h> -- for defining a convenient Boolean type name and constants
<stddef.h> -- for defining several useful types and macros
<stdint.h> -- for defining various integer types with size constraints
<stdio.h> -- for performing input and output
<stdlib.h> -- for performing a variety of operations
<string.h> -- for manipulating several kinds of strings
<tgmath.h> -- for declaring various type-generic math functions
<time.h> -- for converting between various time and date formats
<uchar.h> [added with TR19769] -- for manipulating 16-bit and 32-bit UNICODE wide characters
<wchar.h> -- for manipulating wide streams and several kinds of strings
<wctype.h> -- for classifying wide characters

ISO Technical Reports

The Dinkum C++11 Libraries include several headers, not required by the C Standard or the C++ Standard, but defined in ISO Technical Reports:

<hardware> [added with TR18015] -- for writing portable I/O hardware drivers in C++
<iohw.h> [added with TR18015/TR18037] -- for writing portable I/O hardware drivers in C
<stdfix.h> [added with TR18037] -- for performing fixed-point arithmetic in C
<uchar.h> [added with TR19769] -- for manipulating 16-bit and 32-bit Unicode wide characters in C

By far the largest library addition after C++03 is specified by TR19768, usually referred to as C++ Library Technical Report #1, or TR1. The additions are extensive. Some contribute to existing headers, others take the form of new headers. The contributions from TR1 to existing headers are in:

<functional> -- for defining several templates that help construct predicates for the templates defined in <algorithm> and <numeric>
<memory> -- for defining templates that use reference counting to manage resources
<utility> -- for defining two tuple-like templates that provide information about the contents of instances of pair.

The new headers added with TR1 are:

<cmath> and <math.h> -- for computing a number of additional math functions, usually called "special math" functions (such as Bessel functions), now a separate ISO Standard IS24747
<array> -- for defining a fixed-size array with a container-like interface
<random> -- for defining random number generators
<regex> -- for defining a regular-expression matcher
<tuple> -- for defining an ordered collection of subobjects
<type_traits> -- for accessing detailed type information at compile time to support generic programming
<unordered_map> -- (STL) for defining template classes that implement unordered associative containers that map keys to values
<unordered_set> -- (STL) for defining template classes that implement unordered associative containers

C++11 Library

And, beginning wth the revised C++ Standard, usually referred to as C++11, a number of additional headers are added (along with TR1).

<atomic> -- for defining classes and objects that manage atomic data operations
<chrono> -- for defining time points and durations
<codecvt> -- for defining locale facets that convert between different Unicode encodings
<condition_variable> -- for defining classes that manage inter-thread synchronization
<forward_list> -- (STL) for defining a template class that implements a small-footprint singly linked list container
<future> -- for defining classes and objects that simplify running a function in a thread and getting its result in another thread
<initializer_list> -- for describing a brace-enclosed initializer list
<mutex> -- for defining classes that manage mutual exclusion between threads
<ratio> -- for defining templates that implement compile-time rational numbers
<scoped_allocator> -- for wrapping a nest of allocators
<system_error> -- for wrapping low-level system errors
<thread> -- for defining classes and functions to create and manage threads
<typeindex> -- for defining classes and functions to index typeinfo objects

Additional Libraries

The Dinkum C++11 Libraries include several libraries not required by ISO standards, but whose presence are suggested, or even encouraged, by those standards:

The Dinkum Allocators Library provides numerous allocators, template classes modeled after template class allocator. You use these to manage memory for node-based STL containers, such as list and set, when the default allocator doesn't suffice. This Library includes allocators that implement half a dozen different caching strategies, each of which can be qualified by several different synchronization strategies (including none) for multithreading environments.
The Dinkum Conversions Library provides over six dozen code conversion facets, template classes derived from an instantiation of template class codecvt. You use these to convert between multibyte and wide-character encodings while performing file input and output. This Library makes it easy to work with all the popular variants of Unicode, as well as older character encodings that are still in use. It also includes template classes for performing such conversions inside a program, not just when reading and writing files.
The Dinkum Threads Library lets you create and control multiple threads of execution, to take advantage of multithreading environments such as Linux, Unix, and Windows. You get both a C version, modeled cloaely after the facilities in the Posix Standard, and a C++ version, modeled closely after the facilities in the Boost.Threads library. The Library works correctly on both single-processor and multi-processor systems.

Compatibility Extensions

The Dinkum C++11 Libraries include two headers that provide extensions frequently found in other C++ libraries:

<hash_map> -- (STL) for defining template classes that implement hashed associative containers that map keys to values (also includes an STLport-compatible adapter)
<hash_set> -- (STL) for defining template classes that implement hashed associative containers (also includes an STLport-compatible adapter)

Embedded C++ Library

The Dinkum C++11 Libraries include a subset specifically designed for embedded systems programming called the Embedded C++ Library. It conforms to an industry specification developed in 1997 by a consortium of mostly Japanese companies, and has become the subset of choice for most embedded compiler vendors. You can mix STL code with the Embedded C++ Library to write powerful but lean applications in C++.

For clarity, this library is described in a separate Embedded C++ Library Reference.

C Locales

The Standard C library has the ability to adapt at runtime to different locales you can specify in a locale definition file. The Dinkum C++11 Libraries include about five dozen such locale definitions, covering all major American and European cultures, that you can use to tailor a locale definition file for use with executables.

Overviews

Other information on the Standard C and C++ libraries includes several overviews:

C++ Library Overview -- how to use the Standard C++ library, including alternative mechanisms for handling exceptions
C Library Overview -- how to use the Standard C library, including what happens at program startup and at program termination
Characters -- how to write character constants and string literals, and how to convert between multibyte characters and wide characters
Files and Streams -- how to read and write data between the program and files
Formatted Output -- how to generate text under control of a format string
Formatted Input -- how to scan and parse text under control of a format string
STL Conventions -- how to read the descriptions of STL template classes and functions
STL Containers -- how to use an arbitrary STL container template class
Thread Safety -- how to write code that is safe in a multithreaded environment

This Implementation

As much as possible, this Reference indicates any extensions to standard-conforming behavior particular to this implementation. Moreover, even though the C++ Standard is no longer new, not all compilers support all the features described here. Hence, this implementation introduces macros, or alternative declarations, where necessary to provide reasonable substitutes for the capabilities required by the C++ Standard.