This module implements Variable Integer VARINT. This module supports two variants of variable integer

Google ProtoBuf varint, which is able to encode full uint64 number and maximum size of encoded value is 10 octets (bytes). https://developers.google.com/protocol-buffers/docs/encoding#varints
LibP2P varint, which is able to encode only 63bits of uint64 number and maximum size of encoded value is 9 octets (bytes). https://github.com/multiformats/unsigned-varint

Types

hint = distinct int: Signed integer types which will be encoded using simple cast. Source Edit
hint32 = distinct int32: Source Edit
hint64 = distinct int64: Source Edit
LP = object: Use this type to specify LibP2P varint encoding Source Edit
LPSomeUVarint = uint | uint64 | uint32 | uint16 | uint8: Source Edit
LPSomeVarint = LPSomeUVarint: Source Edit
PB = object: Use this type to specify Google ProtoBuf's varint encoding Source Edit
PBSomeSVarint = hint | hint64 | hint32: Source Edit
PBSomeUVarint = uint | uint64 | uint32: Source Edit
PBSomeVarint = PBSomeUVarint | PBSomeSVarint | PBZigVarint: Source Edit
PBZigVarint = zint | zint64 | zint32: Source Edit
SomeUVarint = PBSomeUVarint | LPSomeUVarint: Source Edit
SomeVarint = PBSomeVarint | LPSomeVarint: Source Edit
VarintError {.pure.} = enum Error, Overflow, Incomplete, Overlong, Overrun: Source Edit
VarintResult[T] = Result[T, VarintError]: Source Edit
zint = distinct int: Signed integer types which will be encoded using zigzag encoding. Source Edit
zint32 = distinct int32: Source Edit
zint64 = distinct int64: Source Edit

Procs

proc encodeVarint(vtype: typedesc[LP]; value: LPSomeVarint): VarintResult[
    seq[byte]] {.inline, ...raises: [].}

Encode integer to LibP2P unsigned varint and returns sequence of bytes as buffer. Source Edit

proc encodeVarint(vtype: typedesc[PB]; value: PBSomeVarint): VarintResult[
    seq[byte]] {.inline, ...raises: [].}

Encode integer to Google ProtoBuf's signed/unsigned varint and returns sequence of bytes as buffer. Source Edit

proc getSVarint(pbytes: openArray[byte]; outsize: var int;
                outval: var (PBZigVarint | PBSomeSVarint)): VarintResult[void] {.
    inline, ...raises: [].}

Decode signed integer (int32 or int64) from buffer pbytes and store it to outval.

On success outlen will be set to number of bytes processed while decoding signed varint.

If array pbytes is empty, Incomplete error will be returned.

If there not enough bytes available in array pbytes to decode signed varint, Incomplete error will be returned.

If encoded value can produce integer overflow, Overflow error will be returned.

Note, when decoding 10th byte of 64bit integer only 1 bit from byte will be decoded, all other bits will be ignored. When decoding 5th byte of 32bit integer only 4 bits from byte will be decoded, all other bits will be ignored.

Source Edit

proc getUVarint[T: PB | LP](vtype: typedesc[T]; pbytes: openArray[byte];
                            outlen: var int; outval: var SomeUVarint): VarintResult[
    void] {....raises: [].}

Decode unsigned varint from buffer pbytes and store it to outval. On success outlen will be set to number of bytes processed while decoding unsigned varint.

If array pbytes is empty, Incomplete error will be returned.

If there not enough bytes available in array pbytes to decode unsigned varint, Incomplete error will be returned.

If encoded value can produce integer overflow, Overflow error will be returned.

Google ProtoBuf When decoding 10th byte of Google Protobuf's 64bit integer only 1 bit from byte will be decoded, all other bits will be ignored. When decoding 5th byte of 32bit integer only 4 bits from byte will be decoded, all other bits will be ignored.

LibP2P When decoding 5th byte of 32bit integer only 4 bits from byte will be decoded, all other bits will be ignored.

Source Edit

proc getVarint[T: PB | LP](vtype: typedesc[T]; pbytes: openArray[byte];
                           nbytes: var int; value: var SomeVarint): VarintResult[
    void] {.inline, ...raises: [].}

Source Edit

proc putSVarint(pbytes: var openArray[byte]; outsize: var int;
                outval: (PBZigVarint | PBSomeSVarint)): VarintResult[void] {.
    inline, ...raises: [].}

Encode signed integer outval using ProtoBuffer's zigzag encoding (sint32 or sint64) and store it to array pbytes.

On success outlen will hold number of bytes (octets) used to encode unsigned integer v.

If there not enough bytes available in buffer pbytes, Incomplete error will be returned and outlen will be set to number of bytes required.

Maximum encoded length of 64bit integer is 10 octets. Maximum encoded length of 32bit integer is 5 octets.

Source Edit

proc putUVarint[T: PB | LP](vtype: typedesc[T]; pbytes: var openArray[byte];
                            outlen: var int; outval: SomeUVarint): VarintResult[
    void] {....raises: [].}

Encode unsigned varint outval and store it to array pbytes.

On success outlen will hold number of bytes (octets) used to encode unsigned integer v.

If there not enough bytes available in buffer pbytes, Incomplete error will be returned and outlen will be set to number of bytes required.

Google ProtoBuf Maximum encoded length of 64bit integer is 10 octets. Maximum encoded length of 32bit integer is 5 octets.

LibP2P Maximum encoded length of 63bit integer is 9 octets. Maximum encoded length of 32bit integer is 5 octets.

Source Edit

proc putVarint[T: PB | LP](vtype: typedesc[T]; pbytes: var openArray[byte];
                           nbytes: var int; value: SomeVarint): VarintResult[
    void] {.inline, ...raises: [].}

Source Edit

proc vsizeof(x: SomeVarint): int {.inline, ...raises: [].}

Returns number of bytes required to encode integer x as varint. Source Edit

Templates

template toBytes(vtype: typedesc[PB]; value: PBSomeVarint): auto: Source Edit

libp2p/varint

Types

Procs

Templates