README

VLQ (可变长度数量) Base64 算法编解码器 (PHP)

文档

VQL + Base64

Base64 允许我们将一串数字表示为文本字符串，可以存储和以文本格式（JSON、XML 等）传输。

VLQ 允许我们用较小的数字容量表示一个整数。例如，Base64 的限制是 6 位。产生的数字称为 "VLQ 数字"。较小的输入数字用较少的 VLQ 数字表示。因此，如果输入序列主要由较小的数字组成，则 VLQ 最有效。

VLQ+Base64 可以有效地在文本格式中表示由少量数字组成的整数序列。

例如，它用于 JavaScript/CSS 源映射。

算法

例如，我们有一个数字块：[12345, -12345, 0]。

(1). VLQ 只适用于无符号整数。将符号位转移到整数的末尾。

12345 的二进制是 11000000111001。添加 0（正数）到末尾：110000001110010。

对于 -12345，取正数形式并在末尾添加 1（负数）：110000001110011。

结果是 [110000001110010, 110000001110011, 0]。

(2). 转换为 VLQ 序列。对于 Base64，我们需要一个 6 位数字块。最高位是保留位 - 它是 "连续"。

将数字分成 5 位的组：[11000 00011 10010, 11000 00011 10011, 00000]。从最低位开始输出。如果组不是当前数字的最后一个组，则设置连续位。

结果是 [110010 100011 011000 110011 100011 011000 000000]。或十进制 [50, 35, 24, 51, 35, 24, 0]。这些都是 VLQ 数字。

(3). 将数字替换为 Base64 字母表中的字母。标准字母表是 A..Za..z0..9+/。

结果是 yjYzjYA。

如何使用库

use axy\codecs\base64vlq\Encoder;

$encoder = new Encoder();

$encoder->encode([12345, -12345, 0]); // yjYzjYA
$encoder->decode('yjYzjYA'); //  [12345, 012345, 9]

$encoder->decode('Variable+Length+QuantitY'); // [-10, 13, -13349, -13 ... -12797139]

或者默认编码器可以通过以下方式获取

$encoder = Encoder::getStandardInstance();

在这种情况下，对象创建和初步计算只执行一次。

自定义选项

标准编码器使用标准选项

1. 传递符号位。
2. 6 位 VLQ 数字。
3. 标准字母表：A..Za..z0..9+/。

您可以应用您的设置

Encoder::__construct([array|string $alphabet, int $bits, bool $signed = true])

/* Custom alphabet, 4 bits, no sign transfer */
$encoder = new Encoder('My Alphabet', 3, false);

$encoder->encode([12345, 6789]); // phalllApplhhhy

自定义字母表可以指定为字符串（我的字母表）或数组（[1 => 'A', 10 => 'B', 15 => 'C', 20 => 'D']）。

异常

错误类位于命名空间 axy\codecs\base64vlq\Encoder\Errors。

• 错误
  • VLQ
    • InvalidVLQSequence
  • Base64
    • InvalidBase64
    • InvalidBase64Input

InvalidVLQSequence

$encoder->decode('Az'); // VLQ sequence is invalid: [0,51]

z 是 51（连续位 = 1）。最后一个数字的连续位必须是 0。

InvalidBase64

$encoder->decode('A*A'); // Base-64 string is invalid: "A*A"

* 不在标准 Base64 字母表中。

InvalidBase64Input

对于标准编码器，此异常不应发生。

可能由于自定义选项不正确而发生

$encoder = new Encoder('qwe', 10);
$encoder->encode([10, 20, 30]); // Number 20 is not found in Base64 alphabet

10 位有 1024 种可能性，但字母表只包含 3 个字母。