Dinkum Compleat Libraries

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

The Dinkum Compleat Libraries are organized into a number ofheaders,files that you include in your program todeclare or define library facilities. Thus, most of thematerial 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 theIndex.

C++ Headers:

<algorithm>· "Dinkum/allocators"· <array>· <bitset>· <cassert>· <ccomplex>· <cctype>· <cerrno>· <cfenv>· <cfloat>· <cinttype>· <ciso646>· <climits>· <clocale>· <cmath>· <complex>· "Dinkum/threads/condition"· <csetjmp>· <csignal>· <cstdarg>· <ccstdbool>· <cstddef>· <cstdint>· <cstdio>· <cstdlib>· <cstring>· <ctgmath>· <ctime>· <cwchar>· <cwctype>· <deque>· <exception>· "Dinkum/threads/exceptions"· <fstream>· <fstream.h>· <functional>· <hardware>· <hash_map>· <hash_set>· <iomanip>· <iomanip.h>· <ios>· <iosfwd>· <iostream>· <iostream.h>· <istream>· <iterator>· <limits>· <list>· <locale>· <map>· <memory>· "Dinkum/threads/mutex"· <new>· <new.h>· <numeric>· "Dinkum/threads/once"· <ostream>· <queue>· <random>· "Dinkum/threads/recursive_mutex"· <regex>· <set>· <slist>· <sstream>· <stack>· <stdexcept>· <streambuf>· <string>· <strstream>· "Dinkum/threads/thread"· "Dinkum/threads/tss"· <tuple>· <typeinfo>· <type_traits>· <unordered_map>· <unordered_set>· <utility>· <valarray>· <vector>· "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>· <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· Thread Safety

Introduction

The Dinkum Compleat Libraries are a collection of severalC and C++ libraries, all based on ISO standards.These libraries include a large number of functionsthat perform essential services such as input/outputand 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 theStandard C++ library,ISO/IEC 14882:1998, as corrected through 2003.
A completely conforming implementation of theStandard C libraryISO/IEC 9899:1999, as corrected through 2003.
A completely conforming implementation ofthe 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 librariesfor all otherC and C++ Technical Reportsapproved and corrected through 2005.
Useful additionsto the Standard C and C++ librariesto facilitate writing multithreaded code, converting betweenvarious forms of Unicode, and managing storage for containers.
Common extensionsto the Standard C and C++ libraries to simplifyadapting code written for Linux and Windows,for open-source Standard C++ libraries, and for pre-standard dialects.
A complete implementation of theEmbedded 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 librarycan adapt to all major American and European cultures.

The Dinkum Compleat Libraries provide a rich, high quality, developmentenvorinment across all the most popular computing platforms.In most cases, it can be configured to use either the native C library(for maximum access to traditional, nonstandard library extensions)or the Dinkumware Standard C library (for maximum conformance andportability). Installing the Dinkum Compleat Libraries neveralters any existing compiler or library files; they are packagedas a pure bolt-on. Thus, the Dinkum Compleat Libraries offer a low-riskway to improve practically any platform, and dramatically lower thecost of moving code between platforms.

The Libraries have been tested on a variety of compilers:

Microsoft Visual C++ compilers V6, V7 (.NET), V7.1 (.NET 2003),V8 (.NET 2005), and Embedded Visual C++ compilers from V3 onward.
GCC compilers from V3 onward on PC Linux, Sparc Solaris,Mac OS/X, and Microsoft Windows.
Sun C++ compilers from V5.7 onward on Sparc Solaris.
Compilers that use the front end fromEdison Design Group (EDG).

Many of these compilers have serious deficiencies in the conformance,correctness, and/or performance of their C and C++ libraries.Even those equipped with various versions of Dinkumware C and C++ librariescan benefit from the extra features, latest improvements, and uniformityoffered with the Dinkum Compleat Libraries.

Note that not all compilers support the language featuresrequired to support all features in the Dinkum Compleat Libraries.The Library often provides reasonable alternative formsto avoid missing language features, but that is not always possible.As a general rule, you can expect reasonably complete libraryfunctionality when using Microsoft Visual C++ compilers from V7.1 onward,GCC compilers from V3.0 onward, and all compilers using the EDG front end.Only EDG compilers offer complete Standard C and C++ conformance(when used with Dinkumware libraries),and only EDG V3.5 and later supports fixed-point arithmetic (TR18037).

