libgslutil  1.2.3
Functions
Variable-length integer packing

Functions

int vint_pack_u16 (uint16_t val, char *buf))
 Pack a 16-bit unsigned integer. More...
 
int vint_pack_s16 (int16_t val, char *buf))
 Pack a 16-bit signed integer. More...
 
int vint_pack_u32 (uint32_t val, char *buf))
 Pack a 32-bit unsigned integer. More...
 
int vint_pack_s32 (int32_t val, char *buf))
 Pack a 32-bit signed integer. More...
 
int vint_pack_u64 (uint64_t val, char *buf))
 Pack a 64-bit unsigned integer. More...
 
int vint_pack_s64 (int64_t val, char *buf))
 Pack a 64-bit signed integer. More...
 
int vint_unpack_u16 (const char *buf, int buf_len, uint16_t *val))
 Unpack a 16-bit unsigned integer. More...
 
int vint_unpack_s16 (const char *buf, int buf_len, int16_t *val))
 Unpack a 16-bit signed integer. More...
 
int vint_unpack_u32 (const char *buf, int buf_len, uint32_t *val))
 Unpack a 32-bit unsigned integer. More...
 
int vint_unpack_s32 (const char *buf, int buf_len, int32_t *val))
 Unpack a 32-bit signed integer. More...
 
int vint_unpack_u64 (const char *buf, int buf_len, uint64_t *val))
 Unpack a 64-bit unsigned integer. More...
 
int vint_unpack_s64 (const char *buf, int buf_len, int64_t *val))
 Unpack a 64-bit signed integer. More...
 

Detailed Description

This module provides a set of functions for packing and unpacking integers to/from an efficient form which contains only the bits of the number that are actually used. The resulting packed objects are a variable number of bytes long (from 1 to 10, for a full 64-bit number). This packing is most efficient for integers of small numerical magnitude.

The first bit of each byte is the continuation bit. If it is set, then another byte of data follows. If it is unset, then this is the last byte of data. In a multi-byte number, the last byte can never be 0x00; this means that there is no ambiguity of representation.

For an unsigned number, the first byte contains the 7 least significant bits of the number. Each byte thereafter contains the 7 next most significant bits. Once all bits set in the original number have been stored in bytes, the packing is complete.

Signed numbers are not transmitted as 2's complement (as this would defeat the short packing scheme used above), but instead as a sign bit and magnitude. The sign bit is transmitted along with the least significant byte in the result, which means the first byte contains only the 6 least significant bits of the number. The sign bit is the least significant bit of the first byte.

The decoding algorithm for an unsigned number is as follows:

The decoding algorithm for a signed number is as follows:

A diagram show the structure of the coded numbers is below:

<

pre>Unsigned, only 7 bits

byte (MSB) bit meanings (LSB) 0 [0]: continuation bit clear [xxx xxxx]: data

Unsigned, > 7 bits

byte (MSB) bit meanings (LSB) 0 [1]: continuation bit set [xxx xxxx]: data least significant 7 bits ... [1]: continuation bit set [xxx xxxx]: data next most significant 7 bits n [0]: continuation bit clear [xxx xxxx]: data most significant 7 bits

Signed, only 6 bits

byte (MSB) bit meanings (LSB) 0 [0]: continuation bit clear [xxx xxx]: data [s]: sign

Signed, > 6 bits

byte (MSB) bit meanings (LSB) 0 [1]: continuation bit set [xxx xxx]: data [s]: sign ... [1]: continuation bit set [xxx xxxx]: data next most significant 7 bits n [0]: continuation bit clear [xxx xxxx]: data most significant 7 bits

Function Documentation

◆ vint_pack_u16()

int vint_pack_u16 ( uint16_t  val,
char *  buf 
)

Pack a 16-bit unsigned integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 3 bytes free).
Returns
Number of bytes written.

◆ vint_pack_s16()

int vint_pack_s16 ( int16_t  val,
char *  buf 
)

Pack a 16-bit signed integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 3 bytes free).
Returns
Number of bytes written.

◆ vint_pack_u32()

int vint_pack_u32 ( uint32_t  val,
char *  buf 
)

Pack a 32-bit unsigned integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 5 bytes free).
Returns
Number of bytes written.

◆ vint_pack_s32()

int vint_pack_s32 ( int32_t  val,
char *  buf 
)

Pack a 32-bit signed integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 5 bytes free).
Returns
Number of bytes written.

◆ vint_pack_u64()

int vint_pack_u64 ( uint64_t  val,
char *  buf 
)

Pack a 64-bit unsigned integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 10 bytes free).
Returns
Number of bytes written.

◆ vint_pack_s64()

int vint_pack_s64 ( int64_t  val,
char *  buf 
)

Pack a 64-bit signed integer.

Parameters
valValue to pack.
bufBuffer to write to (must have at least 10 bytes free).
Returns
Number of bytes written.

◆ vint_unpack_u16()

int vint_unpack_u16 ( const char *  buf,
int  buf_len,
uint16_t *  val 
)

Unpack a 16-bit unsigned integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.

◆ vint_unpack_s16()

int vint_unpack_s16 ( const char *  buf,
int  buf_len,
int16_t *  val 
)

Unpack a 16-bit signed integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.

◆ vint_unpack_u32()

int vint_unpack_u32 ( const char *  buf,
int  buf_len,
uint32_t *  val 
)

Unpack a 32-bit unsigned integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.

◆ vint_unpack_s32()

int vint_unpack_s32 ( const char *  buf,
int  buf_len,
int32_t *  val 
)

Unpack a 32-bit signed integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.

◆ vint_unpack_u64()

int vint_unpack_u64 ( const char *  buf,
int  buf_len,
uint64_t *  val 
)

Unpack a 64-bit unsigned integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.

◆ vint_unpack_s64()

int vint_unpack_s64 ( const char *  buf,
int  buf_len,
int64_t *  val 
)

Unpack a 64-bit signed integer.

Parameters
bufBuffer to read from.
buf_lenNumber of bytes in buf.
[out]valRetrieved value.
Returns
Number of bytes read.
Return values
-1on error.