bsl.h

Go to the documentation of this file.

/// @file bsl.h
///
///
/// @defgroup bsl Group bsl
/// @brief  Basic Standard Library (bsl)
/// @addtogroup bsl
/// @{
/// * <a href="#bsl-purpose"> Purpose</a>
/// * <a href="#bsl-mnemonic"> Mnemonic </a>
/// * <a href="#bsl-description"> Description </a>
///   * <a href="#bsl-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bsl-package-synopsis"> Package Synopsis </a>
///   * <a href="#bsl-package-overview"> Package Overview </a>
///     * <a href="#bsl-bsl-bslhdrs"> bsl+bslhdrs </a>
///     * <a href="#bsl-bslalg"> bslalg </a>
///     * <a href="#bsl-bsldoc"> bsldoc </a>
///     * <a href="#bsl-bslfmt"> bslfmt </a>
///     * <a href="#bsl-bslh"> bslh </a>
///     * <a href="#bsl-bslim"> bslim </a>
///     * <a href="#bsl-bslma"> bslma </a>
///     * <a href="#bsl-bslmf"> bslmf </a>
///     * <a href="#bsl-bsls"> bsls </a>
///     * <a href="#bsl-bslscm"> bslscm </a>
///     * <a href="#bsl-bslstl"> bslstl </a>
///     * <a href="#bsl-bsltf"> bsltf </a>
///     * <a href="#bsl-bslx"> bslx </a>
///
/// # Purpose {#bsl-purpose}
/// Provide a comprehensive foundation for component-based development.
///
/// # Mnemonic {#bsl-mnemonic}
/// Basic Standard Library (bsl)
///
/// # Description {#bsl-description}
/// The 'bsl' ("Basic Standard Library") package group contains
/// various packages that provide platform-specific classes, meta-functions,
/// defensive programming mechanisms, a framework for component testing, memory
/// allocation protocols and algorithms, and a C++ standard library
/// implementation.
///
/// Note that the C++ standard library is implemented in the 'bsl' namespace
/// instead of the standard 'std' namespace.  This allow clients to use both the
/// native compiler provided C++ standard library together with the Bloomberg
/// provided C++ standard library in the same translation unit.
///
/// The 'bsl' package group is the foundation of the firm-wide BDE library and has
/// no dependencies beyond the allowed OS and runtime environment dependencies.
///
/// ## Hierarchical Synopsis {#bsl-hierarchical-synopsis}
///
/// The 'bsl' package group currently has 17 packages having 11 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the packages.
/// The order of packages within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  11. bslmt
///      bslx
///
///  10. bslim
///
///   9. bsl+bslhdrs
///
///   8. bslfmt
///      bslstp                                             !DEPRECATED!
///
///   7. bslstl
///
///   6. bslalg
///
///   5. bslh
///      bsltf
///
///   4. bslma
///
///   3. bsldoc
///      bslmf
///
///   2. bsla
///      bslscm
///
///   1. bslfwd                                             !DEPRECATED!
///      bsls
/// @endcode
/// Note that the 'bsl+stdhdrs' package is only a compatibility layer for
/// Bloomberg managed code.  It is not an essential package for the rest of the
/// BDE libraries (i.e., all other package groups above 'bsl' will compile and
/// function without 'bsl+stdhdrs').  This package implements the logic required
/// for 'BDE-STL' mode.
///
/// Note that required source control package 'bslscm' depends on 'bsls'; this
/// behavior is unique to 'bsl', although it is temporarily also in 'bde' for
/// historic reasons, since logically *every* other package should depend on
/// 'bslscm'.
///
/// ## Package Synopsis {#bsl-package-synopsis}
///
///  'bsl+bslhdrs':
///       Provide a compatibility layer to enable BDE-STL mode in Bloomberg.
/// 
///  'bsla':
///       Provide macros for portable use of compiler annotations.
/// 
///  'bslalg':
///       Provide algorithms and traits used by the BDE STL implementation.
/// 
///  'bsldoc':
///       Provide documentation of terms and concepts used throughout BDE.
/// 
///  'bslfmt':
///       Provide implementation mechanisms for bsl::format.
/// 
///  'bslfwd':                                              !DEPRECATED!
///       Provide compatibility for clients using single-level namespace
/// 
///  'bslh':
///       Provide a framework for hashing types using swappable algorithms.
/// 
///  'bslim':
///       Provide implementation mechanisms.
/// 
///  'bslma':
///       Provide allocators, guards, and other memory-management tools.
/// 
///  'bslmf':
///       Provide meta-function versions of useful coding constructs.
/// 
///  'bslmt':
///       Support for multi-threading and thread-safe processes.
/// 
///  'bsls':
///       Provide system-level utilities for 'bsl'.
/// 
///  'bslscm':
///       Provide versioning information for BDE library components.
/// 
///  'bslstl':
///       Provide replacement classes for STL constructs.
/// 
///  'bslstp':                                              !DEPRECATED!
///       Provide replacement classes (adopted from STLport) for STL.
/// 
///  'bsltf':
///       Provide a set of utilities and types to help with testing.
/// 
///  'bslx':
///       Define externalization protocols and provide implementations.
///
/// ## Package Overview {#bsl-package-overview}
///
/// This section provides a brief introduction to the packages of the 'bsl'
/// package group.  Note that several packages, especially at lower levels in the
/// physical hierarchy, are primarily intended for use by other packages within
/// 'bsl'.  See the respective Package Level documents for more details.
///
/// ### bsl+bslhdrs {#bsl-bsl-bslhdrs}
///
/// The {'bsl+bslhdrs'} package provides the 'bsl' version of the standard C++
/// library (e.g., 'bsl_vector.h' instead of 'vector', 'bsl_algorithm.h' instead
/// of 'algorithm').  Users of 'bsl' can include these headers to obtain the
/// corresponding C++ STL functionalities.
///
/// ### bslalg {#bsl-bslalg}
///
/// The {'bslalg'} package provides a variety of lower-level algorithms,
/// comparisons, and traits.
///
/// ### bsldoc {#bsl-bsldoc}
///
/// The {'bsldoc'} package documents key terminology and concepts used throughout
/// BDE documentation.  Note that the components in this package consist entirely
/// of comments, no code.
///
/// ### bslfmt {#bsl-bslfmt}
///
/// The {'bslfmt'} package provides implementation mechanisms for 'bsl::format',
/// which is a C++03 compatible implementation of C++20's '<format>'.
///
/// ### bslh {#bsl-bslh}
///
/// The {'bslh'} package provides standard hashing algorithms and components
/// allowing the application of those hashing algorithms to types in a modular
/// way.
///
/// ### bslim {#bsl-bslim}
///
/// The {'bslim'} package provides implementation mechanisms for features that
/// must have identical syntax and semantics in many disparate classes.
///
/// ### bslma {#bsl-bslma}
///
/// {'bslma'} provides memory allocation and related proctor and handle objects.
///
/// ### bslmf {#bsl-bslmf}
///
/// The {'bslmf'} package provides low-level "meta-functions" implementing
/// "traits" and other useful properties of types, determined at compile-time.
///
/// ### bsls {#bsl-bsls}
///
/// The {'bsls'} package provides the needed platform-independent definitions and
/// utilities (with platform-specific implementations) so that the rest of the bsl
/// library, and all conforming applications within the Development Framework, can
/// be written in a truly portable, platform-neutral dialect of C++ -- one having
/// dependency on 'bsls', but on no other system-specific services.  Among the
/// issues dealt with in 'bsls' are hardware, operating system, and compiler
/// definitions, "endian-ness" and alignment of type representation in physical
/// memory, bit-manipulation utilities, and a uniform interface to system services
/// (e.g., timers).
///
/// ### bslscm {#bsl-bslscm}
///
/// The {'bslscm'} package contains only two components, @ref bslscm_version  and
/// @ref bslscm_versiontag .  The first of these components is included by every other
/// component in 'bsl', and provides versioning information for the package group.
/// Users may use the @ref bslscm_version  facilities to query a particular 'bsl'
/// library for its version information.  The second component defines macros that
/// can be used for conditional-compilation based on 'bsl' version information.
///
/// ### bslstl {#bsl-bslstl}
///
/// The {'bslstl'} package provides implementations of certain containers of the
/// C++ standard library using the 'bslma' memory allocation model, algorithms and
/// traits in 'bslalg' and meta-functions in 'bslmf'.
///
/// ### bsltf {#bsl-bsltf}
///
/// The {'bsltf'} package provides a set test types and utilities that operates on
/// those types, which can help simplify, particularly for template, the
/// implementation of test drivers.
///
/// ### bslx {#bsl-bslx}
///
/// The {'bslx'} package defines (via documentation) the BDEX protocol for
/// externalization (i.e., for an "out stream") and "unexternalization" (i.e., for
/// an "in stream"), and provides concrete byte-array-based stream implementations
/// of each kind of stream, including streams for testing.
///
/// @}