The Dinkum Compleat Libraries offer a number of unique advantages:

Dinkumware's Standard C++ library is the only such libraryto score near perfect conformance with the C++VS validation suite fromPerennial, Inc..
Dinkumware's Standard C++ library is the only such libraryto support separate compilation of templates(when used with the EDG front end).
Dinkumware's Standard C library is the first such libraryto be validated for perfect compliance with Perennial's CVSAvalidation suite.
Dinkumware's Standard C library is the only such libraryto offer full support for all math functions in all four popularIEC 60559 (IEEE 754) floating-point formats -- 32-bit, 64-bit, 80-bit, and128-bit -- all extensively tested for accuracy and conformanceto optional real and complex floating-point requirements.
Dinkumware's Standard C library is the only C99 librarynot bundled with a specific compiler.
Dinkumware's TR1 (TR19768) library is the onlycomplete implementation, including special math support andC99 library integration.
Dinkumware's fixed-point arithmetic (TR18037) library is the onlysuch library not bundled with a specific compiler.
Dinkumware's Embedded C++ library is the only such libraryto score near perfect conformance with Perennial's EC++VSvalidation suite.
Dinkumware's Embedded C++ library is the only such librarynot bundled with a specific compiler.

Finally, Dinkumware, Ltd. is the onlyremaining independent commercial source for Standard C and C++libraries. You can find bits and pieces availableas open source, with varyingdegrees of quality and varying licenseing restrictions;but only Dinkumware offers the securitythat comes with commercial licensing and support from asingle vendor. The Librarycontains no open source and no code subject torestrictive open source licensing; the entire product iscovered by one comprehensive license agreement.And we ask no additional royalty for the distribution ofexecutables linked with our libraries.

Founded in 1995, Dinkumware, Ltd. supplies the Standard Cand C++ libraries used by the leading compiler vendors forboth desktop and embedded program development. Our OEM customersinclude most major vendors of compilers for desktop andembedded systems program development, includingMicrosoft, IBM, Borland, Green Hills, WindRiver, and manymore. We also license directly to developers through our website, from individuals to shops with hundreds of programmers.Thus, Dinkumware has a well deserved reputation forproducing the highest quality libraries and providing themost comprehensive support available, for customers of allsizes.

Standard C++ Library

The Standard C++ library consists of 51 headers.Of these, 16 constitute theStandard Template Library, orSTL.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 manipulateexternal files
<functional>-- (STL) for defining several templates that help construct predicatesfor 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 formany iostreams classes
<iosfwd>-- for declaring several iostreams template classes before theyare necessarily defined
<iostream>-- for declaring the iostreams objects that manipulate thestandard streams
<istream>-- for defining the template class that performs extractions
<iterator>-- (STL) for defining several templates that help define and manipulateiterators
<limits>-- for testing numeric type properties
<list>-- (STL) for defining a template class that implementsa doubly linked list container
<locale>-- for defining several classes and templates that controllocale-specific behavior, as in the iostreams classes
<map>-- (STL) for defining template classes that implement associative containersthat map keys to values
<memory>-- (STL) for defining several templates that allocate and free storagefor 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 manipulatestring 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-memorycharacter sequences
<typeinfo>-- for defining class type_info, the result of thetypeid operator
<utility>-- (STL) for defining several templates of general utility
<valarray>-- for defining several classes and template classes thatsupport value-oriented arrays
<vector>-- (STL) for defining a template class that implements a vector container

The Standard C++ library works in conjunction with theheaders from theStandard 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
<cinttype.h>-- 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
<cstdarg>-- for accessing a varying number of arguments
<cstdbool.h>-- for defining a convenient Boolean type name and constants
<cstddef>-- for defining several useful types and macros
<cstdint.h>-- 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.h><ctime>-- for converting between various time and date formats
<cwchar>-- for manipulatingwide streams andseveral kinds of strings
<cwctype>-- for classifyingwide characters

Standard C Library

The traditionalStandard C library headers, which isalso 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
<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 manipulatingwide streams andseveral kinds of strings
<wctype.h>-- for classifyingwide characters

