balber.h

Go to the documentation of this file.

/// @file balber.h
///
///
/// @defgroup balber Package balber
/// @brief  Basic Application Library BER (balber)
/// @addtogroup bal
/// @{
/// @addtogroup balber
/// @{
/// * <a href="#balber-purpose"> Purpose</a>
/// * <a href="#balber-mnemonic"> Mnemonic </a>
/// * <a href="#balber-description"> Description </a>
///   * <a href="#balber-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#balber-component-synopsis"> Component Synopsis </a>
///
/// # Purpose {#balber-purpose}
/// Provide encoding/decoding of data per the (binary) BER rules.
///
/// # Mnemonic {#balber-mnemonic}
/// Basic Application Library BER (balber)
///
/// # Description {#balber-description}
/// The `balber` ("Basic Application BER") package defines classes
/// that can encode and decode data per the X.690 BER (Basic Encoding Rules)
/// specification.  These classes can be used only for types supported by the
/// `bdlat` framework.  Typical usage is illustrated in
/// [balber_berdecoder](@ref balber_berdecoder-example-1-decoding-an-employee-record) 
/// and
/// [balber_berencoder](@ref balber_berencoder-example-1-encoding-an-employee-record) .
///
/// There are 2 sets of the encoding/decoding member functions:
///
/// 1. `encode` & `decode`, and
/// 2. `encodeAny` & `decodeAny` (referred as "any-functions" below).
///
/// The first set uses templates and compile-time metaprogramming to generate the
/// encoding/decoding C++ code.  The second set uses the runtime dispatch
/// approach - base classes and virtual functions - to provide the same
/// functionality.  The result does not depend on the functions you use - their
/// functionality is absolutely identical.  The difference is not in **what**
/// they do, but in **how** they do it.
///
/// As usual, the compile-time approach can be faster, but generates a lot of
/// code.  And since this code is in the headers, this causes big load on the
/// compiler and linker - the generated code is in each translation unit and in
/// the object file generated from it.  As a result, slow compilation, huge
/// memory and CPU consumption during the compilation and linking, and a larger
/// resulting executable file size.
///
/// All the above mentioned shortcomings (except the final runtime performance)
/// can be mitigated by using the "any-functions", at the cost of a small runtime
/// slowdown.  All the encoding/decoding code is pre-compiled and located in one
/// place - the BDE library (archive) files.  But how big is the execution
/// slowdown?  Our benchmarks show that the slowdown is less than 10%.
///
/// ## Hierarchical Synopsis {#balber-hierarchical-synopsis}
///
/// The 'balber' package currently has 8 components having 4 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
///  4. balber_berdecoder
///
///  3. balber_berencoder
///
///  2. balber_berencoderoptionsutil
///     balber_beruniversaltagnumber
///     balber_berutil
///
///  1. balber_berconstants
///     balber_berdecoderoptions
///     balber_berencoderoptions
/// @endcode
///
/// ## Component Synopsis {#balber-component-synopsis}
///
///  @ref balber_berconstants :
///       Provide namespace for BER-related constants.
/// 
///  @ref balber_berdecoder :
///       Provide a BER decoder class.
/// 
///  @ref balber_berdecoderoptions :
///       Provide an attribute class for specifying BER decoding options.
/// 
///  @ref balber_berencoder :
///       Provide a BER encoder class.
/// 
///  @ref balber_berencoderoptions :
///       Provide value-semantic attribute classes
/// 
///  @ref balber_berencoderoptionsutil :
///       Provide a utility for configuring `balber::BerEncoderOptions`.
/// 
///  @ref balber_beruniversaltagnumber :
///       Enumerate the set of BER universal tag numbers.
/// 
///  @ref balber_berutil :
///       Provide functions to encode and decode simple types in BER format.
///
/// @}
/** @} */