bslstl.h

Go to the documentation of this file.

/// @file bslstl.h
///
///
/// @defgroup bslstl Package bslstl
/// @brief  Basic Standard Library STL (bslstl)
/// @addtogroup bsl
/// @{
/// @addtogroup bslstl
/// [bslstl]: group__bslstl.html
/// @{
///
/// # Purpose {#bslstl-purpose}
/// Provide replacement classes for STL constructs.
///
/// # Mnemonic {#bslstl-mnemonic}
/// Basic Standard Library STL (bslstl)
///
/// # Description {#bslstl-description}
/// This package mainly provides replacement classes for STL
/// constructs that required substantial modification to (inter)operate with BDE
/// libraries.  In addition to STL replacement classes, this package also provides
/// helper components for the STL implementation classes.  Finally, SGI extensions
/// that are widely used within Bloomberg can also be found in this package.
///
/// In general, the components in this package conform to the STL interface.
/// However, the components (and hence the headers) are intended for private use
/// only.  Clients should use the standard headers directly (e.g., include
/// '<bsl_vector.h>' instead of '<bslstl_vector.h>').
///
/// ## Hierarchical Synopsis
///
/// The 'bslstl' package currently has 126 components having 10 levels of physical
/// dependency.  The list below shows the hierarchical ordering of the components.
/// The order of components within each level is not architecturally significant,
/// just alphabetical.
/// @code
///  10. bslstl_ownerequal
///      bslstl_ownerhash
///      bslstl_ownerless
///      bslstl_stoptoken
///      bslstl_typeindex
///
///   9. bslstl_map_test1                                                !PRIVATE!
///      bslstl_map_test2                                                !PRIVATE!
///      bslstl_map_test3                                                !PRIVATE!
///      bslstl_multimap_test                                            !PRIVATE!
///      bslstl_multiset_test                                            !PRIVATE!
///      bslstl_set_test                                                 !PRIVATE!
///      bslstl_sharedptr
///
///   8. bslstl_map
///      bslstl_multimap
///      bslstl_multiset
///      bslstl_osyncstream
///      bslstl_set
///
///   7. bslstl_boyermoorehorspoolsearcher
///      bslstl_istringstream
///      bslstl_mapcomparator
///      bslstl_ostringstream
///      bslstl_queue
///      bslstl_setcomparator
///      bslstl_stack
///      bslstl_stringstream
///      bslstl_syncbuf
///      bslstl_treenodepool
///      bslstl_unorderedmap_test                                        !PRIVATE!
///      bslstl_unorderedmultimap_test                                   !PRIVATE!
///      bslstl_unorderedmultiset_test                                   !PRIVATE!
///      bslstl_unorderedset_test                                        !PRIVATE!
///
///   6. bslstl_bitset
///      bslstl_defaultsearcher
///      bslstl_deque
///      bslstl_iomanip
///      bslstl_priorityqueue
///      bslstl_span
///      bslstl_string_test                                              !PRIVATE!
///      bslstl_stringbuf
///      bslstl_stringref
///      bslstl_treenode
///      bslstl_unorderedmap
///      bslstl_unorderedmultimap
///      bslstl_unorderedmultiset
///      bslstl_unorderedset
///      bslstl_variant
///
///   5. bslstl_array
///      bslstl_function
///      bslstl_hashtable
///      bslstl_list
///      bslstl_randomaccessiterator
///      bslstl_string
///      bslstl_systemerror
///      bslstl_vector
///
///   4. bslstl_algorithm
///      bslstl_bidirectionaliterator
///      bslstl_charconv
///      bslstl_error
///      bslstl_function_invokerutil                                     !PRIVATE!
///      bslstl_hashtablebucketiterator
///      bslstl_hashtableiterator
///      bslstl_iteratorutil
///      bslstl_ostream
///      bslstl_stringrefdata
///
///   3. bslstl_bidirectionalnodepool
///      bslstl_chrono
///      bslstl_errc
///      bslstl_forwarditerator
///      bslstl_function_rep                                             !PRIVATE!
///      bslstl_ios
///      bslstl_optional
///      bslstl_pair
///      bslstl_stringview
///      bslstl_treeiterator
///
///   2. bslstl_algorithmworkaround                         !DEPRECATED!
///      bslstl_allocator                                   !DEPRECATED!
///      bslstl_badfunctioncall
///      bslstl_badoptionalaccess
///      bslstl_badvariantaccess
///      bslstl_badweakptr
///      bslstl_compare
///      bslstl_complex
///      bslstl_equalto
///      bslstl_exception
///      bslstl_function_isreferencecompatible                           !PRIVATE!
///      bslstl_function_smallobjectoptimization                         !PRIVATE!
///      bslstl_hash
///      bslstl_inplace
///      bslstl_iosfwd
///      bslstl_iserrorcodeenum
///      bslstl_iserrorconditionenum
///      bslstl_iterator
///      bslstl_monostate
///      bslstl_ratio
///      bslstl_referencewrapper
///      bslstl_sharedptrallocateinplacerep
///      bslstl_sharedptrallocateoutofplacerep
///      bslstl_simplepool
///      bslstl_stdexceptutil
///      bslstl_stopstate
///      bslstl_syncbufbase
///      bslstl_unorderedmapkeyconfiguration
///      bslstl_unorderedsetkeyconfiguration
///      bslstl_utility
///
///   1. bslstl_bidirectionalnodepool_cpp03                              !PRIVATE!
///      bslstl_deque_cpp03                                              !PRIVATE!
///      bslstl_function_cpp03                                           !PRIVATE!
///      bslstl_function_invokerutil_cpp03                               !PRIVATE!
///      bslstl_hashtable_cpp03                                          !PRIVATE!
///      bslstl_list_cpp03                                               !PRIVATE!
///      bslstl_map_cpp03                                                !PRIVATE!
///      bslstl_multimap_cpp03                                           !PRIVATE!
///      bslstl_multiset_cpp03                                           !PRIVATE!
///      bslstl_optional_cpp03                                           !PRIVATE!
///      bslstl_priorityqueue_cpp03                                      !PRIVATE!
///      bslstl_queue_cpp03                                              !PRIVATE!
///      bslstl_set_cpp03                                                !PRIVATE!
///      bslstl_sharedptr_cpp03                                          !PRIVATE!
///      bslstl_stack_cpp03                                              !PRIVATE!
///      bslstl_treenodepool_cpp03                                       !PRIVATE!
///      bslstl_unorderedmap_cpp03                                       !PRIVATE!
///      bslstl_unorderedmultimap_cpp03                                  !PRIVATE!
///      bslstl_unorderedmultiset_cpp03                                  !PRIVATE!
///      bslstl_unorderedset_cpp03                                       !PRIVATE!
///      bslstl_variant_cpp03                                            !PRIVATE!
///      bslstl_vector_cpp03                                             !PRIVATE!
/// @endcode
///
/// ## Component Synopsis
///
///  @ref bslstl_algorithm :
///       Provide implementations for algorithms not in the system library.
/// 
///  @ref bslstl_algorithmworkaround :                          !DEPRECATED!
///       Provide a namespace for work arounds for the standard algorithms
/// 
///  @ref bslstl_allocator :                                    !DEPRECATED!
///       Provide an STL-compatible proxy for `bslma::Allocator` objects.
/// 
///  @ref bslstl_array :
///       Provide an STL compliant array.
/// 
///  @ref bslstl_badfunctioncall :
///       Provide an exception class thrown by `bsl::function`.
/// 
///  @ref bslstl_badoptionalaccess :
///       Provide an exception class thrown by `bsl::optional`.
/// 
///  @ref bslstl_badvariantaccess :
///       Provide an exception class thrown by `bsl::variant`.
/// 
///  @ref bslstl_badweakptr :
///       Provide an exception class to indicate a weak_ptr has expired.
/// 
///  @ref bslstl_bidirectionaliterator :
///       Provide a template to create STL-compliant bidirectional iterators.
/// 
///  @ref bslstl_bidirectionalnodepool :
///       Provide efficient creation of nodes used in a node-based container.
/// 
///  'bslstl_bidirectionalnodepool_cpp03':                               !PRIVATE!
///       Provide C++03 implementation for bslstl_bidirectionalnodepool.h
/// 
///  @ref bslstl_bitset :
///       Provide an STL-compliant bitset class.
/// 
///  @ref bslstl_boyermoorehorspoolsearcher :
///       Provide an STL-compliant `boyer_moore_horspool_searcher` class.
/// 
///  @ref bslstl_charconv :
///       Provide implementations for functions not in the system library.
/// 
///  @ref bslstl_chrono :
///       Provide functionality of the corresponding C++ Standard header.
/// 
///  @ref bslstl_compare :
///       Provide functionality of the corresponding C++ Standard header.
/// 
///  @ref bslstl_complex :
///       Provide functionality of the corresponding C++ Standard header.
/// 
///  @ref bslstl_defaultsearcher :
///       Provide an STL-compliant @ref default_searcher  class.
/// 
///  @ref bslstl_deque :
///       Provide an STL-compliant deque class.
/// 
///  'bslstl_deque_cpp03':                                               !PRIVATE!
///       Provide C++03 implementation for bslstl_deque.h
/// 
///  @ref bslstl_equalto :
///       Provide a binary functor conforming to the C++11 `equal_to` spec.
/// 
///  @ref bslstl_errc :
///       Provide a standard compliant version of `errc`.
/// 
///  @ref bslstl_error :
///       Provide standard compliant versions of <system_error> classes.
/// 
///  @ref bslstl_exception :
///       Provide an implementation of @ref uncaught_exceptions .
/// 
///  @ref bslstl_forwarditerator :
///       Provide a template to create STL-compliant forward iterators.
/// 
///  @ref bslstl_function :
///       Provide a polymorphic function object with a specific prototype.
/// 
///  'bslstl_function_cpp03':                                            !PRIVATE!
///       Provide C++03 implementation for bslstl_function.h
/// 
///  'bslstl_function_invokerutil':                                      !PRIVATE!
///       Provide invoker adaptors for `bsl::function`
/// 
///  'bslstl_function_invokerutil_cpp03':                                !PRIVATE!
///       Provide C++03 implementation for bslstl_function_invokerutil.h
/// 
///  'bslstl_function_isreferencecompatible':                            !PRIVATE!
///       Provide a metafunction for substitutability of type references.
/// 
///  'bslstl_function_rep':                                              !PRIVATE!
///       Provide a non-template, common implementation for `bsl::function`.
/// 
///  'bslstl_function_smallobjectoptimization':                          !PRIVATE!
///       Provide small-object optimization buffer for `bsl::function`.
/// 
///  @ref bslstl_hash :
///       Provide a namespace for hash functions.
/// 
///  @ref bslstl_hashtable :
///       Provide a hash-container with support for duplicate values.
/// 
///  'bslstl_hashtable_cpp03':                                           !PRIVATE!
///       Provide C++03 implementation for bslstl_hashtable.h
/// 
///  @ref bslstl_hashtablebucketiterator :
///       Provide an STL compliant iterator over hash table buckets.
/// 
///  @ref bslstl_hashtableiterator :
///       Provide an STL compliant iterator for hash tables.
/// 
///  @ref bslstl_inplace :
///       Provide a standard-compliant in place construction tag types.
/// 
///  @ref bslstl_iomanip :
///       Provide BSL implementations for standard <iomanip> features.
/// 
///  'bslstl_ios':
///       Provide functionality of the corresponding C++ Standard header.
/// 
///  @ref bslstl_iosfwd :
///       Provide forward declarations for Standard stream classes.
/// 
///  @ref bslstl_iserrorcodeenum :
///       Provide a compliant standard `is_error_code_enum` trait.
/// 
///  @ref bslstl_iserrorconditionenum :
///       Provide a compliant standard `is_error_condition_enum` trait.
/// 
///  @ref bslstl_istringstream :
///       Provide a C++03-compatible `istringstream` class.
/// 
///  @ref bslstl_iterator :
///       Provide basic iterator traits, adaptors, and utilities.
/// 
///  @ref bslstl_iteratorutil :
///       Provide utilities operating on iterators and iterator ranges.
/// 
///  @ref bslstl_list :
///       Provide an STL-compliant list class.
/// 
///  'bslstl_list_cpp03':                                                !PRIVATE!
///       Provide C++03 implementation for bslstl_list.h
/// 
///  'bslstl_map':
///       Provide an STL-compliant map class.
/// 
///  'bslstl_map_cpp03':                                                 !PRIVATE!
///       Provide C++03 implementation for bslstl_map.h
/// 
///  'bslstl_map_test1':                                                 !PRIVATE!
///       Provide support for the `bslstl_map.t.cpp` test driver.
/// 
///  'bslstl_map_test2':                                                 !PRIVATE!
///       Provide support for the `bslstl_map.t.cpp` test driver.
/// 
///  'bslstl_map_test3':                                                 !PRIVATE!
///       Provide support for the `bslstl_map.t.cpp` test driver.
/// 
///  @ref bslstl_mapcomparator :
///       Provide a comparator for `TreeNode` objects and a lookup key.
/// 
///  @ref bslstl_monostate :
///       Provide a default constructible alternative for `bsl::variant`.
/// 
///  @ref bslstl_multimap :
///       Provide an STL-compliant multimap class.
/// 
///  'bslstl_multimap_cpp03':                                            !PRIVATE!
///       Provide C++03 implementation for bslstl_multimap.h
/// 
///  'bslstl_multimap_test':                                             !PRIVATE!
///       Provide support for the `bslstl_multimap.t.cpp` test driver.
/// 
///  @ref bslstl_multiset :
///       Provide an STL-compliant multiset class.
/// 
///  'bslstl_multiset_cpp03':                                            !PRIVATE!
///       Provide C++03 implementation for bslstl_multiset.h
/// 
///  'bslstl_multiset_test':                                             !PRIVATE!
///       Provide support for the `bslstl_multiset.t.cpp` test driver.
/// 
///  @ref bslstl_optional :
///       Provide a standard-compliant allocator aware optional type.
/// 
///  'bslstl_optional_cpp03':                                            !PRIVATE!
///       Provide C++03 implementation for bslstl_optional.h
/// 
///  @ref bslstl_ostream :
///       Provide aliases and implementations matching standard <ostream>.
/// 
///  @ref bslstl_ostringstream :
///       Provide a C++03-compatible `ostringstream` class.
/// 
///  @ref bslstl_osyncstream :
///       Provide a C++20-compatible @ref basic_osyncstream  class template.
/// 
///  @ref bslstl_ownerequal :
///       Provide an ownership comparison for shared and weak pointers.
/// 
///  @ref bslstl_ownerhash :
///       Provide an ownership hash functor for shared and weak pointers.
/// 
///  @ref bslstl_ownerless :
///       Provide an ordering for shared and weak pointers.
/// 
///  @ref bslstl_pair :
///       Provide a simple `struct` with two members that may use allocators.
/// 
///  @ref bslstl_priorityqueue :
///       Provide container adapter class template @ref priority_queue .
/// 
///  'bslstl_priorityqueue_cpp03':                                       !PRIVATE!
///       Provide C++03 implementation for bslstl_priorityqueue.h
/// 
///  @ref bslstl_queue :
///       Provide container adapter class template `queue`.
/// 
///  'bslstl_queue_cpp03':                                               !PRIVATE!
///       Provide C++03 implementation for bslstl_queue.h
/// 
///  @ref bslstl_randomaccessiterator :
///       Provide a template to create STL-compliant random access iterators.
/// 
///  @ref bslstl_ratio :
///       Provide functionality of the corresponding C++ Standard header.
/// 
///  @ref bslstl_referencewrapper :
///       Provide copyable, assignable object wrapper for references.
/// 
///  'bslstl_set':
///       Provide an STL-compliant set class.
/// 
///  'bslstl_set_cpp03':                                                 !PRIVATE!
///       Provide C++03 implementation for bslstl_set.h
/// 
///  'bslstl_set_test':                                                  !PRIVATE!
///       Provide support for the `bslstl_set.t.cpp` test driver.
/// 
///  @ref bslstl_setcomparator :
///       Provide a comparator for `TreeNode` objects and a lookup key.
/// 
///  @ref bslstl_sharedptr :
///       Provide a generic reference-counted shared pointer wrapper.
/// 
///  'bslstl_sharedptr_cpp03':                                           !PRIVATE!
///       Provide C++03 implementation for bslstl_sharedptr.h
/// 
///  @ref bslstl_sharedptrallocateinplacerep :
///       Provide an in-place implementation of `bslma::SharedPtrRep`.
/// 
///  @ref bslstl_sharedptrallocateoutofplacerep :
///       Provide an out-of-place implementation of `bslma::SharedPtrRep`.
/// 
///  @ref bslstl_simplepool :
///       Provide efficient allocation of memory blocks for a specific type.
/// 
///  @ref bslstl_span :
///       Provide a (mostly) standard-compliant `span` class template.
/// 
///  @ref bslstl_stack :
///       Provide an STL-compliant stack class.
/// 
///  'bslstl_stack_cpp03':                                               !PRIVATE!
///       Provide C++03 implementation for bslstl_stack.h
/// 
///  @ref bslstl_stdexceptutil :
///       Provide a utility to throw standard exceptions.
/// 
///  @ref bslstl_stopstate :
///       Provide a stop state for `std`-compliant stop tokens.
/// 
///  @ref bslstl_stoptoken :
///       Provide an allocator-aware standard-compliant @ref stop_source  type.
/// 
///  @ref bslstl_string :
///       Provide a standard-compliant @ref basic_string  class template.
/// 
///  'bslstl_string_test':                                               !PRIVATE!
///       Provide support for the `bslstl_string.t.cpp` test driver.
/// 
///  @ref bslstl_stringbuf :
///       Provide a C++03-compatible `stringbuf` class.
/// 
///  @ref bslstl_stringref :
///       Provide a reference to a `const` string.
/// 
///  @ref bslstl_stringrefdata :
///       Provide a base class for `bslstl::StringRef`.
/// 
///  @ref bslstl_stringstream :
///       Provide a C++03-compatible `stringstream` class.
/// 
///  @ref bslstl_stringview :
///       Provide a standard-compliant `basic_string_view` class template.
/// 
///  @ref bslstl_syncbuf :
///       Provide a C++20-compatible @ref basic_syncbuf  class template.
/// 
///  @ref bslstl_syncbufbase :
///       Provide an allocator-independent base-class for @ref basic_syncbuf .
/// 
///  @ref bslstl_systemerror :
///       Provide a standard compliant @ref system_error  class.
/// 
///  @ref bslstl_treeiterator :
///       Provide an STL compliant iterator for a tree of `TreeNode` objects.
/// 
///  @ref bslstl_treenode :
///       Provide a POD-like tree node type holding a parameterized value.
/// 
///  @ref bslstl_treenodepool :
///       Provide efficient creation of nodes used in tree-based container.
/// 
///  'bslstl_treenodepool_cpp03':                                        !PRIVATE!
///       Provide C++03 implementation for bslstl_treenodepool.h
/// 
///  @ref bslstl_typeindex :
///       Provide an value-semantic type to represent @ref type_info  objects.
/// 
///  @ref bslstl_unorderedmap :
///       Provide an STL-compliant `unordered_map` container.
/// 
///  'bslstl_unorderedmap_cpp03':                                        !PRIVATE!
///       Provide C++03 implementation for bslstl_unorderedmap.h
/// 
///  'bslstl_unorderedmap_test':                                         !PRIVATE!
///       Provide support for the `bslstl_unorderedmap.t.cpp` test driver.
/// 
///  @ref bslstl_unorderedmapkeyconfiguration :
///       Provide a class template to extract keys as the `first` attribute.
/// 
///  @ref bslstl_unorderedmultimap :
///       Provide an STL-compliant @ref unordered_multimap  container.
/// 
///  'bslstl_unorderedmultimap_cpp03':                                   !PRIVATE!
///       Provide C++03 implementation for bslstl_unorderedmultimap.h
/// 
///  'bslstl_unorderedmultimap_test':                                    !PRIVATE!
///       Provide support for the `bslstl_unorderedmultimap.t.cpp` test driver.
/// 
///  @ref bslstl_unorderedmultiset :
///       Provide an STL-compliant @ref unordered_multiset  container.
/// 
///  'bslstl_unorderedmultiset_cpp03':                                   !PRIVATE!
///       Provide C++03 implementation for bslstl_unorderedmultiset.h
/// 
///  'bslstl_unorderedmultiset_test':                                    !PRIVATE!
///       Provide support for the `bslstl_unorderedmultiset.t.cpp` test driver.
/// 
///  @ref bslstl_unorderedset :
///       Provide an STL-compliant `unordered_set` container.
/// 
///  'bslstl_unorderedset_cpp03':                                        !PRIVATE!
///       Provide C++03 implementation for bslstl_unorderedset.h
/// 
///  'bslstl_unorderedset_test':                                         !PRIVATE!
///       Provide support for the `bslstl_unorderedset.t.cpp` test driver.
/// 
///  @ref bslstl_unorderedsetkeyconfiguration :
///       Provide a configuration class to use a whole object as its own key.
/// 
///  @ref bslstl_utility :
///       Provide implementations for utilities not in the system library.
/// 
///  @ref bslstl_variant :
///       Provide a standard-compliant allocator aware variant type.
/// 
///  'bslstl_variant_cpp03':                                             !PRIVATE!
///       Provide C++03 implementation for bslstl_variant.h
/// 
///  @ref bslstl_vector :
///       Provide an STL-compliant vector class.
/// 
///  'bslstl_vector_cpp03':                                              !PRIVATE!
///       Provide C++03 implementation for bslstl_vector.h
///
/// @}
/** @} */