leb128

README

LEB128

Little Endian Base 128 | Variable-Length Code Compression

Uses

• LEB128 is used in the WebAssembly binary encoding for all integer literals.
• LEB128 is used by Candid to serialise types into a binary representation for transfer between services.

Documentation

Overview

Package leb128 or Little Endian Base 128 is a form of variable-length code compression used to store an arbitrarily large integer in a small number of bytes.

Index

• func ReadSigned(buf *bytes.Buffer) (int, error)
• func ReadUnsigned(buf *bytes.Buffer) (uint, error)
• func WriteSigned(buf *bytes.Buffer, v int) error
• func WriteUnsigned(buf *bytes.Buffer, v uint) error
• type LEB128
  • func FromUInt(n uint) LEB128
  • func (l LEB128) ToUInt() uint
• type SLEB128
  • func FromInt(n int) SLEB128
  • func (l SLEB128) ToInt() int

Examples

• FromInt
• FromUInt

Functions

func ReadSigned

func ReadSigned(buf *bytes.Buffer) (int, error)

ReadSigned reads a signed leb128 from the given buffer.

func ReadUnsigned

func ReadUnsigned(buf *bytes.Buffer) (uint, error)

ReadUnsigned reads an unsigned leb128 from the given buffer.

func WriteSigned

func WriteSigned(buf *bytes.Buffer, v int) error

WriteSigned writes the given signed int as sleb128 to the given buffer.

func WriteUnsigned

func WriteUnsigned(buf *bytes.Buffer, v uint) error

WriteUnsigned writes the given unsigned int as leb128 to the given buffer.

Types

type LEB128

type LEB128 []byte

LEB128 represents an unsigned number encoded using (unsigned) LEB128.

func FromUInt

func FromUInt(n uint) LEB128

FromUInt encodes an unsigned integer.

Example

package main

import (
	"fmt"
	"github.com/internet-computer/leb128"
)

func main() {
	// MSB ------------------ LSB
	//       10011000011101100101  In raw binary
	//      010011000011101100101  Padded to a multiple of 7 bits
	//  0100110  0001110  1100101  Split into 7-bit groups
	// 00100110 10001110 11100101  Add high 1 bits on all but last (most significant) group to form bytes
	//     0x26     0x8E     0xE5  In hexadecimal
	//
	// -> 0xE5 0x8E 0x26           Output stream (LSB to MSB)
	for _, b := range leb128.FromUInt(624485) {
		fmt.Printf("0x%X: %08b\n", b, b)
	}
	fmt.Println(leb128.LEB128{0xE5, 0x8E, 0x26}.ToUInt())
}

Output:

0xE5: 11100101
0x8E: 10001110
0x26: 00100110
624485

func (LEB128) ToUInt

func (l LEB128) ToUInt() uint

ToUInt converts the byte slice back the an unsigned integer.

type SLEB128

type SLEB128 []byte

SLEB128 represents a signed number encoded using signed LEB128.

func FromInt

func FromInt(n int) SLEB128

FromInt encodes a signed integer.

Example

package main

import (
	"fmt"
	"github.com/internet-computer/leb128"
)

func main() {
	// MSB ------------------ LSB
	//          11110001001000000  Binary encoding of 123456
	//      000011110001001000000  As a 21-bit number
	//      111100001110110111111  Negating all bits (one’s complement)
	//      111100001110111000000  Adding one (two’s complement)
	//  1111000  0111011  1000000  Split into 7-bit groups
	// 01111000 10111011 11000000  Add high 1 bits on all but last (most significant) group to form bytes
	//     0x78     0xBB     0xC0  In hexadecimal
	//
	// -> 0xC0 0xBB 0x78           Output stream (LSB to MSB)
	for _, b := range leb128.FromInt(-123456) {
		fmt.Printf("0x%X: %08b\n", b, b)
	}
	fmt.Println(leb128.SLEB128{0xC0, 0xBB, 0x78}.ToInt())
}

Output:

0xC0: 11000000
0xBB: 10111011
0x78: 01111000
-123456

func (SLEB128) ToInt

func (l SLEB128) ToInt() int

ToInt converts the byte slice back the a signed integer.