[#BloombergLP-bslx-ByteInStream]
= xref:BloombergLP.adoc[BloombergLP]::xref:BloombergLP/bslx.adoc[bslx]::ByteInStream
:relfileprefix: ../../
:mrdocs:

This class provides input methods to unexternalize values, and C‐style arrays of values, of the fundamental integral and floating‐point types, as well as `bsl::string` values, using a byte format documented in the `bslx_byteoutstream` component. In particular, each `get` method of this class is guaranteed to read stream data written by the corresponding `put` method of `bslx::ByteOutStream`. Note that attempting to read beyond the end of a stream will automatically invalidate the stream. See the `bslx` package‐level documentation for the definition of the BDEX `InStream` protocol.

== Synopsis

Declared in `<bslx_byteinstream.h>`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
class ByteInStream;
----

== Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslx/ByteInStream/2constructor-08.adoc[`ByteInStream`]         [.small]#[constructor]#
| Constructors
| xref:BloombergLP/bslx/ByteInStream/2destructor.adoc[`~ByteInStream`] [.small]#[destructor]#
| Destroy this object.
| xref:BloombergLP/bslx/ByteInStream/cursor.adoc[`cursor`] 
| Return the index of the next byte to be extracted from this stream.
| xref:BloombergLP/bslx/ByteInStream/data.adoc[`data`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayFloat32.adoc[`getArrayFloat32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayFloat64.adoc[`getArrayFloat64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt16.adoc[`getArrayInt16`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt24.adoc[`getArrayInt24`] 
| 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 <= numValues` and `variables` has sufficient capacity. Note that each of the values will be sign‐extended.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt32.adoc[`getArrayInt32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt40.adoc[`getArrayInt40`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt48.adoc[`getArrayInt48`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt56.adoc[`getArrayInt56`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt64.adoc[`getArrayInt64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayInt8-03.adoc[`getArrayInt8`] 
| `getArrayInt8` overloads
| xref:BloombergLP/bslx/ByteInStream/getArrayUint16.adoc[`getArrayUint16`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint24.adoc[`getArrayUint24`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint32.adoc[`getArrayUint32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint40.adoc[`getArrayUint40`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint48.adoc[`getArrayUint48`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint56.adoc[`getArrayUint56`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint64.adoc[`getArrayUint64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getArrayUint8-09.adoc[`getArrayUint8`] 
| `getArrayUint8` overloads
| xref:BloombergLP/bslx/ByteInStream/getFloat32.adoc[`getFloat32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getFloat64.adoc[`getFloat64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt16.adoc[`getInt16`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt24.adoc[`getInt24`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt32.adoc[`getInt32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt40.adoc[`getInt40`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt48.adoc[`getInt48`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt56.adoc[`getInt56`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt64.adoc[`getInt64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getInt8-0a.adoc[`getInt8`] 
| `getInt8` overloads
| xref:BloombergLP/bslx/ByteInStream/getLength.adoc[`getLength`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getString.adoc[`getString`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint16.adoc[`getUint16`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint24.adoc[`getUint24`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint32.adoc[`getUint32`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint40.adoc[`getUint40`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint48.adoc[`getUint48`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint56.adoc[`getUint56`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint64.adoc[`getUint64`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/getUint8-05.adoc[`getUint8`] 
| `getUint8` overloads
| xref:BloombergLP/bslx/ByteInStream/getVersion.adoc[`getVersion`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/invalidate.adoc[`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.
| xref:BloombergLP/bslx/ByteInStream/isEmpty.adoc[`isEmpty`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/isValid.adoc[`isValid`] 
| 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.
| xref:BloombergLP/bslx/ByteInStream/length.adoc[`length`] 
| Return the total number of bytes stored in the external memory buffer.
| xref:BloombergLP/bslx/ByteInStream/reset-04.adoc[`reset`] 
| `reset` overloads
| xref:BloombergLP/bslx/ByteInStream/2conversion.adoc[`operator 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.
|===


== Friends

[cols="1,4"]
|===
| Name| Description
| `xref:BloombergLP/bslx/operator_lshift-0ae.adoc[BloombergLP::bslx::operator<<]`
| Write the specified `object` to the specified output `stream` in some reasonable (multi‐line) format, and return a reference to `stream`.
|===

== Non-Member Functions

[cols="1,4"]
|===
| Name| Description
| xref:BloombergLP/bslx/operator_rshift-038.adoc[`operator>>`]
| 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.
|===


[.small]#Created with https://www.mrdocs.com[MrDocs]#