|
Quick Links: |
Define externalization protocols and provide implementations. More...
Components | |
| Component bslx_byteinstream | |
Provide a stream class for unexternalization of fundamental types. | |
| Component bslx_byteoutstream | |
Provide a stream class for externalization of fundamental types. | |
| Component bslx_genericinstream | |
Unexternalization of fundamental types from a parameterized stream. | |
| Component bslx_genericoutstream | |
Externalization of fundamental types to a parameterized stream. | |
| Component bslx_instreamfunctions | |
Facilitate uniform unexternalization of user and fundamental types. | |
| Component bslx_marshallingutil | |
Support platform-independent marshalling of fundamental types. | |
| Component bslx_outstreamfunctions | |
Facilitate uniform externalization of user and fundamental types. | |
| Component bslx_streambufinstream | |
Unexternalization of fundamental types from a | |
| Component bslx_streambufoutstream | |
Externalization of fundamental types to a | |
| Component bslx_testinstream | |
Enable unexternalization of fundamental types with identification. | |
| Component bslx_testinstreamexception | |
Provide an exception class for unexternalization operations. | |
| Component bslx_testoutstream | |
Enable externalization of fundamental types with identification. | |
| Component bslx_typecode | |
Enumerate the fundamental types supported by BDEX. | |
| Component bslx_versionfunctions | |
Provide functions to return BDEX version information for types. | |
versionSelector bslx package defines (via documentation) the BDEX protocol for externalization (i.e., for an "out stream") and "unexternalization" (i.e., for an "in stream"), and provides concrete byte-array-based stream implementations of each kind of stream, including streams for testing. In general, concrete streams must be used in matched pairs, as described in more detail below; see also Security Warning below. bslx package currently has 14 components having 5 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. 5. bslx_streambufinstream
bslx_testinstream
4. bslx_byteinstream
bslx_genericinstream
bslx_streambufoutstream
bslx_testoutstream
3. bslx_byteoutstream
bslx_genericoutstream
2. bslx_instreamfunctions
bslx_outstreamfunctions
bslx_testinstreamexception
1. bslx_marshallingutil
bslx_typecode
bslx_versionfunctions
bslx_byteinstream: bslx_byteoutstream: bslx_genericinstream: bslx_genericoutstream: bslx_instreamfunctions: bslx_marshallingutil: bslx_outstreamfunctions: bslx_streambufinstream: bsl::streambuf.bslx_streambufoutstream: bsl::streambuf.bslx_testinstream: bslx_testinstreamexception: bslx_testoutstream: bslx_typecode: bslx_versionfunctions: bslx is a low-level facility for externalizing and unexternalizing data represented in C++ objects. bslx natively provides support for externalizing fundamental types, arrays, and critical Standard Library types (bsl::string and bsl::vector); higher-level user-defined types (i.e., classes and structs) implement the BDEX concepts on their own, and are responsible for performing validation when data is streamed in from a BDEX byte stream. Any input validation for higher-level types is to be implemented in those types themselves -- i.e., there is no central facility for validating input -- so the strength of the validation performed on an input stream is determined by the strength of the validation for all of the individual types that will process input from the stream. bslx streams provide better support for externalization than iostream objects because BDEX specifies a canonical, optimized representation for fundamental types, provides component authors the tools to externalize in a platform-neutral way any in-core object, and allows versioning of types not directly supported by BDEX. bdexStreamOut is required to use only the methods provided by the BDEX-compliant stream and the methods defined in bslx::OutStreamFunctions that require a version to be specified. For externalization of types not needing a version, the value bslx::VersionFunctions::k_NO_VERSION should be supplied for this parameter. operator<< it is impractical to directly supply the version to be used with each top-level object. As such, an indirect method of versioning is employed, which incorporates data provided to the stream during the stream's construction, the versionSelector. One requirement of all BDEX-compliant serializable types is to implement the maxSupportedBdexVersion method, which converts this versionSelector to the needed version on a per object-type basis. While the list of versions supported by an object is typically a sequential set of numbers starting with 1, the versionSelector is expected to be formatted as "YYYYMMDD", a date representation. For example, an integral versionSelector value of 20140402 represents the date 2014/04/02 (April 2, 2014). vector externalizations include a version, which, for directly supported types, is explicitly the value 1. For nested vectors, the most-nested type is used to determine the version. If this type is directly supported by the stream, the value 1 is used; otherwise, the maxSupportedBdexVersion method provided for that type is used to obtain the version information. bsl::string is streamed as an int representing the string's length and a homogeneous char array for the string's data. Note that Int64 and Uint64 denote bsls::Types::Int64 and bsls::Types::Uint64, respectively, which in turn are typedef names for the signed and unsigned 64-bit integer types, respectively, on the host platform: C++ TYPE REQUIRED CONTENT OF ANY PLATFORM-NEUTRAL FORMAT -------------- ----------------------------------------------- Int64 64 bits (signed) Uint64 64 bits (unsigned) int 32 bits (signed) unsigned int 32 bits (unsigned) short 16 bits (signed) unsigned short 16 bits (unsigned) char 8 bits (platform-dependent) signed char 8 bits (signed) unsigned char 8 bits (unsigned) double IEEE standard 8-byte floating-point value float IEEE standard 4-byte floating-point value bsl::string BDE implementation of the STL string class
InStream and OutStream, that serve as the "documentation protocols" for input and output streams, respectively. // 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. // MANIPULATORS template <class STREAM> STREAM& bdexStreamIn(STREAM& stream, int version); // Assign to this object the value read from the specified input 'stream' // using the specified 'version' format, and return a reference to // 'stream'. If 'stream' is initially invalid, this operation has no // effect. If 'version' is not supported, this object is unaltered and // 'stream' is invalidated, but otherwise unmodified. If 'version' is // supported but 'stream' becomes invalid during this operation, this // object has an undefined, but valid, state. Note that no version is // read from 'stream'. See the 'bslx' package-level documentation for // more information on BDEX streaming of value-semantic types and // containers. // ACCESSORS 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.
bslx: Out Stream In Stream Informal Designation ------------------- ------------------ -------------------- bslx::ByteOutStream bslx::ByteInStream "Production Streams" bslx::TestOutStream bslx::TestInStream "Test Streams"
bslx::TestOutStream and then unexternalized from a seemingly-appropriately-constructed bslx::ByteInStream. Each pair of streams is designed with different aims in mind, and so their exact formats may vary. MyPoint class whose intended purpose is to hold a pair of int values representing a point in a two-dimensional rectilinear coordinate space. We will first define the class without BDEX support and then add that support. Note that, in this example, most of the required documentation and some required methods and free operators are omitted for ease of viewing. MyPoint might be: class MyPoint { int d_x; int d_y; public: // CREATORS MyPoint() : d_x(0), d_y(0) { } MyPoint(int x, int y) : d_x(x), d_y(y) { } MyPoint(const MyPoint& original) : d_x(original.d_x), d_y(original.d_y) { } ~MyPoint() { } // MANIPULATORS MyPoint& operator=(const MyPoint& rhs) { d_x = rhs.d_x; d_y = rhs.d_y; return *this; } void setX(int x) { d_x = x; } void setY(int y) { d_y = y; } // ACCESSORS int x() const { return d_x; } int y() const { return d_y; } };
int values. If BDEX succeeds in externalizing these two int values (preserving their order), then the task is accomplished. MyPoint soon, but first let's just say a few words about "version". In a nutshell, the version is set to 1 in the initial release of the class, and in the best of all worlds, the version stays 1 forever. If, however, for some reason the developer wishes to alter the BDEX streaming contract (e.g., for some performance reasons), the explicit version maintains backward compatibility. MyPoint that are required for BDEX-compliance is straightforward: class MyPoint { int d_x; int d_y; 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() : d_x(0), d_y(0) { } MyPoint(int x, int y) : d_x(x), d_y(y) { } MyPoint(const MyPoint& original) : d_x(original.d_x), d_y(original.d_y) { } ~MyPoint() { } // MANIPULATORS MyPoint& operator=(const MyPoint& rhs) { d_x = rhs.d_x; d_y = rhs.d_y; return *this; } void setX(int x) { d_x = x; } void setY(int y) { d_y = y; } template <class STREAM> STREAM& bdexStreamIn(STREAM& stream, int version); // Assign to this object the value read from the specified input // 'stream' using the specified 'version' format, and return a // reference to 'stream'. If 'stream' is initially invalid, this // operation has no effect. If 'version' is not supported, this // object is unaltered and 'stream' is invalidated, but otherwise // unmodified. If 'version' is supported but 'stream' becomes // invalid during this operation, this object has an undefined, but // valid, state. Note that no version is read from 'stream'. See // the 'bslx' package-level documentation for more information on // BDEX streaming of value-semantic types and containers. // ACCESSORS int x() const { return d_x; } int y() const { return d_y; } 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. };
maxSupportedBdexVersion method simply returns the value 1 regardless of the versionSelector requested: inline int MyPoint::maxSupportedBdexVersion(int versionSelector) { return 1; }
bdexStreamOut method is an accessor (i.e., a const instance method), and is therefore a bit simpler, so we'll show that one first. Anyway, it's a bit more logical to see the output format before implementing the input format. The method is a template method parameterized by STREAM, and the "protocol" of that STREAM must be compatible with the BDEX contract. We can therefore safely assume that the stream object has the required methods. See the "The BDEX Protocols" section above for the contracts. The heart of the method is the two sequential calls to putInt32, which externalize the x and y coordinates of the point value, in that order. These two lines are all the "new" code that the developer must understand and implement. Except for changing the class name from our MyPoint example, the rest of the code can be copied into the new component implementation directly. Note that this template method is implemented in the header of the component defining MyClass: template <class STREAM> STREAM& MyPoint::bdexStreamOut(STREAM& stream, int version) const { switch (version) { case 1: { // Implementation-specific code goes here. stream.putInt32(d_x); stream.putInt32(d_y); } break; default: { stream.invalidate(); } break; } return stream; }
bdexStreamOut, implementing bdexStreamIn is extremely straightforward, involving a template member function whose body can be safely copied from this example or from any appropriate component. Note that the two sequential calls to getInt32 must match, in both method selection and data member order, the putInt32 methods used in the bdexStreamOut method: template <class STREAM> STREAM& MyPoint::bdexStreamIn(STREAM& stream, int version) { if (stream) { switch (version) { // switch on the schema version (starting with 1) case 1: { // Implementation-specific code goes here. stream.getInt32(d_x); stream.getInt32(d_y); } break; default: { stream.invalidate(); } break; } } return stream; }
int data members represents a valid value. However, in general, since we require the state of an object to be valid in the face of a stream error (e.g., an exception being thrown during streaming in), the manipulator method bdexStreamIn must validate the input data, set the object to some valid state in the case of an error, and invalidate the stream before returning. 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. 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. 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. OutStream, a simple approach is to use the current date as a compile-time constant value (but see Updating Production Systems). 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. versionSelector: MyObject foo( /* some value */ ); bslx::ByteOutStream stream(20140725); // The minimum date that will // result in all streamed types // using the correct versions // during externalization. stream << foo;
versionSelector is a compile-time-selected value (in this case, the minimum date that will result in all streamed types using the correct versions during externalization) that can be mapped to the serialization format version of the types being serialized. The receiver of this information must support all these versions as well. Specifying future dates or allowing a run-time selection of versionSelector is error prone: tasks exchanging serialized data are often compiled and deployed at different times, which would result in serialization errors if they were selecting a serialization version at run-time (there is no guarantee the receiver has been rebuilt to accept the updated format version). MyPoint class is determined to need 64-bit storage for the coordinate values. The new bdexStreamIn and bdexStreamOut code might be implemented as: template <class STREAM> STREAM& MyPoint::bdexStreamIn(STREAM& stream, int version) { if (stream) { switch (version) { // switch on the schema version (starting with 1) case 2: { // Implementation-specific code goes here. stream.getInt64(d_x); stream.getInt64(d_y); } break; case 1: { // NOTE: 'd_x' and 'd_y' were switched to 64-bit int tmp; stream.getInt32(tmp); d_x = static_cast<bsls::Types::Int64>(tmp); stream.getInt32(tmp); d_y = static_cast<bsls::Types::Int64>(tmp); } break; default: { stream.invalidate(); } break; } } return stream; } template <class STREAM> STREAM& MyPoint::bdexStreamOut(STREAM& stream, int version) const { switch (version) { case 2: { stream.putInt64(d_x); stream.putInt64(d_y); } break; case 1: { // NOTE: 'd_x' and 'd_y' were switched to 64-bit stream.putInt32(static_cast<int>(d_x)); stream.putInt32(static_cast<int>(d_y)); } break; default: { stream.invalidate(); } break; } return stream; }
maxSupportedBdexVersion, where 2014/04/02 is the date on which the new version is introduced, might look something like: inline int MyPoint::maxSupportedBdexVersion(int versionSelector) { if (versionSelector >= 20140402) { return 2; // RETURN } return 1; }
versionSelector (which is supplied to the BDEX OutStream constructor) is to use the current date as a compile-time constant value. Using the current date will select the most recent BDEX version. However, in environments were multiple tasks may be reading the resulting serialized value, it is important to ensure that all the tasks participating in the system are capable of reading that BDEX version before selecting it as an output version. A) in a production system typically involves these steps: A, introducing a new BDEX version, and version selector for that version that is the date the change is expected to "go-live". A. A (choosing the date used in step 1). A. template <class STREAM, class TYPE> STREAM& bdexStreamIn(STREAM& stream, TYPE& variable, int version); // Assign to the specified 'variable' the 'TYPE' value read from the // specified input 'stream' using the specified 'version' format, and // return a reference to 'stream'. If 'stream' is initially invalid, // this operation has no effect. If 'version' is not supported by // 'TYPE', 'variable' is unaltered and 'stream' is invalidated, but // otherwise unmodified. If 'version' is supported by 'TYPE' but // 'stream' becomes invalid during this operation, 'variable' has an // undefined, but valid, state. The behavior is undefined unless // 'STREAM' and 'TYPE' are BDEX-compliant. Note that no version is read // from '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); // 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. The behavior is undefined unless 'STREAM' and // 'TYPE' are BDEX-compliant. 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 TYPE> int maxSupportedBdexVersion(const TYPE *, int versionSelector); // Return the maximum valid BDEX format version, as indicated by the // specified 'versionSelector', to be passed to the 'bdexStreamOut' // method while streaming an object of the (template parameter) type // 'TYPE'. 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.
namespace ThirdParty { struct MyStruct { public: enum Value { e_A = 7, e_B = 8, e_C = 9 }; }; template <class STREAM> STREAM& bdexStreamIn(STREAM& stream, MyStruct::Value& value, int version) { using bslx::InStreamFunctions::bdexStreamIn; if (stream) { switch (version) { case 1: { char newValue; stream.getInt8(newValue); if (stream) { value = static_cast<MyStruct::Value>(newValue); } } break; default: { stream.invalidate(); } break; } } return stream; } template <class STREAM> STREAM& bdexStreamOut(STREAM& stream, const MyStruct::Value& value, int version) { using bslx::OutStreamFunctions::bdexStreamOut; if (stream) { switch (version) { case 1: { stream.putInt8(static_cast<char>(value)); } break; default: { stream.invalidate(); } break; } } return stream; } inline int maxSupportedBdexVersion(const MyStruct::Value *, int versionSelector) { using bslx::VersionFunctions::maxSupportedBdexVersion; return 1; } } // close ThirdParty namespace
OutStream, which serves as the "documentation protocol" for all BDEX-compliant output streams: // MANIPULATORS void invalidate(); // Put this output stream in an invalid state. This function has no // effect if this stream is already invalid. OutStream& putLength(int length); // If the specified 'length' is less than 128, write to this stream // the one-byte integer comprised of the least-significant one byte // of the 'length'; otherwise, write to this stream the four-byte, // two's complement integer (in network byte order) comprised of the // least-significant four bytes of the 'length' (in host byte order) // with the most-significant bit set. Return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. The behavior is undefined unless '0 <= length'. OutStream& putVersion(int version); // Write to this stream the one-byte, two's complement unsigned // integer comprised of the least-significant one byte of the // specified 'version', and return a reference to this stream. If // this stream is initially invalid, this operation has no effect. void reserveCapacity(int newCapacity); // Set the internal buffer size of this stream to be at least the // specified 'newCapacity' (in bytes). The behavior is undefined // unless '0 <= newCapacity'. void reset(); // Remove all content in this stream and validate this stream if it // is currently invalid. // *** scalar integer values *** OutStream& putInt64(bsls::Types::Int64 value); // Write to this stream the eight-byte, two's complement integer (in // network byte order) comprised of the least-significant eight bytes // of the specified 'value' (in host byte order), and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. OutStream& putUint64(bsls::Types::Uint64 value); // Write to this stream the eight-byte, two's complement unsigned // integer (in network byte order) comprised of the least-significant // eight bytes of the specified 'value' (in host byte order), and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. OutStream& putInt56(bsls::Types::Int64 value); // Write to this stream the seven-byte, two's complement integer (in // network byte order) comprised of the least-significant seven bytes // of the specified 'value' (in host byte order), and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. OutStream& putUint56(bsls::Types::Uint64 value); // Write to this stream the seven-byte, two's complement unsigned // integer (in network byte order) comprised of the least-significant // seven bytes of the specified 'value' (in host byte order), and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. OutStream& putInt48(bsls::Types::Int64 value); // Write to this stream the six-byte, two's complement integer (in // network byte order) comprised of the least-significant six bytes // of the specified 'value' (in host byte order), and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. OutStream& putUint48(bsls::Types::Uint64 value); // Write to this stream the six-byte, two's complement unsigned // integer (in network byte order) comprised of the least-significant // six bytes of the specified 'value' (in host byte order), and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. OutStream& putInt40(bsls::Types::Int64 value); // Write to this stream the five-byte, two's complement integer (in // network byte order) comprised of the least-significant five bytes // of the specified 'value' (in host byte order), and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. OutStream& putUint40(bsls::Types::Uint64 value); // Write to this stream the five-byte, two's complement unsigned // integer (in network byte order) comprised of the least-significant // five bytes of the specified 'value' (in host byte order), and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. OutStream& 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. If this stream is initially invalid, // this operation has no effect. OutStream& putUint32(unsigned int value); // Write to this stream the four-byte, two's complement unsigned // 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. If this stream is initially // invalid, this operation has no effect. OutStream& putInt24(int value); // Write to this stream the three-byte, two's complement integer (in // network byte order) comprised of the least-significant three bytes // of the specified 'value' (in host byte order), and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. OutStream& putUint24(unsigned int value); // Write to this stream the three-byte, two's complement unsigned // integer (in network byte order) comprised of the least-significant // three bytes of the specified 'value' (in host byte order), and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. OutStream& 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. If this stream is initially invalid, // this operation has no effect. OutStream& putUint16(unsigned int value); // Write to this stream the two-byte, two's complement unsigned // 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. If this stream is initially // invalid, this operation has no effect. OutStream& 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. If this stream is // initially invalid, this operation has no effect. OutStream& putUint8(unsigned int value); // Write to this stream the one-byte, two's complement unsigned // integer comprised of the least-significant one byte of the // specified 'value', and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. // *** scalar floating-point values *** OutStream& putFloat64(double value); // Write to this stream the eight-byte IEEE double-precision // floating-point number (in network byte order) comprised of the // most-significant eight bytes of the specified 'value' (in host // byte order), and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. Note // that for non-conforming platforms, this operation may be lossy. OutStream& putFloat32(float value); // Write to this stream the four-byte IEEE single-precision // floating-point number (in network byte order) comprised of the // most-significant four bytes of the specified 'value' (in host byte // order), and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. Note that for // non-conforming platforms, this operation may be lossy. // *** string values *** OutStream& putString(const bsl::string& value); // Write to this stream the length of the specified 'value' (see // 'putLength') and an array of one-byte, two's complement unsigned // integers comprised of the least-significant one byte of each // character in the 'value', and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // *** arrays of integer values *** OutStream& putArrayInt64(const bsls::Types::Int64 *values, int numValues); // Write to this stream the consecutive eight-byte, two's complement // integers (in network byte order) comprised of the // least-significant eight bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint64(const bsls::Types::Uint64 *values, int numValues); // Write to this stream the consecutive eight-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant eight bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt56(const bsls::Types::Int64 *values, int numValues); // Write to this stream the consecutive seven-byte, two's complement // integers (in network byte order) comprised of the // least-significant seven bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint56(const bsls::Types::Uint64 *values, int numValues); // Write to this stream the consecutive seven-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant seven bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt48(const bsls::Types::Int64 *values, int numValues); // Write to this stream the consecutive six-byte, two's complement // integers (in network byte order) comprised of the // least-significant six bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint48(const bsls::Types::Uint64 *values, int numValues); // Write to this stream the consecutive six-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant six bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt40(const bsls::Types::Int64 *values, int numValues); // Write to this stream the consecutive five-byte, two's complement // integers (in network byte order) comprised of the // least-significant five bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint40(const bsls::Types::Uint64 *values, int numValues); // Write to this stream the consecutive five-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant five bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt32(const int *values, int numValues); // Write to this stream the consecutive four-byte, two's complement // integers (in network byte order) comprised of the // least-significant four bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint32(const unsigned int *values, int numValues); // Write to this stream the consecutive four-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant four bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt24(const int *values, int numValues); // Write to this stream the consecutive three-byte, two's complement // integers (in network byte order) comprised of the // least-significant three bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint24(const unsigned int *values, int numValues); // Write to this stream the consecutive three-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant three bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt16(const short *values, int numValues); // Write to this stream the consecutive two-byte, two's complement // integers (in network byte order) comprised of the // least-significant two bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint16(const unsigned short *values, int numValues); // Write to this stream the consecutive two-byte, two's complement // unsigned integers (in network byte order) comprised of the // least-significant two bytes of each of the specified 'numValues' // leading entries in the specified 'values' (in host byte order), // and return a reference to this stream. If this stream is // initially invalid, this operation has no effect. The behavior is // undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayInt8(const char *values, int numValues); OutStream& putArrayInt8(const signed char *values, int numValues); // Write to this stream the consecutive one-byte, two's complement // integers comprised of the least-significant one byte of each of // the specified 'numValues' leading entries in the specified // 'values', and return a reference to this stream. If this stream // is initially invalid, this operation has no effect. The behavior // is undefined unless '0 <= numValues' and 'values' has sufficient // contents. OutStream& putArrayUint8(const char *values, int numValues); OutStream& putArrayUint8(const unsigned char *values, int numValues); // Write to this stream the consecutive one-byte, two's complement // unsigned integers comprised of the least-significant one byte of // each of the specified 'numValues' leading entries in the specified // 'values', and return a reference to this stream. If this stream // is initially invalid, this operation has no effect. The behavior // is undefined unless '0 <= numValues' and 'values' has sufficient // contents. // *** arrays of floating-point values *** OutStream& putArrayFloat64(const double *values, int numValues); // Write to this stream the consecutive eight-byte IEEE // double-precision floating-point numbers (in network byte order) // comprised of the most-significant eight bytes of each of the // specified 'numValues' leading entries in the specified 'values' // (in host byte order), and return a reference to this stream. If // this stream is initially invalid, this operation has no effect. // The behavior is undefined unless '0 <= numValues' and 'values' has // sufficient contents. Note that for non-conforming platforms, this // operation may be lossy. OutStream& putArrayFloat32(const float *values, int numValues); // Write to this stream the consecutive four-byte IEEE // single-precision floating-point numbers (in network byte order) // comprised of the most-significant four bytes of each of the // specified 'numValues' leading entries in the specified 'values' // (in host byte order), and return a reference to this stream. If // this stream is initially invalid, this operation has no effect. // The behavior is undefined unless '0 <= numValues' and 'values' has // sufficient contents. Note that for non-conforming platforms, this // operation may be lossy. // ACCESSORS operator const void *() const; // Return a non-zero value if this stream is valid, and 0 otherwise. // An invalid stream is a stream for which an output operation was // detected to have failed or 'invalidate' was called. int bdexVersionSelector() const; // Return the 'versionSelector' to be used with 'operator<<' for BDEX // streaming as per the 'bslx' package-level documentation. 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. bool isValid() const; // Return 'true' if this stream is valid, and 'false' otherwise. An // invalid stream is a stream for which an output operation was // detected to have failed or 'invalidate' was called. bsl::size_t length() const; // Return the number of bytes in this stream. // FREE OPERATORS template <class TYPE> OutStream& operator<<(OutStream& stream, const TYPE& value); // Write the specified 'value' to the specified output 'stream' following // the requirements of the BDEX protocol (see the 'bslx' package-level // documentation), and return a reference to 'stream'. The behavior is // undefined unless 'TYPE' is BDEX-compliant.
InStream, which serves as the "documentation protocol" for all BDEX-compliant input streams: // MANIPULATORS InStream& getLength(int& length); // If the most-significant bit of the one byte of this stream at the // current cursor location is set, assign to the specified 'length' // the four-byte, two's complement integer (in host byte order) // comprised of the four bytes of this stream at the current cursor // location (in network byte order) with the most-significant bit // unset; otherwise, assign to 'length' the one-byte, two's // complement integer comprised of the one byte of this stream at the // current cursor location. Update the cursor location and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'length' is undefined. Note that the value will be // zero-extended. InStream& getVersion(int& version); // Assign to the specified 'version' the one-byte, two's complement // unsigned integer comprised of the one byte of this stream at the // current cursor location, update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'version' is undefined. Note that the value will be // zero-extended. 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. void reset(); // Set the index of the next byte to be extracted from this stream to // 0 (i.e., the beginning of the stream) and validate this stream if // it is currently invalid. void reset(const char *buffer, bsl::size_t numBytes); // Reset this stream to extract from the specified 'buffer' // containing the specified 'numBytes', set the index of the next // byte to be extracted to 0 (i.e., the beginning of the stream), and // validate this stream if it is currently invalid. The behavior is // undefined unless '0 == numBytes' if '0 == buffer'. void reset(const bslstl::StringRef& srcData); // Reset this stream to extract from the specified 'srcData', set the // index of the next byte to be extracted to 0 (i.e., the beginning // of the stream), and validate this stream if it is currently // invalid. // *** scalar integer values *** InStream& getInt64(bsls::Types::Int64& variable); // Assign to the specified 'variable' the eight-byte, two's // complement integer (in host byte order) comprised of the eight // bytes of this stream at the current cursor location (in network // byte order), update the cursor location, and return a reference to // this stream. If this stream is initially invalid, this operation // has no effect. If this function otherwise fails to extract a // valid value, this stream is marked invalid and the value of // 'variable' is undefined. Note that the value will be // sign-extended. InStream& getUint64(bsls::Types::Uint64& variable); // Assign to the specified 'variable' the eight-byte, two's // complement unsigned integer (in host byte order) comprised of the // eight bytes of this stream at the current cursor location (in // network byte order), update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variable' is undefined. Note that the value will be // zero-extended. InStream& getInt56(bsls::Types::Int64& variable); // Assign to the specified 'variable' the seven-byte, two's // complement integer (in host byte order) comprised of the seven // bytes of this stream at the current cursor location (in network // byte order), update the cursor location, and return a reference to // this stream. If this stream is initially invalid, this operation // has no effect. If this function otherwise fails to extract a // valid value, this stream is marked invalid and the value of // 'variable' is undefined. Note that the value will be // sign-extended. InStream& getUint56(bsls::Types::Uint64& variable); // Assign to the specified 'variable' the seven-byte, two's // complement unsigned integer (in host byte order) comprised of the // seven bytes of this stream at the current cursor location (in // network byte order), update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variable' is undefined. Note that the value will be // zero-extended. InStream& getInt48(bsls::Types::Int64& variable); // Assign to the specified 'variable' the six-byte, two's complement // integer (in host byte order) comprised of the six bytes of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variable' is undefined. // Note that the value will be sign-extended. InStream& getUint48(bsls::Types::Uint64& variable); // Assign to the specified 'variable' the six-byte, two's complement // unsigned integer (in host byte order) comprised of the six bytes // of this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variable' // is undefined. Note that the value will be zero-extended. InStream& getInt40(bsls::Types::Int64& variable); // Assign to the specified 'variable' the five-byte, two's complement // integer (in host byte order) comprised of the five bytes of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variable' is undefined. // Note that the value will be sign-extended. InStream& getUint40(bsls::Types::Uint64& variable); // Assign to the specified 'variable' the five-byte, two's complement // unsigned integer (in host byte order) comprised of the five bytes // of this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variable' // is undefined. Note that the value will be zero-extended. InStream& getInt32(int& variable); // Assign to the specified 'variable' the four-byte, two's complement // integer (in host byte order) comprised of the four bytes of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variable' is undefined. // Note that the value will be sign-extended. InStream& getUint32(unsigned int& variable); // Assign to the specified 'variable' the four-byte, two's complement // unsigned integer (in host byte order) comprised of the four bytes // of this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variable' // is undefined. Note that the value will be zero-extended. InStream& getInt24(int& variable); // Assign to the specified 'variable' the three-byte, two's // complement integer (in host byte order) comprised of the three // bytes of this stream at the current cursor location (in network // byte order), update the cursor location, and return a reference to // this stream. If this stream is initially invalid, this operation // has no effect. If this function otherwise fails to extract a // valid value, this stream is marked invalid and the value of // 'variable' is undefined. Note that the value will be // sign-extended. InStream& getUint24(unsigned int& variable); // Assign to the specified 'variable' the three-byte, two's // complement unsigned integer (in host byte order) comprised of the // three bytes of this stream at the current cursor location (in // network byte order), update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variable' is undefined. Note that the value will be // zero-extended. InStream& getInt16(short& variable); // Assign to the specified 'variable' the two-byte, two's complement // integer (in host byte order) comprised of the two bytes of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variable' is undefined. // Note that the value will be sign-extended. InStream& getUint16(unsigned short& variable); // Assign to the specified 'variable' the two-byte, two's complement // unsigned integer (in host byte order) comprised of the two bytes // of this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variable' // is undefined. Note that the value will be zero-extended. InStream& getInt8(char& variable); InStream& getInt8(signed char& variable); // Assign to the specified 'variable' the one-byte, two's complement // integer comprised of the one byte of this stream at the current // cursor location, update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variable' is undefined. Note that the value will be // sign-extended. InStream& getUint8(char& variable); InStream& getUint8(unsigned char& variable); // Assign to the specified 'variable' the one-byte, two's complement // unsigned integer comprised of the one byte of this stream at the // current cursor location, update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variable' is undefined. Note that the value will be // zero-extended. // *** scalar floating-point values *** InStream& getFloat64(double& variable); // Assign to the specified 'variable' the eight-byte IEEE // double-precision floating-point number (in host byte order) // comprised of the eight bytes of this stream at the current cursor // location (in network byte order), update the cursor location, and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. If this function otherwise // fails to extract a valid value, this stream is marked invalid and // the value of 'variable' is undefined. InStream& getFloat32(float& variable); // Assign to the specified 'variable' the four-byte IEEE // single-precision floating-point number (in host byte order) // comprised of the four bytes of this stream at the current cursor // location (in network byte order), update the cursor location, and // return a reference to this stream. If this stream is initially // invalid, this operation has no effect. If this function otherwise // fails to extract a valid value, this stream is marked invalid and // the value of 'variable' is undefined. // *** string values *** InStream& getString(bsl::string& variable); // Assign to the specified 'variable' the string comprised of the // length of the string (see 'getLength') and the string data (see // 'getUint8'), update the cursor location, and return a reference to // this stream. If this stream is initially invalid, this operation // has no effect. If this function otherwise fails to extract a // valid value, this stream is marked invalid and the value of // 'variable' is undefined. // *** arrays of integer values *** InStream& getArrayInt64(bsls::Types::Int64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive eight-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' eight-byte sequences of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint64(bsls::Types::Uint64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive eight-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' eight-byte sequences of // this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variables' // is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. InStream& getArrayInt56(bsls::Types::Int64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive seven-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' seven-byte sequences of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint56(bsls::Types::Uint64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive seven-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' seven-byte sequences of // this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variables' // is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. InStream& getArrayInt48(bsls::Types::Int64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive six-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' six-byte sequences of this stream // at the current cursor location (in network byte order), update the // cursor location, and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. If // this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint48(bsls::Types::Uint64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive six-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' six-byte sequences of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be zero-extended. InStream& getArrayInt40(bsls::Types::Int64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive five-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' five-byte sequences of this stream // at the current cursor location (in network byte order), update the // cursor location, and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. If // this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint40(bsls::Types::Uint64 *variables, int numVariables); // Assign to the specified 'variables' the consecutive five-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' five-byte sequences of // this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variables' // is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. InStream& getArrayInt32(int *variables, int numVariables); // Assign to the specified 'variables' the consecutive four-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' four-byte sequences of this stream // at the current cursor location (in network byte order), update the // cursor location, and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. If // this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint32(unsigned int *variables, int numVariables); // Assign to the specified 'variables' the consecutive four-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' four-byte sequences of // this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variables' // is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. InStream& getArrayInt24(int *variables, int numVariables); // Assign to the specified 'variables' the consecutive three-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' three-byte sequences of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint24(unsigned int *variables, int numVariables); // Assign to the specified 'variables' the consecutive three-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' three-byte sequences of // this stream at the current cursor location (in network byte // order), update the cursor location, and return a reference to this // stream. If this stream is initially invalid, this operation has // no effect. If this function otherwise fails to extract a valid // value, this stream is marked invalid and the value of 'variables' // is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. InStream& getArrayInt16(short *variables, int numVariables); // Assign to the specified 'variables' the consecutive two-byte, // two's complement integers (in host byte order) comprised of each // of the specified 'numVariables' two-byte sequences of this stream // at the current cursor location (in network byte order), update the // cursor location, and return a reference to this stream. If this // stream is initially invalid, this operation has no effect. If // this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be sign-extended. InStream& getArrayUint16(unsigned short *variables, int numVariables); // Assign to the specified 'variables' the consecutive two-byte, // two's complement unsigned integers (in host byte order) comprised // of each of the specified 'numVariables' two-byte sequences of this // stream at the current cursor location (in network byte order), // update the cursor location, and return a reference to this stream. // If this stream is initially invalid, this operation has no effect. // If this function otherwise fails to extract a valid value, this // stream is marked invalid and the value of 'variables' is // undefined. The behavior is undefined unless '0 <= numVariables' // and 'variables' has sufficient capacity. Note that each of the // values will be zero-extended. InStream& getArrayInt8(char *variables, int numVariables); InStream& getArrayInt8(signed char *variables, int numVariables); // Assign to the specified 'variables' the consecutive one-byte, // two's complement integers comprised of each of the specified // 'numVariables' one-byte sequences of this stream at the current // cursor location, update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variables' is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be sign-extended. InStream& getArrayUint8(char *variables, int numVariables); InStream& getArrayUint8(unsigned char *variables, int numVariables); // Assign to the specified 'variables' the consecutive one-byte, // two's complement unsigned integers comprised of each of the // specified 'numVariables' one-byte sequences of this stream at the // current cursor location, update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variables' is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. Note // that each of the values will be zero-extended. // *** arrays of floating-point values *** InStream& getArrayFloat64(double *variables, int numVariables); // Assign to the specified 'variables' the consecutive eight-byte // IEEE double-precision floating-point numbers (in host byte order) // comprised of each of the specified 'numVariables' eight-byte // sequences of this stream at the current cursor location (in // network byte order), update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variables' is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. InStream& getArrayFloat32(float *variables, int numVariables); // Assign to the specified 'variables' the consecutive four-byte IEEE // single-precision floating-point numbers (in host byte order) // comprised of each of the specified 'numVariables' four-byte // sequences of this stream at the current cursor location (in // network byte order), update the cursor location, and return a // reference to this stream. If this stream is initially invalid, // this operation has no effect. If this function otherwise fails to // extract a valid value, this stream is marked invalid and the value // of 'variables' is undefined. The behavior is undefined unless // '0 <= numVariables' and 'variables' has sufficient capacity. // ACCESSORS operator const void *() const; // Return a non-zero value if this stream is valid, and 0 otherwise. // An invalid stream is a stream for which an input operation was // detected to have failed. bsl::size_t cursor() const; // Return the index of the next byte to be extracted from this // stream. const char *data() const; // Return the address of the contiguous, non-modifiable external // memory buffer of this stream. The behavior of accessing elements // outside the range '[ data() .. data() + (length() - 1) ]' is // undefined. bool isValid() const; // Return 'true' if this stream is valid, and 'false' otherwise. An // invalid stream is a stream in which insufficient or invalid data // was detected during an extraction operation. Note that an empty // stream will be valid unless an extraction attempt or explicit // invalidation causes it to be otherwise. bool isEmpty() const; // Return 'true' if this stream is empty, and 'false' otherwise. // Note that this function enables higher-level types to verify that, // after successfully reading all expected data, no data remains. bsl::size_t length() const; // Return the total number of bytes stored in the external memory // buffer. // FREE OPERATORS template <class TYPE> InStream& operator>>(InStream& stream, TYPE& value); // Read the specified 'value' from the specified input 'stream' // following the requirements of the BDEX protocol (see the 'bslx' // package-level documentation), and return a reference to 'stream'. // The behavior is undefined unless 'TYPE' is BDEX-compliant.
1.7.1