bslx_byteoutstream

Detailed Description

Outline

• Purpose
• Classes
• Description
  • Versioning
  • Usage
    • Example 1: Basic Externalization

Purpose

Provide a stream class for externalization of fundamental types.

Classes

• bslx::ByteOutStream: byte-array-based output stream for fundamental types

See also

bslx_byteinstream

Description

This component implements a byte-array-based output stream class, bslx::ByteOutStream, 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 unexternalization component. Each output method of bslx::ByteOutStream writes a value or a homogeneous array of values to an internally managed buffer. The values are formatted to be readable by the corresponding bslx::ByteInStream method. In general, the user cannot rely on any other mechanism to read data written by bslx::ByteOutStream 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

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

This section illustrates intended use of this component.

Example 1: Basic Externalization

A bslx::ByteOutStream 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::ByteOutStream, 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::ByteOutStream with an arbitrary value for its versionSelector and externalize some values:

bslx::ByteOutStream outStream(20131127);
outStream.putInt32(1);
outStream.putInt32(2);
outStream.putInt8('c');
outStream.putString(bsl::string("hello"));

Then, we compare the contents of the stream to the expected value:

const char  *theChars = outStream.data();
bsl::size_t  length   = outStream.length();
assert(15 == length);
assert( 0 == bsl::memcmp(theChars,
                         "\x00\x00\x00\x01\x00\x00\x00\x02""c\x05""hello",
                         length));

Finally, we print the stream's contents to bsl::cout.

for (bsl::size_t i = 0; i < length; ++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;
    }
}

Executing the above code results in the following output:

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

See the bslx_byteinstream component usage example for a more practical example of using bslx streams.