This chapter is an introduction to the Metrowerks Standard C++ library.
This section introduces you to the definitions, conventions, terminology, and other aspects of the MSL C++ library. The topics discussed include:
This section discusses the meaning of certain terms in the MSL C++ library.
A stream that can seek to any position within the length of the stream. An arbitrary-positional stream is also a repositional stream
Any object which, when treated sequentially, can represent text. A character can be represented by any type that provides the definitions specified.
A class or a type used to represent a character. A character container
class shall be a POD type.
An operator function for equality or relational operators.
A group of library entities directly related as members, parameters, or return types. For example, a class and a related non-member template function entity would referred to as a component.
The specific behavior provided by the implementation, for replacement and handler functions.
A non-reserved function that may be called at various points with a program through supplying a pointer to the function. The definition may be provided by a C++ program.
Templates that take two template arguments: charT and traits. CharT is a character container class, and traits is a structure which defines additional characteristics and functions of the character type.
A class member function other than constructors, assignment, or destructor, that alters the state of an object of the class.
The current value of all non-static class members of an object.
The instantiations of the iostream class templates on the character container class. Traditional iostream classes are regarded as the narrow-oriented iostream classes.
Null Terminated Character Type Sequences. Traditional char strings are NTCTS.
A const member function that accesses the state of an object of the class, but does not alter that state.
A non-reserved C++ function whose definition is provided by a program. Only one definition for such a function is in effect for the duration of the program's execution.
The behavior for any replacement or handler function definition in the program replacement or handler function. If a function defined in a C++ program fails to meet the required behavior when it executes, the behavior is undefined.
A stream that can seek only to a position that was previously encountered.
A function, specified as part of the C++ Standard Library, that must be defined by the implementation. If a C++ program provides a definition for any reserved function, the results are undefined.
A class that encapsulates a set of types and functions necessary for template classes and template functions to manipulate objects of types for which they are instantiated.
The instantiations of the iostream class templates on the character container class wchar_t and the default value of the traits parameter.
Metrowerks Standard Libraries have additional definitions.
MSL C++ Library is multi-thread safe provided that the operating system supports thread-safe system calls. Library has locks at appropriate places in the code for thread safety. The locks are implemented as a mutex class -- the implementation of which may differ from platform to platform.
This ensures that the library is MT-Safe internally. For example, if a buffer is shared between two string class objects (via an internal refcount), then only one string object will be able to modify the shared buffer at a given time.
Thus the library will work in the presence of multiple threads in the same way as in single thread provided the user does not share objects between threads or locks between accesses to objects that are shared.
Conventions used to describe the C++ Standard Library.
This document follows the Standard C++ convention and numbers the library chapters by the sub-clause numbers.
| Chapter |
Description |
Chapter |
Description |
|---|---|---|---|
The Metrowerks Standard Library descriptions include a short description, notes, remarks, cross references and examples of usage.
Some other terminology and conventions used in this reference are:
A letter is any of the 26 lowercase or 26 uppercase letters
The decimal-point character is represented by a period, '.'
A character sequence is an array object of the types char, unsigned char, or signed char.
A character sequence can be designated by a pointer value S that points to its first element.
A null-terminated byte string, or NTBS, is a character sequence whose highest-addressed element with defined content has the value zero (the terminating null character).
The length of an NTBS is the number of elements that precede the terminating null character. An empty NTBS has a length of zero.
3The value of an NTBS is the sequence of values of the elements up to and including the terminating null character.
A static NTBS is an NTBS with static storage duration.
A null-terminated multibyte string, or NTMBS, is an NTBS that consists of multibyte characters,
A static NTMBS is an NTMBS with static storage duration.
A wide-character sequence is an array object of type wchar_t
A wide character sequence can be designated by a pointer value that designates its first element.
A null-terminated wide-character string, or NTWCS, is a wide-character sequence whose highest addressed element has the value zero.
The length of an NTWCS is the number of elements that precede the terminating null wide character.
An empty NTWCS has a length of zero.
The value of an NTWCS is the sequence of values of the elements up to and including the terminating null character.
A static NTWCS is an NTWCS with static storage duration.
Copy constructors, assignment operators, (non-virtual) destructors or virtual destructors that can be generated by default may not be described
To simplify understanding, where objects of certain types are required by the external specifications of their classes to store data. The declarations for such member objects are enclosed in a comment that ends with exposition only, as in:
// streambuf* sb; exposition only
The requirements that apply to the entire C++ Standard library.
The Metrowerks Standard Libraries are organized in the same fashion as the ANSI/ISO C++ Standard.
Definitions are provided for Macros, Values, Types, Templates, Classes, Function and, Objects.
All library entities except macros, operator new and operator
delete are defined within the namespace std or namespaces nested within namespace std.
The components of the MSL C++ Library y are declared or defined in various headers.
| C++ |
Headers |
C++ |
Headers |
| C Style |
Headers |
C Style |
Header |
Except as may be noted, the contents of each C style header cname shall be the same as that of the corresponding header name.h. In the MSL C++ Library the declarations and definitions (except
for names which are defined as macros in C) are within namespace
scope of the namespace std.
NOTE The names defined as macros in C include: assert, errno, offsetof, setjmp, va_arg, va_end, and va_start.
A freestanding implementation has an implementation-defined set of headers. This set shall include at least the following headers.
MSL C++ Freestanding Implementation Headers:
The Metrowerks Standard LIbrary header <cstdlib> includes the functions abort(), atexit(), and exit().
A description of how a C++ program gains access to the facilities of the C++ Standard Library.
A header's contents are made available to a translation unit when it contains the appropriate #include preprocessing directive.
A translation unit shall include a header only outside of any external declaration or definition, and shall include the header lexically before the first reference to any of the entities it declares or first defines in that translation unit.
The Metrowerks Standard C++ Library has external "C++" linkage unless otherwise specified
Objects and functions defined in the library and required by a C++ program are included in the program prior to program startup.
Restrictions on C++ programs that use the facilities of the Metrowerks Standard C++ Library.
Metrowerks Standard Library reserves certain sets of names and function signatures for its implementation.
Names that contains a double underscore (_ _) or begins with an underscore followed by an upper-case letter is reserved to the MSL library for it's use.
Names that begin with an underscore are reserved to the library for use as a name in the global namespace.
User code can safely use macros that are all uppercase characters
and underscores, except for leading underscores. Library code
will either be in namespace std or in namespace Metrowerks. Implementation details in namespace std will be prefixed by a double underscore or an underscore followed
by an uppercase character. Implementation details in namespace Metrowerks are nested in a nested namespace, for example:
Each name from the Metrowerks Standard C library declared with external linkage is reserved to the implementation for use as a name with extern "C" linkage, both in namespace std and in the global namespace.
The behavior of any header file with the same name as a Metrowerks Standard Library public or private header, is undefined.
Virtual member function signatures defined for a base class in the C++ Standard library may be overridden in a derived class defined in the program.
If replacement definition occurs prior to program startup replacement functions are allowed.
A C++ program may provide the definition for any of eight dynamic memory allocation function signatures declared in header <new>.
operator new(size_t)
operator new(size_t, const std::nothrow_t&)
operator new[](size_t)
operator new[](size_t, const std::nothrow_t&)
operator delete(void*)
operator delete(void*, const std::nothrow_t&)
operator delete[](void*)
operator delete[](void*, const std::nothrow_t&)
MSL Standard C++ Library provides default versions of the following handler functions:
unexpected_handler
terminate_handler
A C++ program may install different handler functions during execution, by supplying a pointer to a function defined in the program or the library as an argument to:
set_new_handler
set_unexpected
set_terminate
In certain cases the Metrowerks Standard C++ Library depends on components supplied by a C++ program. If these components do not meet their requirements, t the behavior is undefined.
If a C++ library function is passed incorrect but legal arguments the behavior is undefined.
Metrowerks Standard Library is an ANSI/ISO Conforming implementation as described by the ANSI/ISO Standards in section 17.4.4
Any of the functions defined in the Metrowerks Standard C++ Library may report a failure by throwing an exception. No destructor operation defined in the Metrowerks Standard C++ Library will throw an exception.
The C Style library functions all have a throw() exception-specification. This allows implementations to make performance optimizations based on the absence of exceptions at runtime.
The functions qsort() and bsearch() meet this condition. In particular, they can report a failure to allocate storage by throwing an exception of type bad_alloc, or a class derived from bad_alloc.
The following sections of Standard C++ will not be implemented in the MSL C++ product.
There are minimal areas of the Standard library that depend on C++ features that have so far not been implemented.
The following standard library features are not part of the current release, but are being implemented: