STLSoft C++ Libraries

{{ infobox software | name = STLSoft C++ Libraries | screenshot = | caption = | latest_release_version = 1.9.85 | latest_release_date = | programming_language = C/C++ | operating_system = MS-Windows, Unix, partially Cross-platform | genre = STL extension, Facades | license = BSD-form license | website = http://stlsoft.org/ }}

The STLSoft C++ Libraries are a collection of open source C++ template libraries that extend the functionality of the Standard Template Library and provide facades that wrap operating-system and technology-specific APIs. STLSoft is licensed under a BSD-form license to allow it to be used with both open and closed source projects.

STLSoft claims their library is characterized as being lightweight and having high portability, high performance, minimal coupling and high cohesion.

STLSoft is not a framework. STLSoft components are meant to be used as building blocks for higher level components such as applications, classes, libraries and servers.

The libraries cover operating systems such as Microsoft Windows, Mac OS X and Linux/Unix, several of which both in 32-bit and 64-bit versions and work with compilers such as Borland C++, CodePlay VectorC C/C++, Comeau C/C++, Digital Mars C/C++, GNU C, Intel C/C++, Metrowerks C/C++, SunPro C/C++, Visual C++ and Watcom C/C++.

History

Over the last half a decade or so, Matthew Wilson has been developing the STLSoft open source C++ template libraries to support the creation of both free and commercial software. Many parts of the libraries are derived from proprietary Synesis Software code. In 2008 Wilson remains the main author of the STLSoft libraries.

Implementation

STLSoft is written in C++, but it also contains parts that can be used with C. The libraries use templates and rely on compile-time polymorphism. The STLSoft libraries are header-only: the library code is included in and compiled with the user's code. This makes installation and usage of the libraries relatively easy.

Projects and Libraries

STLSoft is organized in two ways:

1. as projects, for example: COMSTL, PlatformSTL, UnixSTL and WinSTL
2. as libraries, for example: File System Library, Performance Library, Synchronisation Library

There are 12 projects and 30 libraries.

The main project is also called STLSoft and it contains most platform- and technology-independent code and code that helps to take care of compiler and standard library differences.

The biggest projects are COMSTL, UnixSTL and WinSTL. COMSTL provides utilities to work with the Component Object Model (COM) and provides STL-compatible sequence adapters over the COM enumeration and COM collection concepts. UNIXSTL and WinSTL provide operating-system and technology-specific components for Unix and Windows operating systems. These two projects have a number of structural conformant components, such as environment_variable, path and thread_mutex that are also placed in the PlatformSTL project that facilitates writing platform-agnostic code (see also subsection Techniques).

The other projects address additional technology-specific areas. ACESTL applies STL concepts to some components of the Adaptive Communication Environment (ACE) library. MFCSTL makes using the Microsoft Foundation Classes (MFC) more STL-like. RangeLib is the STLSoft implementation of the range concept. InetSTL, ATLSTL and WTLSTL are smaller projects that apply the STL concepts to Internet programming and to programming with the ACTIVE Template Library (ATL) and Windows Template Library (WTL).

Techniques & Concepts

Many IDeaS and techniques that STLSoft uses are described in Imperfect C++ and in Extended STL, Volume 1.

Namespace Aliasing

One such technique is namespace aliasing. It is used to reduce the extent to which namespaces must be specified in the library code itself.

For example, the COMSTL project's namespace, comstl, is actually an alias for the nested namespace stlsoft::comstl_project. This allows all COMSTL project components to 'see' all STLSoft project components (that are defined within the top-level stlsoft namespace), without having to use them.

Intersecting Conformance

With cross-platform libraries, common approaches to provide identical behavior across different platforms or technology areas are 1) to emulate functionality missing from some platforms and 2) to provide only functionality common to all platforms. STLSoft approaches cross-platform support as follows: where similar behavior across platforms is available, structural conformance is employed in its implementation, but where functionality is different structural conformance is avoided. Wilson names this the principle of intersecting conformance. Thus STLSoft provides a common interface for functionality that is available across platforms or technology areas and at the same time does not limit the functionality when programming for the native system only.

Other techniques

Other notable techniques include:

• Shims and type tunneling, which are used to reduce coupling between and to increase cohesion within the library's components
• Inferred Interface Adaptation, which can be used to correct/enhance a type's member types to allow it to fulfil structural conformance requirements of a template that it can then specialize
• zero-performance cost, 1-byte-per-class cost, C++ Properties, described in Chapter 35 of Imperfect C++
• Principle of Irrecoverability, which observes that any failure to adhere to the design of a constituent component of a software system must be interpreted as a failure to adhere to the design of the system as a whole. Systems in such a state must be closed down. The STLSoft component stlsoft::unrecoverable is a base exception class of a family of unrecoverable exceptions - they May Be caught and rethrown, but they may not be quenched without causing the process to be terminated

Finally, efficiency is an important aspect in the implementation of all components. Extensive use of efficient utility classes, such as auto_buffer, and scoped_handle help to attain high performance.

Library contents

Projects:

• ACESTL - STL extensions to the Adaptive Communication Environment open-source cross-platform networking C++ library
• ATLSTL - STL extensions to Microsoft's Active Template Library
• COMSTL - STL extensions the Component Object Model
• .netSTL
• InetSTL - STL extensions to the Windows Internet FtpFindFirstFile/InternetFindNextFile API
• MFCSTL - STL extensions to the Microsoft Foundation Class Library
• PlatformSTL - STL extensions from UNIXSTL and WinSTL that are structurally conformant (see also subsection Techniques)
• RangeLib - STLSoft's implementation of the range concept (see also RangeLib)
• STLSoft - STLSoft's platform- and technology-independent code
• UNIXSTL - STL extensions to the UNIX operating system(s) APIs
• WinSTL - STL extensions to the Windows operating system(s) APIs
• WTLSTL - STL extensions to Microsoft's Windows Template Library

Libraries:

• ACE Reactor Library
• Algorithms Library
• Collections Library
• COM Automation Library
• Containers Library
• Conversion Library
• DL (Dynamic Linking) Library - utilities for manipulating dynamically linked libraries. Main components are the module class, used to load and resource-manage a dynamically loaded library, and the dl_call function template suite, that provide generic, type-safe, single-statement invocation of dynamic library functions.
• Error Library
• File System Library
• Functional Library
• Iterators Library
• Memory Library
• Template Meta-programming Library
• Network Library
• Performance Library
• Properties Library
• Security Library
• Smart Pointers Library
• String Library
• Synchronisation Library
• System Library
• Time Library
• Utility Library
• Windows Clipboard Library
• Windows Control Panel Library
• Windows Controls Library
• Windows Registry Library
• Windows Shell Library
• Windows ToolHelp Library
• Windows Window Library

Examples

platformstl::readdir_sequence

The following example is adapted from . The program reads and displays the directories present in the root directory whether the program is compiled on Unix or compiled on Windows. It uses the class readdir_sequence from STLSoft's cross-platform project PlatformSTL that adapts the Unix opendir/readdir API and the FindFirstFile/FindNextFile MS-Windows API to an iteratable sequence.

#include <platformstl/filesystem/readdir_sequence.hpp>

#include <algorithm>    // std::copy
#include <iterator>     // std::ostream_iterator
#include <iostream>     // std::cout, std::endl
#include <string>       // std::string

using platformstl::readdir_sequence;

int main()
{
   readdir_sequence dir( "/", readdir_sequence::directories );

   std::copy( dir.begin(), dir.end()
            , std::ostream_iterator< std::string >( std::cout, "\n" ));
}

Using the GNU C compiler, the executable program can be build as follows with both Unix and MS-Windows:

g++ -Wall -I../stlsoft-1.9.42/include program.cpp -o program

Here it is assumed that the STLSoft library (release 1.9.42) is installed in a sibling directory of the directory that contains the program.

winstl::clipboard_scope

The next example illustrates STLSoft's strict adherence to Resource Acquisition Is Initialization (RAII), in providing scoped acquisition and access to the Windows Clipboard. It is adapted from the STLSoft documentation. First, setting a string to the clipboard:

#include <winstl/clipboard/clipboard_scope.hpp>

// 1. Set the data on the clipboard
try
{
  winstl::clipboard_scope     scope;

  scope.set_data("The data");

} // Clipboard is released here
catch(winstl::clipboard_scope_exception& x)
{
  . . . // handle error
}

As long as no other thread/process changes the clipboard contents in the meanwhile, this can then be read back, as follows:

// 2. Get the data from the clipboard
try
{
  winstl::clipboard_scope     scope;
  char const*                 str;

  scope.get_data(str); // Will throw if CF_TEXT is unavailable

  std::cout << "Clipboard data: " << str << std::endl;

} // Clipboard is released here; str becomes invalid here
catch(winstl::clipboard_scope_exception& x)
{
  . . . // handle error
}

In each case, access to the clipboard is scoped by the lifetime of the clipboard_scope instance, automatically acquired in the constructor and released in the destructor.

