 |
Vault
4.1
|
|
Vault
4.1
|
VBinaryIOStream is a concrete VIOStream subclass that provides well-typed stream i/o using network byte order for its data. More...
#include <vbinaryiostream.h>
Public Member Functions | |
| VBinaryIOStream (VStream &rawStream) | |
| Constructs the object with an underlying raw stream. | |
| virtual | ~VBinaryIOStream () |
| Destructor. | |
| Vs8 | readS8 () |
| Reads a signed 8-bit value from the stream. | |
| Vu8 | readU8 () |
| Reads an unsigned 8-bit value from the stream. | |
| Vs16 | readS16 () |
| Reads a signed 16-bit value from the stream. | |
| Vu16 | readU16 () |
| Reads an unsigned 16-bit value from the stream. | |
| Vs32 | readS32 () |
| Reads a signed 32-bit value from the stream. | |
| int | readInt32 () |
| Reads a signed 32-bit value from the stream, and casts the return value to int. | |
| Vu32 | readU32 () |
| Reads an unsigned 32-bit value from the stream. | |
| Vs64 | readS64 () |
| Reads a signed 64-bit value from the stream. | |
| Vu64 | readU64 () |
| Reads an unsigned 64-bit value from the stream. | |
| VFloat | readFloat () |
| Reads a single-precision floating-point value from the stream. | |
| VDouble | readDouble () |
| Reads a double-precision floating-point value from the stream. | |
| bool | readBool () |
| Reads a bool value from the stream. | |
| void | readString (VString &s) |
| Reads a VString value from the stream, assuming it is prefaced by dynamically-sized length indicator as done in writeString. | |
| VString | readString () |
| Reads a VString value from the stream, assuming it is prefaced by dynamically-sized length indicator as done in writeString, using a more natural syntax than readString(s), but incurring the overhead of creating two temporary copies instead of zero. | |
| void | readString32 (VString &s) |
| Reads a VString value from the stream, assuming it is prefaced by a 32-bit length indicator as done in writeString32. | |
| VString | readString32 () |
| Reads a VString value from the stream, assuming it is prefaced by a 32-bit length indicator as done in writeString32, using a more natural syntax than readString(s), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero. | |
| void | readInstant (VInstant &i) |
| Reads a VInstant value from the stream. | |
| VInstant | readInstant () |
| Reads a VInstant value from the stream, using a more natural syntax than readInstant(i), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero. | |
| void | readDuration (VDuration &d) |
| Reads a VDuration value from the stream. | |
| VDuration | readDuration () |
| Reads a VDuration value from the stream, using a more natural syntax than readDuration(d), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero. | |
| Vs64 | readDynamicCount () |
| Reads a length/count/size indicator that has been dynamically sized via writeDynamicCount. | |
| void | writeS8 (Vs8 i) |
| Writes a signed 8-bit value to the stream. | |
| void | writeU8 (Vu8 i) |
| Writes an unsigned 8-bit value to the stream. | |
| void | writeS16 (Vs16 i) |
| Writes a signed 16-bit value to the stream. | |
| void | writeU16 (Vu16 i) |
| Writes an unsigned 16-bit value to the stream. | |
| void | writeS32 (Vs32 i) |
| Writes a signed 32-bit value to the stream. | |
| void | writeInt32 (int i) |
| Writes a signed 32-bit value to the stream, casting from the supplied int. | |
| void | writeSize32 (VSizeType i) |
| Writes a signed 32-bit value to the stream, casting from the supplied size_type. | |
| void | writeU32 (Vu32 i) |
| Writes an unsigned 32-bit value to the stream. | |
| void | writeS64 (Vs64 i) |
| Writes a signed 64-bit value to the stream. | |
| void | writeU64 (Vu64 i) |
| Writes an unsigned 64-bit value to the stream. | |
| void | writeFloat (VFloat f) |
| Writes a single-precision floating-point value to the stream. | |
| void | writeDouble (VDouble d) |
| Writes a double-precision floating-point value to the stream. | |
| void | writeBool (bool i) |
| Writes a bool value to the stream. | |
| void | writeString (const VString &s) |
| Writes a VString value to the stream prefaced by dynamically-sized length indicator. | |
| void | writeString32 (const VString &s) |
| Writes a VString value to the stream prefaced by a 32-bit length indicator. | |
| void | writeInstant (const VInstant &i) |
| Writes a VInstant value to the stream. | |
| void | writeDuration (const VDuration &d) |
| Writes a VDuration value to the stream. | |
| void | writeDynamicCount (Vs64 count) |
| Writes a length/count/size indicator that is dynamically sized to fit the actual value, with an encoding so that it can be read. | |
Static Public Member Functions | |
| static int | getDynamicCountLength (Vs64 count) |
| Returns the number of bytes that the specified count value would take in a stream when streamed using the dynamic count format. | |
VBinaryIOStream is a concrete VIOStream subclass that provides well-typed stream i/o using network byte order for its data.
Because it uses network byte order, you can use VBinaryIOStream to read and write data to sockets and files, and be guaranteed that the data can travel across different host processors with different native byte ordering, and be processed correctly. For example, you can have a network client on an X86 processor communcating with a server on a Sun SPARC or Motorola PowerPC processor. Or, you can write a file on such a client, and manually move it to such a server and read it correctly. It also means that Java code, which uses network byte order inherently, can use the file format and wire protocols easily, without byte order work. This is the key to platform-independent data representation. The byte order transformation is handled inside this class.
The read methods all throw a VException if the data cannot be read, and in particular throw a VEOFException if EOF is encountered (but a read on a socket stream will normally just block rather than acting like EOF has been encountered).
The network byte order representation of data types, implemented by this class, is as follows:
| type | format |
| Vs8 and Vu8 | 1 byte |
| Vs16 and Vu16 | 2 bytes in network byte order (big endian) |
| Vs32 and Vu32 | 4 bytes in network byte order (big endian) |
| int | The readInt32/writeInt32 APIs are provided for convenience with the int data type, and use 4 bytes in network byte order (big endian) exactly like Vs32; the API names are intended to be completely clear about the number of bits used |
| Vs64 and Vu64 | 8 bytes in network byte order (big endian) |
| VFloat | 4 bytes in network byte order (big endian) |
| VDouble | 8 bytes in network byte order (big endian) |
| bool | 1 byte: 0 for false, 1 for true |
| VString | A length indicator "n", followed by n bytes of text. The length indicator is dynamically sized to avoid wasting space for small items, while allowing huge items. For example, an empty string takes 1 byte, and short strings have only 1 byte of overhead to indicate the length. See below. |
| "String 32" | A Vs32 (4 bytes) length indicator "n", followed by n bytes of text. Unlike VString described above, this form always has a length indicator that is 4 bytes long, regardless of string length. Thus an empty string takes 4 bytes, and every string has 4 bytes of overhead to indicate the length. |
| VInstant | The VInstant's internal Vs64 value. |
| VDuration | The VDuration's internal Vs64 value. |
The dynamically sized length indicator mode for VString allows short strings to have their length encoded in 1 byte, while still allowing for strings that exceed even 64K to still have their length encoded:
| Data Length | Length Indicator Length | Length Indicator Format |
| n <= 0x7F | 1 byte | 1 length byte (S8) |
| 0x80 <= n <= 0x7FFF | 3 bytes | indicator byte = -1, followed by 2 length bytes (S16) |
| 0x8000 <= n <= 0x7FFFFFFF | 5 bytes | indicator byte = -2, followed by 4 length bytes (S32) |
| 0x80000000 <= n | 9 bytes | indicator byte = -3, followed by 8 length bytes (S64) |
Of course, since VString uses an "int" to describe its length, it does not inherently support 64-bit length strings. This is reasonable since a string is not a suitable data structure for data larger than 4 gigabytes! You can still use arbitrary buffers and VMemoryStream objects for such large data, just not VString.
Definition at line 181 of file vbinaryiostream.h.
| VBinaryIOStream::VBinaryIOStream | ( | VStream & | rawStream | ) |
Constructs the object with an underlying raw stream.
| rawStream | the raw stream on which I/O will be performed |
Definition at line 22 of file vbinaryiostream.cpp.
| Vs8 VBinaryIOStream::readS8 | ( | ) |
Reads a signed 8-bit value from the stream.
Definition at line 27 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vu8 VBinaryIOStream::readU8 | ( | ) |
Reads an unsigned 8-bit value from the stream.
Definition at line 33 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vs16 VBinaryIOStream::readS16 | ( | ) |
Reads a signed 16-bit value from the stream.
Definition at line 39 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vu16 VBinaryIOStream::readU16 | ( | ) |
Reads an unsigned 16-bit value from the stream.
Definition at line 46 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vs32 VBinaryIOStream::readS32 | ( | ) |
Reads a signed 32-bit value from the stream.
Definition at line 53 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| int VBinaryIOStream::readInt32 | ( | ) |
Reads a signed 32-bit value from the stream, and casts the return value to int.
This is useful if you use int in your code and the data in question is known to fit in an int value, so that you do not have truncation concerns.
Definition at line 60 of file vbinaryiostream.cpp.
References readS32().
| Vu32 VBinaryIOStream::readU32 | ( | ) |
Reads an unsigned 32-bit value from the stream.
Definition at line 64 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vs64 VBinaryIOStream::readS64 | ( | ) |
Reads a signed 64-bit value from the stream.
Definition at line 71 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| Vu64 VBinaryIOStream::readU64 | ( | ) |
Reads an unsigned 64-bit value from the stream.
Definition at line 78 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| VFloat VBinaryIOStream::readFloat | ( | ) |
Reads a single-precision floating-point value from the stream.
Definition at line 85 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| VDouble VBinaryIOStream::readDouble | ( | ) |
Reads a double-precision floating-point value from the stream.
Definition at line 92 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::readGuaranteed().
| bool VBinaryIOStream::readBool | ( | ) |
Reads a bool value from the stream.
Definition at line 99 of file vbinaryiostream.cpp.
References readU8().
| void VBinaryIOStream::readString | ( | VString & | s | ) |
Reads a VString value from the stream, assuming it is prefaced by dynamically-sized length indicator as done in writeString.
| s | a VString to format |
Definition at line 103 of file vbinaryiostream.cpp.
References VString::EMPTY(), VString::getDataBuffer(), VString::postflight(), VString::preflight(), readDynamicCount(), and VIOStream::readGuaranteed().
| VString VBinaryIOStream::readString | ( | ) |
Reads a VString value from the stream, assuming it is prefaced by dynamically-sized length indicator as done in writeString, using a more natural syntax than readString(s), but incurring the overhead of creating two temporary copies instead of zero.
Definition at line 119 of file vbinaryiostream.cpp.
| void VBinaryIOStream::readString32 | ( | VString & | s | ) |
Reads a VString value from the stream, assuming it is prefaced by a 32-bit length indicator as done in writeString32.
| s | a VString to format |
Definition at line 132 of file vbinaryiostream.cpp.
References VString::EMPTY(), VString::getDataBuffer(), VString::isNotEmpty(), VString::postflight(), VString::preflight(), VIOStream::readGuaranteed(), and readS32().
| VString VBinaryIOStream::readString32 | ( | ) |
Reads a VString value from the stream, assuming it is prefaced by a 32-bit length indicator as done in writeString32, using a more natural syntax than readString(s), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero.
Definition at line 146 of file vbinaryiostream.cpp.
| void VBinaryIOStream::readInstant | ( | VInstant & | i | ) |
Reads a VInstant value from the stream.
| i | a VInstant to set |
Definition at line 159 of file vbinaryiostream.cpp.
References readS64(), and VInstant::setValue().
| VInstant VBinaryIOStream::readInstant | ( | ) |
Reads a VInstant value from the stream, using a more natural syntax than readInstant(i), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero.
Definition at line 164 of file vbinaryiostream.cpp.
References VInstant::instantFromRawValue(), and readS64().
| void VBinaryIOStream::readDuration | ( | VDuration & | d | ) |
Reads a VDuration value from the stream.
| d | a VDuration to set |
Definition at line 176 of file vbinaryiostream.cpp.
References readS64(), and VDuration::setDurationMilliseconds().
| VDuration VBinaryIOStream::readDuration | ( | ) |
Reads a VDuration value from the stream, using a more natural syntax than readDuration(d), but incurring the overhead (depending on the compiler) of creating a temporary copy or two instead of zero.
Definition at line 181 of file vbinaryiostream.cpp.
References VDuration::MILLISECOND(), and readS64().
| Vs64 VBinaryIOStream::readDynamicCount | ( | ) |
| void VBinaryIOStream::writeS8 | ( | Vs8 | i | ) |
Writes a signed 8-bit value to the stream.
| i | the Vs8 |
Definition at line 208 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeU8 | ( | Vu8 | i | ) |
Writes an unsigned 8-bit value to the stream.
| i | the Vu8 |
Definition at line 213 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeS16 | ( | Vs16 | i | ) |
Writes a signed 16-bit value to the stream.
| i | the Vs16 |
Definition at line 218 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeU16 | ( | Vu16 | i | ) |
Writes an unsigned 16-bit value to the stream.
| i | the Vu16 |
Definition at line 224 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeS32 | ( | Vs32 | i | ) |
Writes a signed 32-bit value to the stream.
| i | the Vs32 |
Definition at line 230 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeInt32 | ( | int | i | ) |
Writes a signed 32-bit value to the stream, casting from the supplied int.
This is useful if you use int in your code and the data in question is known to fit in a signed 32-bit value, so that you do not have truncation concerns.
| i | the int to be written as a Vs32 value |
Definition at line 240 of file vbinaryiostream.cpp.
References writeS32().
| void VBinaryIOStream::writeSize32 | ( | VSizeType | i | ) |
Writes a signed 32-bit value to the stream, casting from the supplied size_type.
This is useful if you have a size_type or STL collection in your code and the data in question is known to fit in a signed 32-bit value, so that you do not have truncation concerns.
| i | the int to be written as a Vs32 value |
Definition at line 236 of file vbinaryiostream.cpp.
References writeS32().
| void VBinaryIOStream::writeU32 | ( | Vu32 | i | ) |
Writes an unsigned 32-bit value to the stream.
| i | the Vu32 |
Definition at line 244 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeS64 | ( | Vs64 | i | ) |
Writes a signed 64-bit value to the stream.
| i | the Vs64 |
Definition at line 250 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeU64 | ( | Vu64 | i | ) |
Writes an unsigned 64-bit value to the stream.
| i | the Vu64 |
Definition at line 256 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeFloat | ( | VFloat | f | ) |
Writes a single-precision floating-point value to the stream.
| f | the VFloat |
Definition at line 262 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeDouble | ( | VDouble | d | ) |
Writes a double-precision floating-point value to the stream.
| d | the VDouble |
Definition at line 268 of file vbinaryiostream.cpp.
References CONST_S64, and VIOStream::write().
| void VBinaryIOStream::writeBool | ( | bool | i | ) |
Writes a bool value to the stream.
| i | the bool |
Definition at line 274 of file vbinaryiostream.cpp.
References writeU8().
| void VBinaryIOStream::writeString | ( | const VString & | s | ) |
Writes a VString value to the stream prefaced by dynamically-sized length indicator.
The length indicator is 1 byte for strings of length 252 or less, and is larger if the string length needs more bytes to be represented.
| s | the VString |
Definition at line 278 of file vbinaryiostream.cpp.
References VString::getDataBufferConst(), VString::length(), VIOStream::write(), and writeDynamicCount().
| void VBinaryIOStream::writeString32 | ( | const VString & | s | ) |
Writes a VString value to the stream prefaced by a 32-bit length indicator.
| s | the VString |
Definition at line 283 of file vbinaryiostream.cpp.
References VString::getDataBufferConst(), VString::length(), VIOStream::write(), and writeS32().
| void VBinaryIOStream::writeInstant | ( | const VInstant & | i | ) |
Writes a VInstant value to the stream.
| i | the VInstant |
Definition at line 288 of file vbinaryiostream.cpp.
References VInstant::getValue(), and writeS64().
| void VBinaryIOStream::writeDuration | ( | const VDuration & | d | ) |
Writes a VDuration value to the stream.
| d | the VDuration |
Definition at line 292 of file vbinaryiostream.cpp.
References VDuration::getDurationMilliseconds(), and writeS64().
| void VBinaryIOStream::writeDynamicCount | ( | Vs64 | count | ) |
Writes a length/count/size indicator that is dynamically sized to fit the actual value, with an encoding so that it can be read.
The purpose is to be as compact as possible for typical small counts, while still allowing for arbitrarily large values that might be encountered less frequently.
| count | the count value |
Definition at line 296 of file vbinaryiostream.cpp.
References writeU16(), writeU32(), writeU64(), and writeU8().
| int VBinaryIOStream::getDynamicCountLength | ( | Vs64 | count | ) | [static] |
Returns the number of bytes that the specified count value would take in a stream when streamed using the dynamic count format.
| count | the count value |
Definition at line 338 of file vbinaryiostream.cpp.