bdlde.h

Go to the documentation of this file.

/// @file bdlde.h
///
///
/// @defgroup bdlde Package bdlde
/// @brief  Basic Development Library Data Encoder (bdlde)
/// @addtogroup bdl
/// @{
/// @addtogroup bdlde
/// @{
/// * <a href="#bdlde-purpose"> Purpose</a>
/// * <a href="#bdlde-mnemonic"> Mnemonic </a>
/// * <a href="#bdlde-description"> Description </a>
///   * <a href="#bdlde-hierarchical-synopsis"> Hierarchical Synopsis </a>
///   * <a href="#bdlde-component-synopsis"> Component Synopsis </a>
///   * <a href="#bdlde-usage"> Usage </a>
///     * <a href="#bdlde-example-1-crc-32"> Example 1: CRC-32 </a>
///     * <a href="#bdlde-example-2-md5"> Example 2: MD5 </a>
///
/// # Purpose {#bdlde-purpose}
/// Mechanisms for standard encodings and hashings, e.g., base64, md5.
///
/// # Mnemonic {#bdlde-mnemonic}
/// Basic Development Library Data Encoder (bdlde)
///
/// @see 
///
/// # Description {#bdlde-description}
/// The 'bdlde' package provides mechanisms (typically in the form of
/// fully value-semantic objects) for performing various standard hashings of an
/// input dataset, for, e.g., basic encoding, check-sums, and cryptographic
/// hashes.
///
/// ## Hierarchical Synopsis {#bdlde-hierarchical-synopsis}
///
/// The 'bdlde' package currently has 23 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. bdlde_base64decoder
///
///  3. bdlde_base64encoder
///
///  2. bdlde_base64decoderoptions
///     bdlde_base64encoderoptions
///     bdlde_charconvertucs2
///     bdlde_charconvertutf16
///     bdlde_charconvertutf32
///     bdlde_utf8checkinginstreambufwrapper
///
///  1. bdlde_base64alphabet
///     bdlde_base64ignoremode
///     bdlde_byteorder
///     bdlde_charconvertstatus
///     bdlde_crc32
///     bdlde_crc32c
///     bdlde_crc64
///     bdlde_hexdecoder
///     bdlde_hexencoder
///     bdlde_md5
///     bdlde_quotedprintabledecoder
///     bdlde_quotedprintableencoder
///     bdlde_sha1
///     bdlde_sha2
///     bdlde_utf8util
/// @endcode
///
/// ## Component Synopsis {#bdlde-component-synopsis}
///
///  @ref bdlde_base64alphabet :
///       Provide an enumeration of the set of possible base 64 alphabets.
/// 
///  @ref bdlde_base64decoder :
///       Provide automata for converting to and from Base64 encodings.
/// 
///  @ref bdlde_base64decoderoptions :
///       Provide value-semantic attribute class for decoder options.
/// 
///  @ref bdlde_base64encoder :
///       Provide automata for converting to and from Base64 encodings.
/// 
///  @ref bdlde_base64encoderoptions :
///       Provide a value-semantic attribute class for encoder options.
/// 
///  @ref bdlde_base64ignoremode :
///       Provide an enumeration of the set of possible base64 ignore modes.
/// 
///  @ref bdlde_byteorder :
///       Provide an enumeration of the set of possible byte orders.
/// 
///  @ref bdlde_charconvertstatus :
///       Provide masks for interpreting status from charconvert functions.
/// 
///  @ref bdlde_charconvertucs2 :
///       Provide efficient conversions between UTF-8 and UCS-2 encodings.
/// 
///  @ref bdlde_charconvertutf16 :
///       Provide fast, safe conversion between UTF-8 and UTF-16 encodings.
/// 
///  @ref bdlde_charconvertutf32 :
///       Provide fast, safe conversion between UTF-8 encoding and UTF-32.
/// 
///  @ref bdlde_crc32 :
///       Provide a mechanism for computing the CRC-32 checksum of a dataset.
/// 
///  @ref bdlde_crc32c :
///       Provide utilities to calculate the CRC32-C checksum of a dataset.
/// 
///  @ref bdlde_crc64 :
///       Provide a mechanism for computing the CRC-64 checksum of a dataset.
/// 
///  @ref bdlde_hexdecoder :
///       Provide mechanism for decoding text from hexadecimal.
/// 
///  @ref bdlde_hexencoder :
///       Provide mechanism for encoding text into hexadecimal.
/// 
///  'bdlde_md5':
///       Provide a value-semantic type encoding a message in an MD5 digest.
/// 
///  @ref bdlde_quotedprintabledecoder :
///       Provide automata converting to and from Quoted-Printable encodings.
/// 
///  @ref bdlde_quotedprintableencoder :
///       Provide automata converting to and from Quoted-Printable encodings.
/// 
///  @ref bdlde_sha1 :
///       Provide a value-semantic type encoding a message in a SHA-1 digest.
/// 
///  @ref bdlde_sha2 :
///       Provide a value-semantic type encoding a message in a SHA-2 digest.
/// 
///  @ref bdlde_utf8checkinginstreambufwrapper :
///       Provide a stream buffer wrapper for validating UTF-8 input.
/// 
///  @ref bdlde_utf8util :
///       Provide basic utilities for UTF-8 encodings.
///
/// ## Usage {#bdlde-usage}
///
/// This section illustrates intended use of this package.
///
/// ### Example 1: CRC-32 {#bdlde-example-1-crc-32}
///
/// The following snippets of code illustrate a typical use of the 'bdlde_Crc32'
/// class.  Each function would typically execute in separate processes or
/// potentially on separate machines.  The 'senderExample' function below
/// demonstrates how a message sender can write a message and its CRC-32 checksum
/// to a 'bdlx' output stream.  Note that 'Out' may be a 'typedef' of any class
/// that implements the 'bdlx_OutStream' protocol:
/// @code
///  void senderExample(Out& output)
///      // Write a message and its CRC-32 checksum to the specified 'output'
///      // stream.
///  {
///      // prepare a message
///      bdl::string message = "This is a test message.";
///
///      // generate a checksum for 'message'
///      bdlde_Crc32 crc(message.data(), message.length());
///
///      // write the message to 'output'
///      output << message;
///
///      // write the checksum to 'output'
///      output << crc;
///  }
/// @endcode
/// The 'receiverExample' function below illustrates how a message receiver can
/// read a message and its CRC-32 checksum from a 'bdlx' input stream, then
/// perform a local CRC-32 computation to verify that the message was received
/// intact.  Note that 'In' may be a 'typedef' of any class that implements the
/// 'bdlx_InStream' protocol:
/// @code
///  void receiverExample(In& input)
///      // Read a message and its CRC-32 checksum from the specified 'input'
///      // stream, and verify the integrity of the message.
///  {
///      // read the message from 'input'
///      bdl::string message;
///      input >> message;
///
///      // read the checksum from 'input'
///      bdlde_Crc32 crc;
///      input >> crc;
///
///      // locally compute the checksum of the received 'message'
///      bdlde_Crc32 crcLocal;
///      crcLocal.update(message.data(), message.length());
///
///      // verify that the received and locally-computed checksums match
///      assert(crcLocal == crc);
///  }
/// @endcode
///
/// ### Example 2: MD5 {#bdlde-example-2-md5}
///
/// The following snippets of code illustrate a typical use of the 'bdlde_Md5'
/// class.  Each function would typically execute in separate processes or
/// potentially on separate machines.  The 'senderExample' function below
/// demonstrates how a message sender can write a message and its MD5 hash to a
/// 'bdlx' output stream.  Note that 'Out' may be a 'typedef' of any class that
/// implements the 'bdlx_OutStream' protocol:
/// @code
///  void senderExample(Out& output)
///      // Write a message and its MD5 hash to the specified 'output' stream.
///  {
///      // prepare a message
///      bdl::string message = "This is a test message.";
///
///      // generate a hash for 'message'
///      bdlde_Md5 hash(message.data(), message.length());
///
///      // write the message to 'output'
///      output << message;
///
///      // write the hash to 'output'
///      output << hash;
///  }
/// @endcode
/// The 'receiverExample' function below illustrates how a message receiver can
/// read a message and its MD5 hash from a 'bdlx' input stream, then perform a
/// local MD5 computation to verify that the message was received intact.  Note
/// that 'In' may be a 'typedef' of any class that implements the 'bdlx_InStream'
/// protocol:
/// @code
///  void receiverExample(In& input)
///      // Read a message and its MD5 hash from the specified 'input' stream,
///      // and verify the integrity of the message.
///  {
///      // read the message from 'input'
///      bdl::string message;
///      input >> message;
///
///      // read the hash from 'input'
///      bdlde_Md5 hash;
///      input >> hash;
///
///      // locally compute the hash of the received 'message'
///      bdlde_Md5 hashLocal;
///      hashLocal.update(message.data(), message.length());
///
///      // verify that the received and locally-computed hashes match
///      assert(hashLocal == hash);
///  }
/// @endcode
///
/// @}
/** @} */