stlsoft::scoped_handle

A more sophisticated application of Resource Acquisition Is Initialization is found in the stlsoft::scoped_handle component, which can apply RAII on-the-fly, by specifying the resource releasing function along with the resource handle to the constructor. Consider the following examples, which apply RAII to a UNIX file handle, a malloc()'d block of memory and the Windows Winsock library.

UNIX file handle

int fh = open("filename", . . .);

if(-1 != fh)
{
  stlsoft::scoped_handle<int>  scoper(fh, close);

  . . . // use fh

} // fh is closed, via close(), by the destructor of scoper

malloc()'d block of memory

void* p = malloc(. . .);

if(NULL != p)
{
  stlsoft::scoped_handle<void*>  scoper(p, free);

  . . . // use p

} // p is freed, via free(), by the destructor of scoper

Windows Winsock Library

This version uses a the <void> specialisation of the class template, which is used for resources that do not have a resource handle, such as the Winsock Library.

WSADATA data;

if(0 != WSAStartup(MAKEWORD(2, 2), &data))
{
  stlsoft::scoped_handle<void>  scoper(WSACleanup);

  . . . // use the Winsock library

} // Winsock library is terminated, via WSACleanup(), by the destructor of scoper

Driving the Speech API

#include <comstl/speech/sapi_util.hpp>
#include <comstl/util/initialisers.hpp>
#include <stlsoft/smartptr/ref_ptr.hpp>

#include <stdio.h>
#include <stdlib.h>

int main()
{
  try
  {
    comstl::com_initialiser coinit;

    stlsoft::ref_ptr<ISpVoice>  voice;

    HRESULT hr = comstl::sapi_create(voice);

    if(SUCCEEDED(hr))
    {
      comstl::sapi_speak(voice, "Hello world!", 0);
    }

    return EXIT_SUCCESS;
  }
  catch(std::exception& x)
  {
    fprintf(stderr, "exception: %s\n", x.what());
  }

  return EXIT_FAILURE;
}

Criticisms

The documentation accompanying the STLSoft libraries consists of Doxygen generated reference documentation that includes a partially completed overview of the library contents and of the concepts, patterns, principles and techniques that it uses. In addition to this, the documentation contains circa twenty example programs that show how to use various components of the library, but that do not contain an explanation of the component's usage. There is no user documentation with a tutorial or a thematic approach (Getting Started guide). Detailed treatment of the design and implementation of several components is contained within both of Wilson's books - Imperfect C++ (2004) and Extended STL, volume 1 (2007) - but the coverage is arbitrary and does not include all the libraries, or all the projects. The necessity to improve the documentation is recognized though.

Platforms supported

Architecture—OS—Compiler / 32-bit, 64-bit / Unix, Linux, FreeBSD, Mac OS X, Sun Solaris?, MS-Windows.

The compilers supported by the STLSoft libraries are:

• Borland C++ 5.5, 5.51, 5.6, 5.6.4 & 5.82
• CodePlay VectorC C/C++ 1
• Comeau 4.3.0.1 & 4.3.3
• Digital Mars C/C++ 8.26 and above
• GCC 2.95, 2.96, 3.2, 3.3, 3.4 & 4.0
• Intel C/C++ 6.0, 7.0, 7.1, 8.0, 9.0, 10.0
• Metrowerks 2.4, 3.0 & 3.2 (CodeWarrior 7.0, 8.0 & 9.0)
• SunPro C/C++ 5.9
• Visual C++ 4.2, 5.0, 6.0, 7.0 (.NET), 7.1 (.NET 2003), 8.0 (2005) & 9.0 (2008)
• Watcom C/C++ 11.0, Open Watcom 1.0, 1.1, 1.2, 1.3, 1.4, 1.5 (partial support; to be made comprehensive in version 1.10)

Projects that use STLSoft

• b64 Base-64 conversion library
• FastFormat C/C++ output/formatting library
• flecxx abstraction harmonizer library
• Open-RJ Record-Jar API
• Pantheios C++ logging API library
• recls recursive file-system search
• shwild shell-compatible wildcards
• VOLE C++ COM/Automation driver
• xContract a contract enforcement library
• xTests Unit testing framework

See also

• List of C++ template libraries

Further reading

• STLSoft Getting Started Guide (Draft) PDF, CHM
• Articles by Matthew Wilson on Byte.com
• Articles by Matthew Wilson on Dr.Dobb's Portal
• Articles by Matthew Wilson on Synesis Software Website

External links

• STLSoft Official Website
• STLSoft Musings Blog
• STLSoft newsgroup