bslx_streambufoutstream.h

Go to the documentation of this file.

/// @file bslx_streambufoutstream.h
///
/// The content of this file has been pre-processed for Doxygen.
///
 
 
// bslx_streambufoutstream.h                                          -*-C++-*-
#ifndef INCLUDED_BSLX_STREAMBUFOUTSTREAM
#define INCLUDED_BSLX_STREAMBUFOUTSTREAM
 
#include <bsls_ident.h>
BSLS_IDENT("$Id: $")
 
/// @defgroup bslx_streambufoutstream bslx_streambufoutstream
/// @brief  Externalization of fundamental types to a `bsl::streambuf`.
/// @addtogroup bsl
/// @{
/// @addtogroup bslx
/// @{
/// @addtogroup bslx_streambufoutstream
/// @{
///
/// <h1> Outline </h1>
/// * <a href="#bslx_streambufoutstream-purpose"> Purpose</a>
/// * <a href="#bslx_streambufoutstream-classes"> Classes </a>
/// * <a href="#bslx_streambufoutstream-description"> Description </a>
///   * <a href="#bslx_streambufoutstream-versioning"> Versioning </a>
///   * <a href="#bslx_streambufoutstream-usage"> Usage </a>
///     * <a href="#bslx_streambufoutstream-example-1-basic-externalization"> Example 1: Basic Externalization </a>
///
/// # Purpose {#bslx_streambufoutstream-purpose}
/// Externalization of fundamental types to a `bsl::streambuf`.
///
/// # Classes {#bslx_streambufoutstream-classes}
///
/// -  bslx::StreambufOutStream: `bsl::streambuf` output for fundamentals
///
/// @see  bslx_streambufinstream, bslx_genericoutstream
///
/// # Description {#bslx_streambufoutstream-description}
/// This component implements a `bsl::streambuf` output stream
/// class, `bslx::StreambufOutStream`, that provides platform-independent
/// output methods ("externalization") on values, and arrays of values, of
/// fundamental types, and on `bsl::string`.
///
/// This component is intended to be used in conjunction with the
/// @ref bslx_streambufinstream  "unexternalization" component.  Each output method
/// of `bslx::StreambufOutStream` writes a value or a homogeneous array of
/// values to a `bsl::streambuf`.  The values are formatted to be readable by
/// the corresponding `bslx::StreambufInStream` method.  In general, the user
/// cannot rely on any other mechanism to read data written by
/// `bslx::StreambufOutStream` unless that mechanism explicitly states its
/// ability to do so.
///
/// The supported types and required content are listed in the `bslx`
/// package-level documentation under "Supported Types".
///
/// Note that the values are stored in big-endian (i.e., network byte order)
/// format.
///
/// Note that output streams can be *invalidated* explicitly and queried for
/// *validity*.  Writing to an initially invalid stream has no effect.  Whenever
/// an output operation fails, the stream should be invalidated explicitly.
///
/// ## Versioning {#bslx_streambufoutstream-versioning}
///
///
/// BDEX provides two concepts that support versioning the BDEX serialization
/// format of a type: `version` and `versionSelector`.  A `version` is a 1-based
/// integer indicating one of the supported formats (e.g., format 1, format 2,
/// etc.).  A `versionSelector` is a value that is mapped to a `version` for a
/// type by the type's implementation of `maxSupportedBdexVersion`.
///
/// Selecting a value for a `versionSelector` is required at two different
/// points: (1) when implementing a new `version` format within the
/// `bdexStreamIn` and `bdexStreamOut` methods of a type, and (2) when
/// implementing code that constructs a BDEX `OutStream`.  In both cases, the
/// value should be a *compile*-time-selected value.
///
/// When a new `version` format is implemented within the `bdexStreamIn` and
/// `bdexStreamOut` methods of a type, a new mapping in
/// `maxSupportedBdexVersion` should be created to expose this new `version`
/// with a `versionSelector`.  A simple - and the recommended - approach is to
/// use a value having the pattern "YYYYMMDD", where "YYYYMMDD" corresponds to
/// the "go-live" date of the corresponding `version` format.
///
/// When constructing an `OutStream`, a simple approach is to use the current
/// date as a *compile*-time constant value.  In combination with the
/// recommended selection of `versionSelector` values for
/// `maxSupportedBdexVersion`, this will result in consistent and predictable
/// behavior while externalizing types.  Note that this recommendation is chosen
/// for its simplicity: to ensure the largest possible audience for an
/// externalized representation, clients can select the minimum date value that
/// will result in the desired version of all types externalized with
/// `operator<<` being selected.
///
/// See the `bslx` package-level documentation for more detailed information
/// about versioning.
///
/// ## Usage {#bslx_streambufoutstream-usage}
///
///
/// This section illustrates intended use of this component.
///
/// ### Example 1: Basic Externalization {#bslx_streambufoutstream-example-1-basic-externalization}
///
///
/// A `bslx::StreambufOutStream` can be used to externalize values in a
/// platform-neutral way.  Writing out fundamental C++ types and `bsl::string`
/// requires no additional work on the part of the client; the client can simply
/// use the stream directly.  The following code serializes a few representative
/// values using a `bslx::StreambufOutStream`, compares the contents of this
/// stream to the expected value, and then writes the contents of this stream's
/// buffer to `stdout`.
///
/// First, we create a `bslx::StreambufOutStream` with an arbitrary value for
/// its `versionSelector` and externalize some values:
/// @code
/// bsl::stringbuf               buffer;
/// bslx::StreambufOutStream outStream(&buffer, 20131127);
/// outStream.putInt32(1);
/// outStream.putInt32(2);
/// outStream.putInt8('c');
/// outStream.putString(bsl::string("hello"));
/// @endcode
/// Then, we compare the contents of the stream to the expected value:
/// @code
/// bsl::string  theChars = buffer.str();
/// ASSERT(15 == theChars.size());
/// ASSERT( 0 == bsl::memcmp(theChars.data(),
///                          "\x00\x00\x00\x01\x00\x00\x00\x02""c\x05""hello",
///                          15));
/// @endcode
/// Finally, we print the stream's contents to `bsl::cout`.
/// @code
/// for (bsl::size_t i = 0; i < theChars.size(); ++i) {
///     if (bsl::isalnum(static_cast<unsigned char>(theChars[i]))) {
///         bsl::cout << "nextByte (char): " << theChars[i] << bsl::endl;
///     }
///     else {
///         bsl::cout << "nextByte (int): "
///                   << static_cast<int>(theChars[i])
///                   << bsl::endl;
///     }
/// }
/// @endcode
/// Executing the above code results in the following output:
/// @code
/// nextByte (int): 0
/// nextByte (int): 0
/// nextByte (int): 0
/// nextByte (int): 1
/// nextByte (int): 0
/// nextByte (int): 0
/// nextByte (int): 0
/// nextByte (int): 2
/// nextByte (char): c
/// nextByte (int): 5
/// nextByte (char): h
/// nextByte (char): e
/// nextByte (char): l
/// nextByte (char): l
/// nextByte (char): o
/// @endcode
/// See the @ref bslx_streambufinstream  component usage example for a more
/// practical example of using `bslx` streams.
/// @}
/** @} */
/** @} */
 
/** @addtogroup bsl
 * @{
 */
/** @addtogroup bslx
 * @{
 */
/** @addtogroup bslx_streambufoutstream
 * @{
 */
 
#include <bslscm_version.h>
 
#include <bslx_genericoutstream.h>
 
#include <bsl_streambuf.h>
 
 
namespace bslx {
 
                       // ========================
                       // class StreambufOutStream
                       // ========================
 
/// This class facilitates the externalization of values (and C-style arrays
/// of values) of the fundamental integral and floating-point types in a
/// data-independent, platform-neutral representation.  It is currently a
/// `typedef` for `bslx::GenericOutStream<bsl::streambuf>`.
typedef GenericOutStream<bsl::streambuf> StreambufOutStream;
 
}  // 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 ----------------------------------
 
/** @} */
/** @} */
/** @} */