NAME

LEB128 - Encoding and decoding of integers in the LEB128 encoding

SYNOPSIS

use LEB128;

my $buf-eu = encode-leb128-unsigned(1234);
my $buf-es = encode-leb128-signed(-1234);

DESCRIPTION

LEB128 or Little Endian Base 128 is a variable-length encoding of integers - that is, it aims to store integers of different sizes efficiently. It is used in the DWARF debug information format, Web Assembly, and other formats and protocols. This Raku module provides both encoding and decoding.

Encoding

There are both signed and unsigned encoding functions, encode-leb128-signed and encode-leb128-unsigned respectively. Both are multis with candidates that take an Int and return a Buf with the encoded value:

my $buf-eu = encode-leb128-unsigned(1234);
my $buf-es = encode-leb128-signed(-1234);

Or to write the encoded Int into a Buf and return the number of bytes written, which is often more efficient since it avoids the creation of a temporary Buf:

my $buf = Buf.new;
my $offset = 0;
$offset += encode-leb128-unsigned(1234, $buf, $offset);

Decoding

There are both signed and unsigned decoding functions, decode-leb128-signed and decode-leb128-unsigned respectively. Both are multis with candidates that take a Buf and try to decode an Int from the start of it, returning that Int:

my $value-du = decode-leb128-unsigned($entire-buffer-u);
my $value-ds = decode-leb128-signed($entire-buffer-s);

Or that decode the value from a specified offset in a given buffer, and use an rw parameter of type int, which is incremented by the number of bytes consumed.

my int $read;
my $value = decode-leb128-unsigned($buffer, $offset, $read);

To have the offset updated, it may be passed as both parameters:

my $value = decode-leb128-unsigned($buffer, $offset, $offset);

Method reference

multi sub encode-leb128-signed

multi sub encode-leb128-signed(
    Int $value is copy,
    Buf $target,
    int $offset = 0
) returns int

Encodes the provided signed value into the target buffer at the given offset, returning the number of bytes produced.

multi sub encode-leb128-signed

multi sub encode-leb128-signed(
    Int $value
) returns Buf

Encodes the provided signed value into a C and returns it.

multi sub encode-leb128-unsigned

multi sub encode-leb128-unsigned(
    Int $value is copy,
    Buf $target,
    int $offset = 0
) returns int

Encodes the provided unsigned value into the target buffer at the

multi sub encode-leb128-unsigned

multi sub encode-leb128-unsigned(
    Int $value
) returns Buf

Encodes the provided unsigned value into a C and returns it.

class X::LEB128::Incomplete

This exception is thrown if LEB128 decoding fails due to there being an incomplete value at the end of the buffer.

multi sub decode-leb128-unsigned

multi sub decode-leb128-unsigned(
    Buf $encoded,
    int $offset is copy,
    int $read is rw
) returns Mu

Decodes an unsigned value from the provided buffer starting at the specified offset. The final rw parameter is incremented for each byte consumed from the buffer. Throws X::LEB128::Incomplete if a complete value cannot be read.

multi sub decode-leb128-unsigned

multi sub decode-leb128-unsigned(
    Buf $encoded
) returns Int

Decodes the provided C and returns the resulting unsigned value. Throws X::LEB128::Incomplete if a complete value cannot be read.

multi sub decode-leb128-signed

multi sub decode-leb128-signed(
    Buf $encoded,
    int $offset is copy,
    int $read is rw
) returns Mu

Decodes a signed value from the provided buffer starting at the specified offset. The final rw parameter is incremented for each byte consumed from the buffer. Throws X::LEB128::Incomplete if a complete value cannot be read.

multi sub decode-leb128-signed

multi sub decode-leb128-signed(
    Buf $encoded
) returns Int

Decodes the provided C and returns the resulting signed value. Throws X::LEB128::Incomplete if a complete value cannot be read.

AUTHOR

Jonathan Worthington

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.