ISO Technical Reports

The Dinkum Compleat Libraries includeseveral headers, not required by the C Standard orthe 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, however, comes withTR19768, usually referred to as C++ Library Technical Report #1, orTR1. The additions are extensive.Some contribute to existing headers, others take the form ofnew headers. The contributions from TR1 to existing headers are in:

<cmath> and<math.h>-- for computing a number of additional math functions,usually called "special math" functions(such as Bessel functions)
<functional>-- for defining several templates that help construct predicatesfor 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 informationabout the contents of instances of std::pair.

The new headers added with TR1 are:

<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 tosupport generic programming
<unordered_map>-- (STL) for defining template classes that implement unorderedassociative containers that map keys to values
<unordered_set>-- (STL) for defining template classes that implement unorderedassociative containers

Additional Libraries

The Dinkum Compleat Libraries include several libraries notrequired by ISO standards, but whose presence are suggested,or even encouraged, by those standards:

The Dinkum Allocators Libraryprovides numerous allocators,template classes modeled after template classallocator.You use these to manage memory for node-basedSTL containers, such aslistr andset,when the default allocator doesn't suffice. This Libraryincludes allocators that implement half a dozen differentcaching strategies, each of which can be qualified byseveral different synchronization strategies (including none)for multithreading environments.
The Dinkum Conversions Libraryprovides over six dozen code conversion facets,template classes derived from an instantiation of template classcodecvt.You use these to convert between multibyte and wide-characterencodings while performing file input and output. This Librarymakes 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 conversionsinside a program, not just when reading and writing files.
The Dinkum Threads Librarylets 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 afterthe facilities in thePosixStandard, and a C++ version, modeled closely after thefacilities in theBoost.Threadslibrary. The Library works correctly on both single-processor andmulti-processor systems.

Compatibility Extensions

The Dinkum Compleat Libraries include several headersthat provide extensions frequently found in other C++ libraries:

<hash_map>-- (STL) for defining template classes that implement hashedassociative containers that map keys to values (also includesan STLport-compatible adapter)
<hash_set>-- (STL) for defining template classes that implement hashedassociative containers (also includes an STLport-compatible adapter)
<slist>-- (STL) for defining a template class that implementsa singly linked list container

The Library also includes several headersfor compatibility with traditional (pre-standard) C++ libraries:

<fstream.h>-- for defining several iostreams template classes that manipulateexternal files
<iomanip.h>-- for declaring several iostreams manipulators that take an argument
<iostream.h>-- for declaring the iostreams objects that manipulate thestandard streams
<new.h>-- for declaring several functions that allocate and free storage

Embedded C++ Library

The Dinkum Compleat Libraries include a subset specificallydesigned for embedded systems programming calledthe Embedded C++ Library. It conforms to an industryspecificationdeveloped in 1997 by a consortium of mostly Japanese companies, and hasbecome 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 separateEmbedded C++ Library Reference.

C Locales

The Standard C library has the ability to adapt atruntime to different locales you can specify in alocale definition file. The Dinkum Compleat Librariesinclude about five dozen suchlocale definitions,covering all major American and Europeancultures, that you can use to tailor a locale definition filefor use with executables.

Overviews

Other information on the Standard C and C++ libraries includesseveral overviews:

C++ Library Overview --how to use the Standard C++ library, including alternativemechanisms for handling exceptions
C Library Overview --how to use the Standard C library, including what happens atprogram startup and atprogram termination
Characters --how to writecharacter constants andstring literals, and how toconvert betweenmultibyte characters andwide characters
Files and Streams -- how to read and write data between the program andfiles
Formatted Output -- how to generate text under control of aformat string
Formatted Input -- how to scan and parse text under control of aformat string
STL Conventions -- how to read the descriptions ofSTL template classes and functions
STL Containers -- how to use an arbitrarySTL 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 extensionsto standard-conforming behavior particular to thisimplementation.Moreover, even though the C++ Standardis no longer new, not all compilers support all the featuresdescribed here. Hence, this implementation introduces macros,or alternative declarations, where necessary to provide reasonablesubstitutes for the capabilities required by the C++ Standard.