Tide 0.1.0
|
Functions for managing variable-length integers. More...
Typedefs | |
typedef std::pair< uint64_t, std::streamsize > | OffsetInt |
The result type of s_to_u(). | |
typedef std::pair< uint64_t, std::vector< char > ::const_iterator > | DecodeResult |
The result of a decode operation is a pair of the integer decoded and an iterator pointing to the first element after the used data. | |
typedef std::pair< uint64_t, std::streamsize > | ReadResult |
The result of a read operation is a pair of the integer read and the number of bytes read. | |
Functions | |
std::streamsize | size (uint64_t integer) |
Get the size of an integer after encoding. | |
OffsetInt | s_to_u (int64_t integer) |
Offsets a signed integer into unsigned territory. | |
int64_t | u_to_s (OffsetInt integer) |
Offsets an unsigned integer into signed territory. | |
std::vector< char > | encode (uint64_t integer, std::streamsize req_size=0) |
Encode an unsigned integer into a buffer. | |
DecodeResult | decode (std::vector< char > const &buffer) |
Decode an unsigned variable-length integer from a buffer. | |
std::streamsize | write (uint64_t integer, std::ostream &output, std::streamsize req_size=0) |
Encode an unsigned integer and write it to an output stream. | |
ReadResult | read (std::istream &input) |
Decode an unsigned integer from an input stream. |
Functions for managing variable-length integers.
This namespace contains the functions used to manage variable-length integers. These are a part of the EBML specification that stores unsigned integers for the Element IDs and Element data sizes in a UTF-8-like encoding scheme, using leading zeros to indicate the value's stored size. This allows integers of varying length to be stored without needing a separate byte count value.
Note that this is distinct from the coding used on standard integers (signed and unsigned) stores in element bodies, which merely truncates leading 0x00 and 0xFF values.
typedef std::pair<uint64_t, std::vector<char>::const_iterator> tide::vint::DecodeResult |
typedef std::pair<uint64_t, std::streamsize> tide::vint::OffsetInt |
typedef std::pair<uint64_t, std::streamsize> tide::vint::ReadResult |
DecodeResult tide::vint::decode | ( | std::vector< char > const & | buffer | ) |
Decode an unsigned variable-length integer from a buffer.
Decodes the variable-length integer stored in the buffer.
[in] | buffer | The buffer holding the raw data. |
InvalidVarInt | if the first byte in the buffer is zero, an invalid starting byte for a variable-length integer. |
BufferTooSmall | if the expected encoded length of the variable-length integer is larger than the available buffer length. |
std::vector<char> tide::vint::encode | ( | uint64_t | integer, |
std::streamsize | req_size = 0 |
||
) |
Encode an unsigned integer into a buffer.
Encodes an unsigned variable-length integer according to the EBML specification. Leading zero bits are used to indicate the length of the encoded integer in bytes.
The vector provided as a buffer must already have enough space to store the encoded data reserved. This can be done by either reserving the maximum possible size (8 bytes) or by using size() to find the required size.
[in] | integer | The integer to encode. |
[in] | req_size | If not zero, then use this length when encoding the integer instead of the optimal size. Must be equal to or larger than the optimal size. |
VarIntTooBig | if the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF). |
SpecSizeTooSmall | if the integer is too big for the requested size. |
ReadResult tide::vint::read | ( | std::istream & | input | ) |
Decode an unsigned integer from an input stream.
This function performs the same task as tide::vint::decode(), but it reads the bytes from the input stream rather than a simple buffer.
[in] | input | The std::istream object to read bytes from. |
InvalidVarInt | if the variable-length integer in the byte stream is invalid. |
ReadError | if there is an error reading the input stream. |
OffsetInt tide::vint::s_to_u | ( | int64_t | integer | ) |
Offsets a signed integer into unsigned territory.
EBML variable-length integers are always unsigned. In order to represent a signed integer, as is done in laced blocks using EBML lacing, it must be offset into the unsigned territory. This function offsets a signed integer by half the range of its required storage space to make it unsigned.
[in] | integer | The integer to offset. |
VarIntTooBig | if the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF). |
std::streamsize tide::vint::size | ( | uint64_t | integer | ) |
Get the size of an integer after encoding.
The size required by an encoded integer depends on the value of that integer, and will range from 1 to 8 bytes.
[in] | integer | The integer to get the size of. |
VarIntTooBig | if the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF). |
int64_t tide::vint::u_to_s | ( | OffsetInt | integer | ) |
Offsets an unsigned integer into signed territory.
EBML variable-length integers are always unsigned. In order to represent a signed integer, as is done in laced blocks using EBML lacing, it must be offset into the unsigned territory. This function offsets an unsigned integer by half the range of its required storage space to make it signed.
[in] | integer | The integer to offset, including both the integer itself and its size in bytes. |
VarIntTooBig | if the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF). |
std::streamsize tide::vint::write | ( | uint64_t | integer, |
std::ostream & | output, | ||
std::streamsize | req_size = 0 |
||
) |
Encode an unsigned integer and write it to an output stream.
This function performs the same task as tide::vint::encode(), but it writes the result to a std::ostream instead of a simple buffer.
[in] | integer | The integer to encode. |
[in] | output | The std::ostream object to write the encoded integer to. |
[in] | req_size | If not zero, then use this length when encoding the integer instead of the optimal size. Must be equal to or larger than the optimal size. |
VarIntTooBig | if the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF). |
WriteError | if there is an error writing to the stream. |
SpecSizeTooSmall | if the integer is too big for the requested size. |