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
LPSomeUVarint = uint | uint64 | uint32 | uint16 | uint8
- Source Edit
PBSomeUVarint = uint | uint64 | uint32
- Source Edit
VarintError {.pure.} = enum Error, Overflow, Incomplete, Overlong, Overrun
- Source Edit
VarintResult[T] = Result[T, VarintError]
- 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