Tide 0.1.0
Typedefs | Functions

tide::vint Namespace Reference

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.

Detailed Description

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 Documentation

typedef std::pair<uint64_t, std::vector<char>::const_iterator> tide::vint::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.

Definition at line 137 of file vint.h.

typedef std::pair<uint64_t, std::streamsize> tide::vint::OffsetInt

The result type of s_to_u().

The first contains the offset integer. The second contains the number of bytes to be used to store the integer.

Definition at line 77 of file vint.h.

typedef std::pair<uint64_t, std::streamsize> tide::vint::ReadResult

The result of a read operation is a pair of the integer read and the number of bytes read.

Definition at line 178 of file vint.h.


Function Documentation

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.

Parameters:
[in]bufferThe buffer holding the raw data.
Returns:
The DecodeResult, containing the decoded integer. and the number of bytes used from the buffer in the second.
Exceptions:
InvalidVarIntif the first byte in the buffer is zero, an invalid starting byte for a variable-length integer.
BufferTooSmallif 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.

Parameters:
[in]integerThe integer to encode.
[in]req_sizeIf 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.
Returns:
A vector containing the encoded data.
Exceptions:
VarIntTooBigif the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF).
SpecSizeTooSmallif 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.

Parameters:
[in]inputThe std::istream object to read bytes from.
Returns:
A pair containing the value read in the first and the number of bytes read from the stream in the second.
Exceptions:
InvalidVarIntif the variable-length integer in the byte stream is invalid.
ReadErrorif 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.

Parameters:
[in]integerThe integer to offset.
Returns:
The offset integer as an unsigned data type and the number of bytes it requires.
Exceptions:
VarIntTooBigif 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.

Parameters:
[in]integerThe integer to get the size of.
Returns:
The size, in bytes, that the integer will require when coded.
Exceptions:
VarIntTooBigif 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.

Parameters:
[in]integerThe integer to offset, including both the integer itself and its size in bytes.
Returns:
The offset integer as a signed data type.
Exceptions:
VarIntTooBigif 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.

Parameters:
[in]integerThe integer to encode.
[in]outputThe std::ostream object to write the encoded integer to.
[in]req_sizeIf 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.
Returns:
The number of bytes written.
Exceptions:
VarIntTooBigif the integer is above the maximum value for variable-length integers (0xFFFFFFFFFFFFFF).
WriteErrorif there is an error writing to the stream.
SpecSizeTooSmallif the integer is too big for the requested size.
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines