STLSoft C++ Libraries

infobox software
name = STLSoft C++ Libraries


caption =
latest_release_version = 1.9.57
latest_release_date = release date|2008|10|10
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 can be characterized as being "lightweight" and having high portability, high performance, minimal coupling and high cohesion.STLSoft Documentation.]

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++, [http://www.codeplay.com/ 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",Wilson 2007, p.xxxiv] This indicates that STLSoft started around the year 2002. HISTORY.txt and other files in the root directory of the STLSoft distribution contain the comment: Created: 29th March 2002, whereas the file stlsoft/stlsoft.h contains: Created: 15th January 2002.] 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 [http://synesis.com.au/ Synesis Software] code.Wilson 2004, p.565.] In 2008 Wilson remains the main author of the STLSoft libraries.STLSoft Website.]

= 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:
# as projects, for example: COMSTL, PlatformSTL, UnixSTL and WinSTL
# as libraries, for example: File System Library, Performance Library, SynchronisationBritish English spelling is used as in synchronisation, tokeniser and initialiser.] 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++"Wilson 2004.] and in "Extended STL, Volume 1".Wilson 2007.]

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.Wilson 2007, p.xxxv.] C/C++ User's Journal 2003a.]

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.Wilson 2007, pp. 57-64.] STLSoft Documentation.]

... others ...

Other notable techniques include:
* shims and type tunneling, which are used to reduce coupling between and to increase cohesion within the library's componentsC/C++ Users Journal 2003b] STLSoft Documentation.]
* 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 specializeC/C++ Users Journal 2005a.]
* zero-performance cost, 1-byte-per-class cost, C++ Properties, described in Chapter 35 of "Imperfect C++"Wilson 2004, pp.530-562.]
* 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.STLSoft Documentation.]

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 [http://rangelib.synesis.com.au/ 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 [http://stlsoft.org/doc-1.9/group__group____library____dl.html module] class, used to load and resource-manage a dynamically loaded library, and the [http://stlsoft.org/doc-1.9/group__group____library____dl.html 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 C++ Source 2004, Listing 2.] . 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

#include // std::copy
#include // std::ostream_iterator
#include // std::cout, std::endl
#include // 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, " " ));}

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 obsession with 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

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

scope.set_data("The data");

} // Clipboard is released herecatch(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 clipboardtry{ 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 herecatch(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 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 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 scoper(WSACleanup);

. . . // use the Winsock library

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

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.STLSoft Documentation.] 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)Wilson 2004.] and "Extended STL, volume 1" (2007)Wilson 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.STLSoft newsgroup.]

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:File STLSoft.h.]
* Borland C++ 5.5, 5.51, 5.6, 5.6.4 & 5.82
* [http://www.codeplay.com/ 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 & 9.0
* Watcom C/C++ 11.0, [http://www.openwatcom.org/ 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
* [http://flecxx.org/ flecxx] abstraction harmonizer library
* [http://openrj.org/ Open-RJ] Record-Jar API
* Pantheios C++ logging API library
* [http://recls.org/ recls] recursive file-system search
* [http://shwild.org/ shwild] shell-compatible wildcards
* VOLE C++ COM/Automation driver
* [http://xcontract.sourceforge.net/ xContract] a contract enforcement library
* [http://xtests.org/ xTests] Unit testing framework

See also

* STL - Standard Template Library

Notes

References

* Citation
last = Wilson
first = Matthew
title = Open-source Flexibility via Namespace Aliasing
newspaper = C/C++ User's Journal
volume = 21
issue = 7
year = 2003
date = July 2003
url = http://www.ddj.com/cpp/184401677

* Citation
last = Wilson
first = Matthew
title = Generalised String Manipulation: Access Shims and Type-tunnelling
newspaper = C/C++ User's Journal
volume = 21
issue = 8
year = 2003
date = August 2003
url = http://www.cuj.com/documents/s=8681/cuj0308wilson/

* Citation
last = Wilson
first = Matthew
title = Reading Unix-style Directories via STL-compliant Sequences
newspaper = The C++ Source
volume =
issue =
year = 2004
date = June 21, 2004
url=http://www.artima.com/cppsource/directoriesviasequences.html

* Citation
last = Wilson
first = Matthew
title = Adapting Interface-Incomplete Types at Compile Time
newspaper = C/C++ User's Journal
volume =
issue =
year = 2005
date = Deceember 2005
url = http://www.ddj.com/cpp/184402050

* cite web
url=http://www.digitalmars.com/pnews/read.php?server=news.digitalmars.com&group=c++.stlsoft&artnum=792
title=Documentation strategy ... opinions welcome (c++.stlsoft)
publisher=www.digitalmars.com
accessdate=2008-05-20
last=
first=

* Citation
last = Wilson
first = Matthew
url=http://stlsoft.org/
title=STLSoft - Robust, Lightweight, Cross-platform, Template Software
accessdate= 22 May 2008

* Citation
last = Wilson
first = Matthew
title = STLSoft Documentation
year = 2008
date = 01 Oct 2008
url = http://stlsoft.sourceforge.net/documentation.html
accessdate = 01 Oct 2008

* Citation
last = Wilson
first = Matthew
title = STLSoft Library 1.9.56
year = 2008
date = 01 Oct 2008
url = http://sourceforge.net/project/showfiles.php?group_id=238860
accessdate = 01 Oct 2008

* cite book
first = Matthew
last = Wilson
coauthors =
authorlink =
year = 2004
title = Imperfect C++: Practical Solutions for Real-Life Programming
publisher = Addison-Wesley
id = ISBN 0-321-22877-4

* cite book
first = Matthew
last = Wilson
coauthors =
authorlink =
year = 2007
title = Extended STL, Volume 1: Collections and Iterators
publisher = Addison-Wesley
id = ISBN 0-321-30550-7

Further reading

* STLSoft Getting Started Guide (Draft) [http://stlsoft.wiki.sourceforge.net/space/showimage/STLSoft-GettingStarted.pdf PDF ] , [http://stlsoft.wiki.sourceforge.net/space/showimage/STLSoft-GettingStarted.chm CHM ]
* [http://www.byte.com/wilson/ Articles by Matthew Wilson] on [http://www.byte.com/ Byte.com]
* [http://www.ddj.com/TechSearch/searchResults.jhtml?queryText=matthew+wilson&x=34&y=4 Articles by Matthew Wilson] on [http://www.ddj.com/ Dr.Dobb's Portal]
* [http://synesis.com.au/articles.html Articles by Matthew Wilson] on Synesis Software Website

External links

* [http://stlsoft.org/ STLSoft Official Website]
* [http://blog.stlsoft-musings.net/ STLSoft Musings] Blog
* [news://news.digitalmars.com/c++.stlsoft STLSoft newsgroup]