bslx_outstreamfunctions.h

Go to the documentation of this file.

/// @file bslx_outstreamfunctions.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslx_outstreamfunctions.h                                          -*-C++-*-
#ifndef INCLUDED_BSLX_OUTSTREAMFUNCTIONS
#define INCLUDED_BSLX_OUTSTREAMFUNCTIONS
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslx_outstreamfunctions bslx_outstreamfunctions
/// @brief  Facilitate uniform externalization of user and fundamental types.
/// @addtogroup bsl
/// @{
/// @addtogroup bslx
/// @{
/// @addtogroup bslx_outstreamfunctions
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslx_outstreamfunctions-purpose"> Purpose</a>
/// * <a href="#bslx_outstreamfunctions-classes"> Classes </a>
/// * <a href="#bslx_outstreamfunctions-description"> Description </a>
///   * <a href="#bslx_outstreamfunctions-component-design-anticipated-usage-and-the-bdex-contract"> Component Design, Anticipated Usage, and the BDEX Contract </a>
///     * <a href="#bslx_outstreamfunctions-implementing-bdex-streaming-in-value-semantic-template-classes"> Implementing BDEX Streaming in Value-Semantic Template Classes </a>
///   * <a href="#bslx_outstreamfunctions-usage"> Usage </a>
///     * <a href="#bslx_outstreamfunctions-example-1-using-bslx-outstreamfunctions-to-externalize-data"> Example 1: Using bslx::OutStreamFunctions to Externalize Data </a>
///
/// # Purpose {#bslx_outstreamfunctions-purpose}
/// Facilitate uniform externalization of user and fundamental types.
///
/// # Classes {#bslx_outstreamfunctions-classes}
///
/// -  bslx::OutStreamFunctions: namespace for BDEX externalization functions
///
/// @see  bslx_instreamfunctions, bslx_versionfunctions
///
/// # Description {#bslx_outstreamfunctions-description}
/// This component provides a namespace,
/// `bslx::OutStreamFunctions`, that facilitates uniform support for BDEX
/// externalization across all BDEX-compliant user-defined types, including
/// template types and containers, as well as those fundamental types (and
/// `bsl::string` and `bsl::vector`) for which the BDEX protocol provides direct
/// support.
///
/// The namespace `bslx::OutStreamFunctions` facilitates client externalization
/// of objects in a uniform, type-independent manner.  It contains the
/// `bdexStreamOut` function that externalizes objects of all BDEX-compliant
/// types.  This function externalizes the specified `object` in the specified
/// `version`.  The `bdexStreamOut` function is overloaded for fundamental
/// types, enumeration types, `bsl::string`, and `bsl::vector`.  Note that,
/// excluding `bsl::vector`, version information is never written to the stream
/// while externalizing these types.
///
/// By default, objects of enumeration type are streamed out as 32-bit `int`
/// values.  Users can override this behavior by providing overloads of the
/// `OutStreamFunctions::bdexStreamOut` function in the enumeration's namespace
/// for their enumeration types.  The general form of this overload is:
/// @code
/// template <class STREAM>
/// STREAM& bdexStreamOut(STREAM& stream, const MyEnum& value, int version)
/// {
///     using bslx::OutStreamFunctions::bdexStreamOut;
///
///     // Code to stream out objects of 'MyEnum' type.
///
///     return stream;
/// }
/// @endcode
/// For value-semantic types that support the BDEX protocol, the free function
/// `bdexStreamOut` calls the `bdexStreamOut` member function for that type.
///
/// ## Component Design, Anticipated Usage, and the BDEX Contract {#bslx_outstreamfunctions-component-design-anticipated-usage-and-the-bdex-contract}
///
///
/// @ref bslx_outstreamfunctions  is an integral part of the BDEX externalization
/// contract.  The BDEX contract is at least in part "collaborative", which is
/// to say that each developer of a given *kind* of component (e.g., a stream or
/// a value-semantic container) must comply with the relevant portions of the
/// contract to ensure that the "system as a whole" works for everybody.
/// @ref bslx_outstreamfunctions  plays several related but different roles in
/// helping various developers to produce BDEX-compliant components.  In this
/// section we briefly highlight how and why @ref bslx_outstreamfunctions  is
/// helpful (or required) for these different developers.  By discussing
/// different aspects of usage, we convey the general design goals of this
/// component, and, to a certain extent, the overall BDEX contract.  See the
/// `bslx` package-level documentation for a full specification of the BDEX
/// contract.
///
/// ### Implementing BDEX Streaming in Value-Semantic Template Classes {#bslx_outstreamfunctions-implementing-bdex-streaming-in-value-semantic-template-classes}
///
///
/// The author of a non-template value-semantic type has full knowledge of the
/// details of the "value" of that type, and may choose to use the appropriate
/// output stream `put` methods directly when implementing the required
/// `bdexStreamOut` method for that type.  However, if one or more aspects of
/// the value are of template parameter type, then the author cannot in general
/// know how to stream the value using the `put` methods.  For example, if a
/// type has as its value one `int` data member:
/// @code
/// int d_value;
/// @endcode
/// then the implementation of the `bdexStreamOut` method can contain:
/// @code
/// stream.putInt32(d_value);
/// @endcode
/// However, if the data member is of (template parameter) `TYPE`:
/// @code
/// TYPE d_value;
/// @endcode
/// then the implementation of the `bdexStreamOut` method must rely on the
/// `bslx::OutStreamFunctions` implementation to output the value:
/// @code
/// using bslx::OutStreamFunctions::bdexStreamOut;
/// bdexStreamOut(stream, d_value, 1);
/// @endcode
/// This call will resolve to the correct sequence of `put` calls no matter
/// whether `TYPE` is a fundamental type, a BDEX-compliant `enum`, or a proper
/// BDEX-compliant class.  In the latter two cases, the explicit specification
/// of the version format (in this case, 1) guarantees the stable operation of
/// this method whether or not `TYPE` is provided additional version formats.
///
/// ## Usage {#bslx_outstreamfunctions-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Using bslx::OutStreamFunctions to Externalize Data {#bslx_outstreamfunctions-example-1-using-bslx-outstreamfunctions-to-externalize-data}
///
///
/// In this example we illustrate the primary intended use of the parameterized
/// methods of this component, as well as a few trivial invocations just to show
/// the syntax clearly.  To accomplish this, we exhibit two separate example
/// "components": a value-semantic point object, and an `enum`.  In all cases,
/// the component designs are very simple, with much of the implied
/// functionality omitted, in order to focus attention on the key aspects of the
/// functionality of *this* component.
///
/// First, consider an `enum` `Color` that enumerates a set of colors:
/// @code
/// enum Color {
///     RED   = 0,
///     GREEN = 1,
///     BLUE  = 2
/// };
/// @endcode
/// Next, we consider a very special-purpose point that has as a data member its
/// color.  Such a point provides an excellent opportunity for factoring, but
/// since we are interested in highlighting BDEX streaming of various types, we
/// will present a simple and unfactored design here.  In a real-world problem,
/// the `mypoint` component would be implemented differently.
///
/// Note that the `MyPoint` class in this example represents its coordinates as
/// `short` integer values; this is done to make the BDEX stream output byte
/// pattern somewhat easier for the reader of this example to recognize when the
/// output buffer is printed.
/// @code
/// // mypoint.h
///
/// class MyPoint {
///     // This class provides a geometric point having integer coordinates and
///     // an enumerated color property.
///
///     short d_x;      // x coordinate
///     short d_y;      // y coordinate
///     Color d_color;  // enumerated color property
///
///   public:
///     // CLASS METHODS
///     static int maxSupportedBdexVersion(int versionSelector);
///         // Return the maximum valid BDEX format version, as indicated by
///         // the specified 'versionSelector', to be passed to the
///         // 'bdexStreamOut' method.  Note that it is highly recommended that
///         // versionSelector' be formatted as "YYYYMMDD", a date
///         // representation.  Also note that 'versionSelector' should be a
///         // *compile*-time-chosen value that selects a format version
///         // supported by both externalizer and unexternalizer.  See the
///         // 'bslx' package-level documentation for more information on BDEX
///         // streaming of value-semantic types and containers.
///
///     // CREATORS
///     MyPoint();
///         // Create a default point.
///
///     MyPoint(short x, short y, Color color);
///         // Create a point having the specified 'x' and 'y' coordinates
///         // and the specified 'color'.
///
///     ~MyPoint();
///         // Destroy this point.
///
///     // MANIPULATORS
///     // ...
///
///     // ACCESSORS
///     int x() const;
///         // Return the x coordinate of this point.
///
///     int y() const;
///         // Return the y coordinate of this point.
///
///     Color color() const;
///         // Return the enumerated color of this point.
///
///     template <class STREAM>
///     STREAM& bdexStreamOut(STREAM& stream, int version) const;
///         // Write the value of this object, using the specified 'version'
///         // format, to the specified output 'stream', and return a reference
///         // to 'stream'.  If 'stream' is initially invalid, this operation
///         // has no effect.  If 'version' is not supported, 'stream' is
///         // invalidated, but otherwise unmodified.  Note that 'version' is
///         // not written to 'stream'.  See the 'bslx' package-level
///         // documentation for more information on BDEX streaming of
///         // value-semantic types and containers.
/// };
///
/// // FREE OPERATORS
/// inline
/// bool operator==(const MyPoint& lhs, const MyPoint& rhs);
///     // Return 'true' if the specified 'lhs' and 'rhs' points have the same
///     // value, and 'false' otherwise.  Two points have the same value if
///     // they have the same x and y coordinates and the same color.
/// @endcode
/// Representative (inline) implementations of these methods are shown below:
/// @code
/// // ========================================================================
/// //                      INLINE FUNCTION DEFINITIONS
/// // ========================================================================
///
/// // CLASS METHODS
/// inline
/// int MyPoint::maxSupportedBdexVersion(int versionSelector)
/// {
///     if (versionSelector >= 20131201) {
///         return 2;
///     }
///     return 1;
/// }
///
/// // CREATORS
/// inline
/// MyPoint::MyPoint(short x, short y, Color color)
/// : d_x(x)
/// , d_y(y)
/// , d_color(color)
/// {
/// }
///
/// inline
/// MyPoint::~MyPoint()
/// {
/// }
///
/// // ...
///
/// // MANIPULATORS
/// // ...
///
/// // ACCESSORS
/// inline
/// int MyPoint::x() const
/// {
///     return d_x;
/// }
///
/// // ...
///
/// template <class STREAM>
/// STREAM& MyPoint::bdexStreamOut(STREAM& stream, int version) const
/// {
///     switch (version) {
///       case 1: {
///         stream.putInt16(d_x);          // output the x coordinate
///         stream.putInt16(d_y);          // output the y coordinate
///         stream.putInt8(static_cast<char>(d_color));
///                                        // output the color enum as one byte
///       } break;
///       default: {
///         stream.invalidate();
///       } break;
///     }
///     return stream;
/// }
///
/// // FREE OPERATORS
/// inline
/// bool operator==(const MyPoint& lhs, const MyPoint& rhs)
/// {
///     return lhs.x()     == rhs.x()
///         && lhs.y()     == rhs.y()
///         && lhs.color() == rhs.color();
/// }
/// @endcode
/// Then, we will implement an extremely simple output stream that supports the
/// BDEX documentation-only protocol.  For simplicity, we will use a fixed-size
/// buffer (usually a bad idea in any event, and more so here since the
/// implementation knows the buffer size, but makes no effort to prevent
/// overwriting that buffer), and will only show a few methods needed for this
/// example.  See other `bslx` stream components for examples of
/// properly-designed BDEX streams.
/// @code
/// // myoutstream.h
/// // ...
///
/// class MyOutStream {
///     // This class implements a limited-size fixed-buffer output stream that
///     // partially conforms to the BDEX protocol for output streams.  This
///     // class is suitable for demonstration purposes only.
///
///     char d_buffer[1000]; // externalized values stored as contiguous bytes
///
///     int  d_length;       // length of data in 'd_buffer' (in bytes)
///
///     bool d_validFlag;    // stream validity flag; 'true' if stream is in
///                          // valid state, 'false' otherwise
///
///   public:
///     // CREATORS
///     MyOutStream();
///         // Create an empty output stream of limited, fixed capacity.  Note
///         // that this object is suitable for demonstration purposes only.
///
///     ~MyOutStream();
///        // Destroy this output stream.
///
///     // MANIPULATORS
///     void invalidate();
///         // Put this input stream in an invalid state.  This function has no
///         // effect if this stream is already invalid.  Note that this
///         // function should be called whenever a value extracted from this
///         // stream is determined to be invalid, inconsistent, or otherwise
///         // incorrect.
///
///     MyOutStream& putVersion(int version);
///         // Write to this stream the one-byte, two's complement integer
///         // comprised of the least-significant one byte of the specified
///         // 'version', and return a reference to this stream.
///
///     MyOutStream& putInt32(int value);
///         // Write to this stream the four-byte, two's complement integer (in
///         // network byte order) comprised of the least-significant four
///         // bytes of the specified 'value' (in host byte order), and return
///         // a reference to this stream.
///
///     MyOutStream& putInt16(int value);
///         // Write to this stream the two-byte, two's complement integer
///         // (in network byte order) comprised of the least-significant two
///         // bytes of the specified 'value' (in host byte order), and return
///         // a reference to this stream.
///
///     MyOutStream& putInt8(int value);
///         // Write to this stream the one-byte, two's complement integer
///         // comprised of the least-significant one byte of the specified
///         // 'value', and return a reference to this stream.
///
///     void removeAll();
///         // Remove all content in this stream.
///
///     // ACCESSORS
///     const char *data() const;
///         // Return the address of the contiguous, non-modifiable internal
///         // memory buffer of this stream.  The address will remain valid as
///         // long as this stream is not destroyed or modified.  The behavior
///         // of accessing elements outside the range
///         // '[ data() .. data() + (length() - 1) ]' is undefined.
///
///     int length() const;
///         // Return the number of bytes in this stream.
/// };
///
/// // FREE OPERATORS
/// inline
/// bsl::ostream& operator<<(bsl::ostream&      stream,
///                          const MyOutStream& object);
///     // Write the specified 'object' to the specified output 'stream' in
///     // some reasonable (multi-line) format, and return a reference to
///     // 'stream'.
/// @endcode
/// The relevant (inline) implementations are as follows.
/// @code
/// // ========================================================================
/// //                      INLINE FUNCTION DEFINITIONS
/// // ========================================================================
///
/// // CREATORS
/// inline
/// MyOutStream::MyOutStream()
/// : d_length(0)
/// , d_validFlag(true)
/// {
/// }
///
/// inline
/// MyOutStream::~MyOutStream()
/// {
/// }
///
/// // MANIPULATORS
/// inline
/// void MyOutStream::invalidate()
/// {
///     d_validFlag = false;
/// }
///
/// inline
/// MyOutStream& MyOutStream::putVersion(int value)
/// {
///     d_buffer[d_length] = static_cast<char>(value);
///     ++d_length;
///     return *this;
/// }
///
/// inline
/// MyOutStream& MyOutStream::putInt32(int value)
/// {
///     d_buffer[d_length + 0] = static_cast<char>((value >> 24) & 0xff);
///     d_buffer[d_length + 1] = static_cast<char>((value >> 16) & 0xff);
///     d_buffer[d_length + 2] = static_cast<char>((value >>  8) & 0xff);
///     d_buffer[d_length + 3] = static_cast<char>((value >>  0) & 0xff);
///     d_length += 4;
///     return *this;
/// }
///
/// inline
/// MyOutStream& MyOutStream::putInt16(int value)
/// {
///     d_buffer[d_length + 0] = static_cast<char>((value >> 8) & 0xff);
///     d_buffer[d_length + 1] = static_cast<char>((value >> 0) & 0xff);
///     d_length += 2;
///     return *this;
/// }
///
/// inline
/// MyOutStream& MyOutStream::putInt8(int value)
/// {
///     d_buffer[d_length] = static_cast<char>(value);
///     d_length += 1;
///     return *this;
/// }
///
/// inline
/// void MyOutStream::removeAll()
/// {
///     d_length = 0;
/// }
///
/// // ACCESSORS
/// inline
/// const char *MyOutStream::data() const
/// {
///     return static_cast<const char *>(d_buffer);
/// }
///
/// inline
/// int MyOutStream::length() const
/// {
///     return d_length;
/// }
/// @endcode
/// Finally, use the above `enum`, point class, and output stream to illustrate
/// `bslx::OutStreamFunctions` functionality.  This test code does not attempt
/// to do anything more useful than writing known values to a stream and
/// confirming that the expected byte pattern was in fact written.
/// @code
/// int             i     = 168496141;  // byte pattern 0a 0b 0c 0d
/// Color           color = BLUE;       // byte pattern 02
/// MyPoint         p(0, -1, color);    // byte pattern 00 00 ff ff 02
///
/// using bslx::OutStreamFunctions::bdexStreamOut;
///
/// MyOutStream out;
/// assert(0 == out.length());
///
/// bdexStreamOut(out, i, 1);
/// assert(4 == out.length());
/// assert(0 == bsl::memcmp(out.data(), "\x0a\x0b\x0c\x0d", out.length()));
///
/// out.removeAll();
/// assert(0 == out.length());
///
/// bdexStreamOut(out, i, 0);
/// assert(4 == out.length());
/// assert(0 == bsl::memcmp(out.data(), "\x0a\x0b\x0c\x0d", out.length()));
///
/// out.removeAll();
/// assert(0 == out.length());
///
/// bdexStreamOut(out, color, 1);
/// assert(4 == out.length());
/// assert(0 == bsl::memcmp(out.data(), "\x00\x00\x00\x02", out.length()));
///
/// out.removeAll();
/// assert(0 == out.length());
///
/// bdexStreamOut(out, color, 0);
/// assert(4 == out.length());
/// assert(0 == bsl::memcmp(out.data(), "\x00\x00\x00\x02", out.length()));
///
/// out.removeAll();
/// assert(0 == out.length());
///
/// bdexStreamOut(out, p, 1);
/// assert(5 == out.length());
/// assert(0 == bsl::memcmp(out.data(), "\x00\x00\xff\xff\x02", out.length()));
/// @endcode
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslx
 * @{
 */
/** @addtogroup bslx_outstreamfunctions
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bslx_versionfunctions.h>
 
#include <bslmf_assert.h>
#include <bslmf_conditional.h>
#include <bslmf_isenum.h>
 
#include <bsls_types.h>
 
#include <bsl_string.h>
#include <bsl_vector.h>
#include <bsl_cstdint.h>
 
#ifndef BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
#include <bslmf_if.h>
#endif  // BDE_DONT_ALLOW_TRANSITIVE_INCLUDES
 
 
namespace bslx {
 
                         // ============================
                         // namespace OutStreamFunctions
                         // ============================
 
namespace OutStreamFunctions {
    // This namespace facilitates externalization of all BDEX-compliant types
    // in a type-independent manner.  The externalization functions are
    // overloaded for fundamental types, enumeration types, 'bsl::string', and
    // 'bsl::vector'.  A compilation error will occur if the (template
    // parameter) 'TYPE' of a non-overloaded method of
    // 'bslx::OutStreamFunctions' does not support 'bdexStreamOut' and
    // 'maxSupportedBdexVersion' (with the appropriate signatures).
 
                         // =================
                         // struct IsEnumType
                         // =================
 
    /// This `struct`, together with `IsNotEnumType` (below), is used to
    /// distinguish enumeration types from other types in function overload
    /// resolution.  This `struct` contains no interface or implementation
    /// by design, and is meant for internal use only.
    ///
    /// See @ref bslx_outstreamfunctions 
    struct IsEnumType {
    };
 
                         // ====================
                         // struct IsNotEnumType
                         // ====================
 
    /// This `struct`, together with `IsEnumType` (above), is used to
    /// distinguish enumeration types from other types in function overload
    /// resolution.  This `struct` contains no interface or implementation
    /// by design, and is meant for internal use only.
    ///
    /// See @ref bslx_outstreamfunctions 
    struct IsNotEnumType {
    };
 
    // PRIVATE CLASS METHODS
 
    /// Write the specified `value` to the specified output `stream` as a
    /// 32-bit `int`, and return a reference to `stream`.  The specified
    /// `version` is ignored.  If `stream` is initially invalid, this operation has no effect.  
    /// 
    /// \note Note that   this function is called only for
    /// enumeration types and that if `value` is outside the range of an
    /// `int32_t` the externalization will be lossy.  Also note that this
    /// function is for internal use only.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class TYPE>
    STREAM& bdexStreamOutImp(STREAM&           stream,
                             const TYPE&       value,
                             int               version,
                             const IsEnumType&);
 
    /// Write the specified `value`, using the specified `version` format,
    /// to the specified output `stream`, and return a reference to
    /// `stream`.  If `stream` is initially invalid, this operation has no
    /// effect.  If `version` is not supported by `TYPE`, `stream` is invalidated, but otherwise unmodified.  
    /// 
    /// \note Note that   `version` is not
    /// written to `stream`.  Also note that this function is for internal
    /// use only.  See the `bslx` package-level documentation for more
    /// information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM, class TYPE>
    STREAM& bdexStreamOutImp(STREAM&              stream,
                             const TYPE&          value,
                             int                  version,
                             const IsNotEnumType&);
 
    // CLASS METHODS
 
    /// Write the specified `value` to the specified output `stream`, and
    /// return a reference to `stream`.  If `stream` is initially invalid,
    /// this operation has no effect.  If needed, first write the computed
    /// version information to the `stream` and if this version is not supported by `TYPE`, `stream` is invalidated.  
    /// 
    /// \note Note that   the version
    /// is only needed when the (template parameter) `TYPE` is a
    /// `bsl::vector` or a user-defined type.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class TYPE>
    STREAM& bdexStreamOut(STREAM& stream, const TYPE& value);
 
    /// Write the specified `value`, using the specified `version` format,
    /// to the specified output `stream`, and return a reference to
    /// `stream`.  If `stream` is initially invalid, this operation has no
    /// effect.  If `version` is not supported by `TYPE`, `stream` is invalidated, but otherwise unmodified.  
    /// 
    /// \note Note that   `version` is not
    /// written to `stream`.  See the `bslx` package-level documentation for
    /// more information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM, class TYPE>
    STREAM& bdexStreamOut(STREAM& stream, const TYPE& value, int version);
 
                       /* overloads */
 
    /// Write the specified `bool` `value` to the specified output `stream`,
    /// and return a reference to `stream`.  The optionally specified
    /// `version` is ignored.  If `stream` is initially invalid, this
    /// operation has no effect.  See the `bslx` package-level documentation
    /// for more information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM& stream, const bool& value, int version = 0);
 
    /// Write the specified `char` `value` to the specified output `stream`,
    /// and return a reference to `stream`.  The optionally specified
    /// `version` is ignored.  If `stream` is initially invalid, this
    /// operation has no effect.  See the `bslx` package-level documentation
    /// for more information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM& stream, const char& value, int version = 0);
 
    /// Write the specified `signed char` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&            stream,
                          const signed char& value,
                          int                version = 0);
 
    /// Write the specified `unsigned char` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&              stream,
                          const unsigned char& value,
                          int                  version = 0);
 
    /// Write the specified `short` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&      stream,
                          const short& value,
                          int          version = 0);
 
    /// Write the specified `unsigned short` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&               stream,
                          const unsigned short& value,
                          int                   version = 0);
 
    /// Write the specified `int` `value` to the specified output `stream`,
    /// and return a reference to `stream`.  The optionally specified
    /// `version` is ignored.  If `stream` is initially invalid, this
    /// operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM& stream, const int& value, int version = 0);
 
    /// Write the specified `unsigned int` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&             stream,
                          const unsigned int& value,
                          int                 version = 0);
 
    /// Write the specified `long` `value` to the specified output `stream`
    /// as a 32-bit `int`, and return a reference to `stream`.  The
    /// optionally specified `version` is ignored.  If `stream` is initially invalid, this operation has no effect.  
    /// 
    /// \note Note that   for platforms
    /// where `long` is not equivalent to `int32_t`, this operation may be
    /// lossy.  See the `bslx` package-level documentation for more
    /// information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM& stream, const long& value, int version = 0);
 
    /// Write the specified `unsigned long` `value` to the specified output
    /// `stream` as a 32-bit `unsigned int`, and return a reference to
    /// `stream`.  The optionally specified `version` is ignored.  If
    /// `stream` is initially invalid, this operation has no effect.  
    /// 
    /// \note Note that   for platforms where `unsigned long` is not equivalent to
    /// `uint32_t`, this operation may be lossy.  See the `bslx`
    /// package-level documentation for more information on BDEX streaming
    /// of value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&              stream,
                          const unsigned long& value,
                          int                  version = 0);
 
    /// Write the specified `bsls::Types::Int64` `value` to the specified
    /// output `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&                   stream,
                          const bsls::Types::Int64& value,
                          int                       version = 0);
 
    /// Write the specified `bsls::Types::Uint64` `value` to the specified
    /// output `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&                    stream,
                          const bsls::Types::Uint64& value,
                          int                        version = 0);
 
    /// Write the specified `float` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM& stream, const float& value, int version = 0);
 
    /// Write the specified `double` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&       stream,
                          const double& value,
                          int           version = 0);
 
    /// Write the specified `bsl::string` `value` to the specified output
    /// `stream`, and return a reference to `stream`.  The optionally
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM>
    STREAM& bdexStreamOut(STREAM&            stream,
                          const bsl::string& value,
                          int                version = 0);
 
    /// Write the specified `bsl::vector<char, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                         stream,
                          const bsl::vector<char, ALLOC>& value,
                          int                             version);
 
    /// Write the specified `bsl::vector<signed char, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                                stream,
                          const bsl::vector<signed char, ALLOC>& value,
                          int                                    version);
 
    /// Write the specified `bsl::vector<unsigned char, ALLOC>` `value` to
    /// the specified output `stream`, and return a reference to `stream`.
    /// The specified `version` is ignored.  If `stream` is initially
    /// invalid, this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                                  stream,
                          const bsl::vector<unsigned char, ALLOC>& value,
                          int                                      version);
 
    /// Write the specified `bsl::vector<short, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                          stream,
                          const bsl::vector<short, ALLOC>& value,
                          int                              version);
 
    /// Write the specified `bsl::vector<unsigned short, ALLOC>` `value` to
    /// the specified output `stream`, and return a reference to `stream`.
    /// The specified `version` is ignored.  If `stream` is initially
    /// invalid, this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                                   stream,
                          const bsl::vector<unsigned short, ALLOC>& value,
                          int                                       version);
 
    /// Write the specified `bsl::vector<int, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                        stream,
                          const bsl::vector<int, ALLOC>& value,
                          int                            version);
 
    /// Write the specified `bsl::vector<unsigned int, ALLOC>` `value` to
    /// the specified output `stream`, and return a reference to `stream`.
    /// The specified `version` is ignored.  If `stream` is initially
    /// invalid, this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                                 stream,
                          const bsl::vector<unsigned int, ALLOC>& value,
                          int                                     version);
 
    /// Write the specified `bsl::vector<bsls::Types::Int64, ALLOC>` `value`
    /// to the specified output `stream`, and return a reference to
    /// `stream`.  The specified `version` is ignored.  If `stream` is
    /// initially invalid, this operation has no effect.  See the `bslx`
    /// package-level documentation for more information on BDEX streaming
    /// of value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(
                        STREAM&                                       stream,
                        const bsl::vector<bsls::Types::Int64, ALLOC>& value,
                        int                                           version);
 
    /// Write the specified `bsl::vector<bsls::Types::Uint64, ALLOC>`
    /// `value` to the specified output `stream`, and return a reference to
    /// `stream`.  The specified `version` is ignored.  If `stream` is
    /// initially invalid, this operation has no effect.  See the `bslx`
    /// package-level documentation for more information on BDEX streaming
    /// of value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(
                       STREAM&                                        stream,
                       const bsl::vector<bsls::Types::Uint64, ALLOC>& value,
                       int                                            version);
 
    /// Write the specified `bsl::vector<float, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                          stream,
                          const bsl::vector<float, ALLOC>& value,
                          int                              version);
 
    /// Write the specified `bsl::vector<double, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  The
    /// specified `version` is ignored.  If `stream` is initially invalid,
    /// this operation has no effect.  See the `bslx` package-level
    /// documentation for more information on BDEX streaming of
    /// value-semantic types and containers.
    template <class STREAM, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                           stream,
                          const bsl::vector<double, ALLOC>& value,
                          int                               version);
 
    /// Write the specified `bsl::vector<TYPE, ALLOC>` `value` to the
    /// specified output `stream`, and return a reference to `stream`.  If
    /// `stream` is initially invalid, this operation has no effect.  If
    /// needed, first write the computed version information to the `stream`
    /// and if this version is not supported by `TYPE` and the vector is not empty, `stream` is invalidated.  
    /// 
    /// \note Note that   the version is only
    /// needed when the (template parameter) `TYPE` is a `bsl::vector` or a
    /// user-defined type.  See the `bslx` package-level documentation for
    /// more information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM, class TYPE, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                         stream,
                          const bsl::vector<TYPE, ALLOC>& value);
 
    /// Write the specified `bsl::vector<TYPE, ALLOC>` `value`, using the
    /// specified `version` format, to the specified output `stream`, and
    /// return a reference to `stream`.  If `stream` is initially invalid,
    /// this operation has no effect.  If `version` is not supported by
    /// `TYPE` and the vector is not empty, `stream` is invalidated, but otherwise unmodified.  
    /// 
    /// \note Note that   the specified `TYPE` might not
    /// require a `version` to be serialized and that `version` is not
    /// written to `stream`.  See the `bslx` package-level documentation for
    /// more information on BDEX streaming of value-semantic types and
    /// containers.
    template <class STREAM, class TYPE, class ALLOC>
    STREAM& bdexStreamOut(STREAM&                         stream,
                          const bsl::vector<TYPE, ALLOC>& value,
                          int                             version);
 
}  // close namespace OutStreamFunctions
 
