
The original Watcom C++ compiler came with an old-style C++ library that predated even the 1998
standard. We have been modernizing this library by adding the missing components and updating
the existing components. Our implementation is entirely fresh. We do not use any third party
library components. This allows us to take advantage of Open Watcom's unique features while
working around, if necessary, Open Watcom's limitations. See the [Design
Philosophy](#DesignPhilosophy) section below for more details about the design criteria and
goals for the Open Watcom C++ library (OWCPPLIB).

Currently, OWCPPLIB is in an unfinished state. Relative to the C++ 1998 standard about 3/4 of
the required library components are available. Some library components from the C++ 2011
standard have also been implemented, but C++ 2011 support is minimal. Also, due to limitations
in the Open Watcom C++ compiler, many library components can only be partial implemented or, in
some cases, not implemented at all. See the [C++ Library Status](C++-Library-Status) section for
more information.

<a name="DesignPhilosophy"></a>
Design Philosophy
-----------------

In this section we attempt to answer the question of how the Open Watcom C++ library is
different from other C++ libraries by making explicit the design criteria and goals for the
OWCPPLIB project. The order of the items below is not significant.

+ *Clarity of Presentation*. Writing clear code is, of course, always desirable. In the case of
  an open source C++ library where essentially all the code is in header files, clarity seems
  especially important. We want OWCPPLIB to invite study, not only to help improve its quality,
  but also to serve as an educational vehicle for novice C++ programmers. Templates that are
  easy to read also improves debugging in cases where you want to step into the library code.
  Several of the other criteria below are derived from the desire to make OWCPPLIB as clear as
  possible.

+ *Specific to Open Watcom*. OWCPPLIB does not attempt to be usable with other compilers -
  including earlier versions of Open Watcom. It was developed for the current version of Open
  Watcom only. This simplifies the implementation considerably because it is not necessary to
  clutter the code with `#ifdef` blocks to selectively work around bugs and quirks in multiple
  compilation systems. This also allows OWCPPLIB to take advantage of Open Watcom specific
  features and extensions in a straight forward way.

+ *Conformance to the C++ Standard*. It is our priority to make OWCPPLIB highly conformant to
  the standard.

+ *Good Support for 16-bit Programming*. Since Open Watcom C/C++ supports several 16-bit
  targets, we want OWCPPLIB to be usable with such targets. This means the library needs to
  behave reasonably even when used in programs with significant memory constraints. This is
  particularly important for a template-heavy library where "code bloat" is sometimes a problem.


<a name="ModernizingIOStreams"></a>
Modernizing IOStreams
---------------------

Open Watcom C++ is currently using a "classic" (old style) IOStreams library in namespace `std`.
This is somewhat odd. One would normally expect the classic library to be in the global name
space and to only find a standard version of IOStreams in namespace `std`. However, the current
situation does allow Open Watcom to compile many simple I/O examples according to the standard
(e.g., programs that use `std::cout` and similar basic facilities of IOStreams).

Standard IOStreams differs from the classic library in many respects and advanced users of the
library will quickly encounter the differences. Here are two of those differences:

+ Standard IOStreams are template based with separate instantiations for characters and wide
  characters. Classic IOStreams only support characters using ordinary (non-template) classes.

+ Standard IOStreams use standard locales to control formatting. Classic IOStreams does not have
  locales.

Although this is a work in progress, we intend to upgrade Open Watcom's IOStreams library so
that it will conform to the standard. The approach we are taking is to, in effect, rewrite the
entire library from scratch. One approach might be to build the new library in a temporary name
space so that it does not interfere with the existing library while it is under construction.
Although the new library will be written "from scratch" we expect to be able to borrow
significant sections of logic, if not actual code, from the existing IOStreams library.

The new library will be built from the bottom up. Since standard IOStreams is heavily dependent
on locales, the first step might be to provide standard locales for Open Watcom (this can be
done directly in namespace `std` since there is no existing locale code to conflict). Once this
is done the IOStream class hierarchy can be built, starting with `ios_base` and working down the
inheritance graph toward `iostream`.

Special Features
----------------

OWCPPLIB contains a number of special features that we highlight in this section.

### Case-Insensitive String Comparisons

After doing `#include <string>` a special instantiation of `std::basic_string` named
`watcom::istring` is available that does all comparisons in a case-insensitive manner. For
example:

```cpp
#include <string>

void f( )
{
    watcom::istring s( "HELLO" );
    if( s == "hello" ) {
        // Matches "HELLO", "Hello", "HeLlO", etc.
    }
    watcom::istring::size_type result = find( s, "ell" );  // Returns 1.
}
```

### Simple Local Names

OWCPPLIB is written without the extensive use of underscore characters in the header files that
one typically finds in C++ library implementations. For example, consider OWCPPLIB's version of
`for_each`:

```cpp
template<class InputIterator, class Function>
Function for_each( InputIterator first, InputIterator last, Function f )
{
    while( first != last ) {
        f( *first );
        ++first;
    }
    return( f );
}
```

This is to be contrasted with a more common style that looks like

```cpp
template< class __InputIterator, class __Function >
__Function for_each( __InputIterator _first, __InputIterator _last, __Function _f )
{
    while( _first != _last ) {
        _f( *_first );
        ++_first;
    }
    return( _f );
}
```

We feel that the extensive use of underscores obscures the code and makes it difficult to read.
Thus, we avoid them.

The underscores are normally used to protect the names from accidental modification due to user
defined macros. Since the preprocessor does not respect the usual C++ scope rules, such macros
might conflict with the simple names used in the first example. To avoid this, other template
libraries use implementation reserved names even for symbols that would otherwise be local.

We believe, however, that the correct way to protect template bodies from molestation by the
preprocessor is to provide the preprocessor with some sort of scope control facility. This has
not yet been done in Open Watcom partly because we are waiting to see if such a facility becomes
standard.

Future Directions
-----------------

In this section we provide a rough road map describing the anticipated future work on OWCPPLIB.
If you are interested in contributing to OWCPPLIB you can consider this list as a "to do" list.
The items below are approximately in descending order of priority.

+ Obtain user feedback on the library components that currently exist. Actively maintain the
  existing components.

+ Finish OWCPPLIB by providing the remaining functionality as required by the C++ 2011 standard.
  This will also require updating the C++ compiler itself since it does not yet support all the
  necessary features for processing a fully standard library.

+ Write user level documentation to augment the current C++ Library Reference manual.

+ Add extensions of interest to Open Watcom users (for example, near and far allocators, etc.).

+ Perform detailed performance evaluations, and then optimize the implementation.

+ Implement some sort of scope control facility in the preprocessor so that the simple local
  names used in OWCPPLIB will be safe.

+ Experiment with alternative implementation methods, perhaps allowing the user to select from
  the alternatives at compile time (or run time?).

+ Build a "debugging" version of OWCPPLIB that includes additional run time (or compile time?)
  checks.
