@hookun/vlq

A tool to encode/decode arbitrary unsigned integers using predefined-length chunk of bits.

Usage

import {encodeToArrayBuffer, decodeToArray} from '@hookhookun/vlq';
const data = [1, 2, 3, 4];
const encoded1 = encodeToArrayBuffer(data, 1);
console.info(Buffer.from(encoded1).toString('hex'));
// 073788
console.info(Buffer.from(encoded1).toString('base64url'));
// BzeI
console.info(decodeToArray(encoded1));
// [ 1, 2, 3, 4 ]
const encoded2 = encodeToArrayBuffer(data, 2);
console.info(Buffer.from(encoded1).toString('hex'));
// 129d10
console.info(Buffer.from(encoded1).toString('base64url'));
// Ep0Q
console.info(decodeToArray(encoded1));
// [ 1, 2, 3, 4 ]

Install

npm install @hookun/vlq

API document

docs/modules.md

Format of encoded binary

Encoded     = ChunkSize -> Data -> EndOfChunks
ChunkSize   = Value(3,C-1)
Data        = *Value(C,x)
EndOfChunks = SB(C,0)
Value(n,x)  = *SB(n,x1) -> LSB(n,x0)
SB(n,x)     = 1xxxxxxxxxxx
               | <- n -> |
LSB(n,y)    = 0yyyyyyyyyyy

The binary representation of ChunkSize is 1 less than the actual value.

Example: Value(1+n) and EndOfChunks (EOC)

Assume that ChunkSize is 1.

| x| Value(1,x)| |----:|----------------:| | 0| 00| | 1| 01| | 2| 11 00| | 3| 11 01| | 4| 11 10 00| | 5| 11 10 01| | 8| 11 10 10 00| | 16| 11 10 10 10 00| | EOC| 10|

Assume that ChunkSize is 2.

| x| Value(2,x)| |----:|----------------:| | 0| 000| | 1| 001| | 2| 010| | 3| 011| | 4| 101 000| | 5| 101 001| | 8| 110 000| | 16| 101 100 000| | 32| 110 100 000| | 64|101 100 100 000| | EOC| 100|

Assume that ChunkSize is 3.

| x| Value(3,x)| |----:|---------------:| | 0| 0000| | 1| 0001| | 2| 0010| | 3| 0011| | 4| 0100| | 8| 1001 0000| | 16| 1010 0000| | 32| 1100 0000| | 64|1001 1000 0000| | EOC| 1000|

Example: Encoded

Assume that Data is [1, 2, 3, 4] ChunkSize is 1.

EndOfChunks = 10
Data        = 01 11 00 11 01 11 10 00
ChunkSize   = 0000
Encoded     = 0000 01 11 00 11 01 11 10 00 10
            = ChunkSize -> Data -> EndOfChunks
            = 0000011100110111100010
            = 0000 0111 0011 0111 1000 10(00)
            =    0    7    3    7    8     8
            = 0x073788

Assume that Data is [1, 2, 3, 4] ChunkSize is 2.

EndOfChunks = 100
Data        = 001 010 011 101 000
ChunkSize   = 0001
Encoded     = 0001 001 010 011 101 000 100
            = ChunkSize -> Data -> EndOfChunks
            = 0001001010011101000100
            = 0001 0010 1001 1101 0001 00(00)
            =    1    2    9    d    1     0
            = 0x129d10

Example: decoding 0x51450f2880

Encoded =    5   1   4   5   0   f   2   8   8   0
        = 0101000101000101000011110010100010000000
          ^^^^|          <-   Data   ->          |

Since ChunkSize is 5, divide Data into (5+offset+flag bit)=(5+1+1)=7 bits each.

Data = 0001010 0010100 0011110 0101000 1000000 0
     =      10      20      30      40     EOC
     = [10, 20, 30, 40]

License

Apache License, Version 2.0