// ============================================================================
//                          INLINE FUNCTION DEFINITIONS
// ============================================================================
 
                         // ----------------------------
                         // namespace OutStreamFunctions
                         // ----------------------------
 
template <class STREAM, class TYPE>
inline
STREAM& OutStreamFunctions::bdexStreamOutImp(STREAM&           stream,
                                             const TYPE&       value,
                                             int            /* version */,
                                             const IsEnumType&)
{
    // A compilation error indicating the next line of code implies the 'TYPE'
    // cannot be represented as a 32-bit 'int' and an overload for the
    // 'OutStreamFunctions::bdexStreamOut' function, in the enumeration's
    // namespace, should be provided.
 
    BSLMF_ASSERT(sizeof(TYPE) <= sizeof(bsl::int32_t));
 
    // Stream the 'enum' value as a 32-bit 'int'.
    return stream.putInt32(static_cast<int>(value));
}
 
template <class STREAM, class TYPE>
inline
STREAM& OutStreamFunctions::bdexStreamOutImp(STREAM&              stream,
                                             const TYPE&          value,
                                             int                  version,
                                             const IsNotEnumType&)
{
    // A compilation error indicating the next line of code implies the class
    // of 'TYPE' does not support the 'bdexStreamOut' method.
 
    return value.bdexStreamOut(stream, version);
}
 
