… robust, lightweight, cross-platform, template software …
STLSoft is a suite of C and C++ libraries (currently the 1.11 line) that provides:
- STL extensions;
- general-purpose utility components;
- facades over operating-system and technology-specific APIs;
The overarching characteristic of STLSoft is that it is lightweight. Specifically, the libraries share the following characteristics:
- 100% header-only — all components are entirely defined within header files, so users need only
#includethe requisite files to access the functionality; - Intersecting Conformance — similar, but not identical, components from different sub-projects (e.g. UnixSTL and WinSTL) are structurally conformant (compatible syntax and corresponding semantics, without being related by type) only to the degree of the intersection of identical functionality, rather than employing significant additional functionality to achieve total structural conformance. For example, though both
unixstl::filesystem_traitsandwinstl::filesystem_traitsprovidestat()andfstat(),lstat()is provided only by the former; - Maximum Cohesion with Minimal Coupling — achieved by extensive use of generalising mechanisms such as shims; e.g. types that manipulate character strings can interact with arbitrary string types, not just
char const*andstd::string; - Very High Efficiency — along with Robustness, components are implemented with a view to maximum Efficiency, aided by efficient utility classes such as
stlsoft::auto_bufferandstlsoft::scoped_handle;
NOTE: STLSoft is not a framework. Each library component is as thin as possible for its given function. The intent is that STLSoft components are used as building blocks for higher-level software — applications, classes, libraries, servers. STLSoft has been used extensively in all these guises.
Further reading: CONCEPTS.md, FAQ.md, INSTALL.md, http://www.stlsoft.org/.
Detailed instructions — via CMake, and via environment variables (archive or clone) — are provided in the accompanying INSTALL.md file, including an explanation of the top-level build scripts.
In short, there are three main ways to install STLSoft:
- As a downloaded archive, then using environment variables;
- Cloning the project, then using environment variables;
- Cloning the project, then installing via CMake;
Option 3 is recommended.
IMPORTANT: If you are installing STLSoft for the first time, you must do the CMake-based prepare step specifying that you do not want to run tests — by passing the flags
-Eand-Tto prepare_cmake.sh — otherwise you will hit a circular dependency on xTests (which depends on STLSoft). INSTALL.md explains the full first-time ordering.
The components in STLSoft are organised as sub-projects (technology / platform facets) that share libraries (functional areas). Many libraries appear in more than one sub-project with intersecting conformance — for example filesystem and dl under PlatformSTL, UnixSTL, and WinSTL.
The following significant sub-projects are provided:
- STLSoft — general-purpose components and base-level features, such as
stlsoft::auto_buffer<>,stlsoft::scoped_handle<>, andSTLSOFT_ASSERT(); - ACESTL — components for the ACE framework, such as
acestl::message_queue_sequence<>; - ATLSTL — components for the Active Template Library (ATL), such as
atlstl::get_MemberValue(); - COMSTL — components for the Component Object Model (COM), such as
comstl::interface_castandcomstl::enumerator_sequence<>; - InetSTL — components for internet APIs, such as
inetstl::sessionandinetstl::ftpdir_sequence; - MFCSTL — components for the Microsoft Foundation Classes (MFC), such as
mfcstl::CArray_cadaptor<>; - PlatformSTL — platform-selected facades over UnixSTL or WinSTL (by structural conformance), such as
platformstl::readdir_sequenceandplatformstl::stopwatch; - UnixSTL — components for Unix operating-system APIs, such as
unixstl::glob_sequenceandunixstl::dl_call(); - WinSTL — components for Windows operating-system APIs, such as
winstl::clipboard_scopeandwinstl::findfile_sequence;
The significant libraries include (examples are illustrative, not exhaustive):
- algorithms — POD and unordered-sequence algorithms, such as
stlsoft::pod_copy_n()andstlsoft::find_first_duplicate(); - automation — ATL Automation property and enumerator helpers, such as
atlstl::get_MemberValue(); - clipboard — Windows clipboard RAII and enumeration, such as
winstl::clipboard_scope; - collections — sequence and veneer adaptors (arrays, COM enumerators, ACE queues, MFC containers), such as
stlsoft::array_view<>andcomstl::enumerator_sequence<>; - containers — general- and special-purpose containers, such as
stlsoft::frequency_map<>andstlsoft::unicode_point_map; - controls — STL sequences over Win32 common controls, such as
winstl::listview_sequence; - conversion — casts and converters, such as
stlsoft::sap_cast<>(),stlsoft::format_bytes(), andcomstl::interface_cast; - diagnostics — stopwatches, timing histograms, and debug emitters, such as
platformstl::stopwatchandstlsoft::doomgram; - dl — dynamic-library loading and invocation (Unix and Windows), such as
platformstl::dl_moduleandwinstl::dl_call(); - filesystem — directory/glob sequences, paths, and mapped files, such as
platformstl::readdir_sequence,unixstl::glob_sequence, andplatformstl::memory_mapped_file; - functional — function/method adaptors and predicates, such as
stlsoft::noop_function; - iterator — output and transforming iterators, such as
stlsoft::FILE_iteratorandstlsoft::string_concatenator_iterator; - locale — scoped C locale changes, such as
stlsoft::locale_scope; - memory — buffers and allocators, such as
stlsoft::auto_buffer<>andcomstl::task_allocator<>; - meta — compile-time type traits and selectors, such as
stlsoft::is_same_type<>; - network — internet/ACE session and connection facades, such as
inetstl::sessionandinetstl::connection; - performance — performance counters (often aliased to platform stopwatches), such as
platformstl::performance_counter; - process — Windows process-creation helpers, such as
winstl::create_process(); - quality — contract-enforcement and coverage macros, such as
STLSOFT_COVER_MARK_LINE(); - reactor — ACE reactor custom-event handling, such as
acestl::custom_event_handler; - registry — Windows registry keys, values, and sequences, such as
winstl::reg_keyandwinstl::reg_value_sequence; - resource — Windows resource-loading helpers, such as
winstl::load_custom_resource(); - security — COM/Win security initialisation and token/ACL views, such as
comstl::CoInitSecurity()andwinstl::token_information<>; - shell — Windows Shell helpers, such as
winstl::browse_for_folder(); - shims — generalising access, attribute, and logical shims (overloads across sub-projects), such as
stlsoft::c_str_ptr()andstlsoft::get_ptr(); - smartptr — scoped and reference-counted handles, such as
stlsoft::scoped_handle<>andstlsoft::ref_ptr<>; - speech — lightweight SAPI helpers, such as
comstl::sapi_speak(); - string — lightweight strings, views, and tokenisers, such as
stlsoft::basic_simple_string<>andstlsoft::string_tokeniser<>; - synch — mutexes, spin locks, and lock scopes, such as
platformstl::thread_mutexandstlsoft::lock_scope<>; - system — environment, home directory, and process-id sequences, such as
platformstl::home_directoryandplatformstl::pid_sequence; - time — time formatting and comparison helpers, such as
stlsoft::fast_strftime(); - typelib — COM type-library helpers, such as
comstl::TypeInfo_resource_scope; - view — transforming views, such as
stlsoft::member_selector_view<>;
The tables below list the significant components of STLSoft by header stem (a .h and .hpp pair counts once), each with the release in which it first appeared. Badges are coloured by era: dark grey for 1.9.118 and earlier, orange for 1.9.119+, blue for 1.10+, green for 1.11+. Tag history in this repository begins at 1.9.118, so since values for earlier components are estimates derived from header Created: dates and CHANGES.md (≤1.9.1-beta1 means created before the first release recorded there). Enhanced is the latest tag at which the header's major or minor version changed, i.e. a significant enhancement; - means no such change since 1.9.118 (or since introduction).
Components first written for 1.10 (files merely relocated by the 1.10 reorganisation are not listed unless they are also notable legacy components below):
Legacy (1.9 and earlier) components that are used by other STLSoft components, used by other Synesis projects, or otherwise important:
Examples are provided in the examples directory, along with a markdown description for each. A detailed catalogue is in EXAMPLES.md. After a CMake build, ./run_all_examples.sh exercises matching example programs (see INSTALL.md).
Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/STLSoft.
If you'd like to help out with the project, please raise an issue via GitHub Issues — you'll be very welcome! See also HOW_YOU_CAN_HELP.md.
| Dependency | Role | Required? |
|---|---|---|
| — | Installation and use of STLSoft (100% header-only) | ✅ None |
| ACE | ACESTL examples / tests | ⚪ Optional (NO_ACE / --no-ace; ACE / ACE_ROOT or system package) |
| xTests | Component- / unit-tests (BUILD_TESTING) |
⚪ Tests only |
Projects that depend on STLSoft — though for some it is only for tests — include:
- 2be (tests only);
- b64 (C++ API only);
- CLASP (C++ API, tests only);
- cstring (tests only);
- Diagnosticism (tests only);
- FastFormat;
- libCLImate;
- libpath (tests only);
- Pantheios;
- Pantheios.Extras.AtExit;
- Pantheios.Extras.DiagUtil;
- Pantheios.Extras.Main;
- Pantheios.Extras.xHelpers;
- recls;
- shwild (C++ API only);
- UNIXem (tests only);
- VOLE (tests only);
- xTests;
STLSoft is released under the 3-clause BSD license. See LICENSE for details.