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]

buffer

The 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:

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.

Parameters:

[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.

Returns:

A vector containing the encoded data.

Exceptions:

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.

Parameters:

[in]

input

The 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:

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.

Parameters:

[in]

integer

The integer to offset.

Returns:

The offset integer as an unsigned data type and the number of bytes it requires.

Exceptions:

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.

Parameters:

[in]

integer

The integer to get the size of.

Returns:

The size, in bytes, that the integer will require when coded.

Exceptions:

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.

Parameters:

[in]

integer

The integer to offset, including both the integer itself and its size in bytes.

Returns:

The offset integer as a signed data type.

Exceptions:

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.

Parameters:

[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.

Returns:

The number of bytes written.

Exceptions:

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.