Crate gvli

Crate gvli 

Source
Expand description

§Generalized variable-length integers

This crate implements the “generalized variable-length integers” described in RFC 3492 section 3.3. This implementation is generic, so that it may be used outside of just RFC 3492 implementations.

This crate implements only little-endian encoding and decoding, as they are the only ones described in the RFC and associated litterature.

§Example

let parameters = gvli::Parameters::from_parts(&gvli::BASE_OCTAL, &[2, 3, 5]).unwrap();

let encoded = gvli::encode(&[145, 62], &parameters);
assert_eq!(encoded, "734251");

let decoded = gvli::decode(&encoded, &parameters).unwrap();
assert_eq!(decoded, [145, 62]);

§Usage

§Parameters

GVLI encoding and decoding requires having:

  • a base: a finite sequence of digits; a mapping of chars to numbers;
  • a thresholds sequence: an infinite sequence of numbers which allows for discriminating terminating digits from non-terminating ones.

For one application, both of these settings are going to be fixed, so they are grouped into one struct: Parameters.

A convenience constant is provided for the specific case of Punycode: PUNYCODE.

§Encoding

Encoding takes a sequence of numbers and turns them into a sequence of chars, the digits. Four encoding functions are provided:

Encoding never fails: all possible violations are checked by Parameters::from_parts().

§Decoding

Decoding takes a sequence of chars, the digits, and turns them into a sequence of numbers. Because it is impossible to know in advance how many numbers are encoded, and if they are encoded correctly, only one function is provided: decode().

Decoding may fail:

  • if a digit that is not part of the base is encountered,
  • if the sequence of chars ends on a non-terminating digit.

Structs§

Parameters
The parameters of the GVLI encoding/decoding process: the base and thresholds.

Enums§

GVLIError
Error type returned by the GVLI APIs.

Constants§

BASE_DECIMAL
Convenience base array for a base defining its digits as 0 to 9.
BASE_HEX
Convenience base array for a base defining its digits as 0 to 9, then A to F.
BASE_OCTAL
Convenience base array for a base defining its digits as 0 to 7.
BASE_PUNYCODE
Convenience base array for Punycode encoding: a to z, then 0 to 9.
PUNYCODE
Convenience Parameters for Punycode encoding. See BASE_PUNYCODE and THRESHOLDS_PUNYCODE.
THRESHOLDS_PUNYCODE
Convenience thresholds array for Punicode encoding: 1 twice, then 26 repeated infinitely.

Functions§

decode
Decode a sequence of GVLI.
encode
Encode a sequence of numbers, creating a new String.
encode_noalloc
Encode a sequence of numbers, appending to an existing String.
encode_one
Encode a single number, creating a new String.
encode_one_noalloc
Encode a single number, appending to an existing String.