template <class STREAM, class TYPE>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM& stream, const TYPE& value)
{
    using VersionFunctions::maxSupportedBdexVersion;
 
    const int version = maxSupportedBdexVersion(&value,
                                                stream.bdexVersionSelector());
    if (VersionFunctions::k_NO_VERSION != version) {
        stream.putVersion(version);
    }
 
    return bdexStreamOut(stream, value, version);
}
 
template <class STREAM, class TYPE>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&     stream,
                                          const TYPE& value,
                                          int         version)
{
    typedef typename bsl::conditional<bslmf::IsEnum<TYPE>::value,
                                      IsEnumType,
                                      IsNotEnumType>::type dummyType;
    return bdexStreamOutImp(stream, value, version, dummyType());
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&     stream,
                                          const bool& value,
                                          int      /* version */)
{
    return stream.putInt8(static_cast<char>(value));
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&     stream,
                                          const char& value,
                                          int      /* version */)
{
    return stream.putInt8(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&            stream,
                                          const signed char& value,
                                          int             /* version */)
{
    return stream.putInt8(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&              stream,
                                          const unsigned char& value,
                                          int               /* version */)
{
    return stream.putUint8(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&      stream,
                                          const short& value,
                                          int       /* version */)
{
    return stream.putInt16(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&               stream,
                                          const unsigned short& value,
                                          int                /* version */)
{
    return stream.putUint16(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&    stream,
                                          const int& value,
                                          int     /* version */)
{
    return stream.putInt32(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&             stream,
                                          const unsigned int& value,
                                          int              /* version */)
{
    return stream.putUint32(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&     stream,
                                          const long& value,
                                          int      /* version */)
{
    return stream.putInt32(static_cast<int>(value));
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&              stream,
                                          const unsigned long& value,
                                          int               /* version */)
{
    return stream.putUint32(static_cast<unsigned int>(value));
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&                   stream,
                                          const bsls::Types::Int64& value,
                                          int                    /* version */)
{
    return stream.putInt64(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                         STREAM&                    stream,
                                         const bsls::Types::Uint64& value,
                                         int                     /* version */)
{
    return stream.putUint64(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&      stream,
                                          const float& value,
                                          int       /* version */)
{
    return stream.putFloat32(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&       stream,
                                          const double& value,
                                          int        /* version */)
{
    return stream.putFloat64(value);
}
 
template <class STREAM>
inline
STREAM& OutStreamFunctions::bdexStreamOut(STREAM&            stream,
                                          const bsl::string& value,
                                          int             /* version */)
{
    return stream.putString(value);
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                    STREAM&                         stream,
                                    const bsl::vector<char, ALLOC>& value,
                                    int                          /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayInt8(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                             STREAM&                                stream,
                             const bsl::vector<signed char, ALLOC>& value,
                             int                                 /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayInt8(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                           STREAM&                                  stream,
                           const bsl::vector<unsigned char, ALLOC>& value,
                           int                                   /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayUint8(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                   STREAM&                          stream,
                                   const bsl::vector<short, ALLOC>& value,
                                   int                           /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayInt16(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                          STREAM&                                   stream,
                          const bsl::vector<unsigned short, ALLOC>& value,
                          int                                    /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayUint16(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                     STREAM&                        stream,
                                     const bsl::vector<int, ALLOC>& value,
                                     int                         /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayInt32(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                            STREAM&                                 stream,
                            const bsl::vector<unsigned int, ALLOC>& value,
                            int                                  /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayUint32(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                      STREAM&                                       stream,
                      const bsl::vector<bsls::Types::Int64, ALLOC>& value,
                      int                                        /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayInt64(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                     STREAM&                                        stream,
                     const bsl::vector<bsls::Types::Uint64, ALLOC>& value,
                     int                                         /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayUint64(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                   STREAM&                          stream,
                                   const bsl::vector<float, ALLOC>& value,
                                   int                           /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayFloat32(&value[0], length) : stream;
}
 
template <class STREAM, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                  STREAM&                           stream,
                                  const bsl::vector<double, ALLOC>& value,
                                  int                            /* version */)
{
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    return 0 < length ? stream.putArrayFloat64(&value[0], length) : stream;
}
 
template <class STREAM, class TYPE, class ALLOC>
inline
STREAM& OutStreamFunctions::bdexStreamOut(
                                        STREAM&                         stream,
                                        const bsl::vector<TYPE, ALLOC>& value)
{
    using VersionFunctions::maxSupportedBdexVersion;
 
    const int version = maxSupportedBdexVersion(&value,
                                                stream.bdexVersionSelector());
 
    stream.putVersion(version);
    return bdexStreamOut(stream, value, version);
}
 
template <class STREAM, class TYPE, class ALLOC>
STREAM& OutStreamFunctions::bdexStreamOut(
                                       STREAM&                         stream,
                                       const bsl::vector<TYPE, ALLOC>& value,
                                       int                             version)
{
    typedef typename bsl::vector<TYPE, ALLOC>::const_iterator Iterator;
 
    const int length = static_cast<int>(value.size());
    stream.putLength(length);
 
    for (Iterator it = value.begin(); it != value.end(); ++it) {
        bdexStreamOut(stream, *it, version);
    }
 
    return stream;
}
 
}  // close package namespace
 
 
#endif
 
// ----------------------------------------------------------------------------
// Copyright 2014 Bloomberg Finance L.P.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// ----------------------------- END-OF-FILE ----------------------------------
 
/** @} */
/** @} */
/** @} */