lzma
The lzma library, compresses and decompresses strings in the format used by util.Compress.
The format is the 5 bytes of lzma properties, the decompressed size as 8 bytes in little endian and the raw lzma stream.
When HolyLib is installed and the call is made from a coroutine, the work is done on a separate thread with util.AsyncCompress / util.AsyncDecompress and the coroutine waits for the result, otherwise the call is synchronous.
Fields
| Name | Type | Description |
|---|---|---|
PROPS_SIZE | integer | The size of the lzma properties in bytes. = 5 |
Functions
lzma.compress | Compresses a string into lzma data. |
lzma.decompress | Decompresses lzma data. |
lzma.size | Returns the decompressed size stored in the header of the lzma data. |
lzma.validate | Checks if the string starts with a valid lzma header, the same check HolyLib and the engine do before decompressing. |
#lzma.compress
async function lzma.compress(data: string, level?: integer, dictionary_size?: integer): stringCompresses a string into lzma data.
Runs on a separate thread when HolyLib is installed and the call is made from a coroutine, synchronously with util.Compress otherwise.
Throws an error if the compression fails.
| Name | Type | Description |
|---|---|---|
data | string | The string to compress. |
leveloptional | integer | The compression level from 0 to 9, 5 by default, only used by HolyLib. |
dictionary_sizeoptional | integer | The dictionary size in bytes, 65536 by default, only used by HolyLib. |
| Type | Name | Description |
|---|---|---|
string | compressed_data | The compressed data. |
#lzma.decompress
async function lzma.decompress(compressed_data: string, ratio?: number): stringDecompresses lzma data.
Runs on a separate thread when HolyLib is installed and the call is made from a coroutine, synchronously with util.Decompress otherwise.
ratio protects against decompression bombs, the data is rejected if decompressed_size // compressed_size is greater than 1 / ( 1 - ratio ), 0.98 allows less than 50 times the compressed size ( floating point makes the limit 49.99... ), nil or 1 and more disables the check.
Throws an error on an invalid header ( see lzma.validate ), malformed or truncated data, a ratio of 0 or less, or if the ratio is exceeded; call via pcall() when processing untrusted input.
| Name | Type | Description |
|---|---|---|
compressed_data | string | The lzma data to decompress. |
ratiooptional | number | The maximum allowed compression ratio, no limit by default. |
| Type | Name | Description |
|---|---|---|
string | decompressed_data | The decompressed string. |
#lzma.size
function lzma.size(str: string): integerReturns the decompressed size stored in the header of the lzma data.
Only the low 32 bits of the 64-bit size field are read.
Throws an error if the data is shorter than 9 bytes.
| Name | Type | Description |
|---|---|---|
str | string | The lzma data. |
| Type | Name | Description |
|---|---|---|
integer | size | The decompressed size in bytes. |
#lzma.validate
function lzma.validate(compressed_data: string): boolean, nil | stringChecks if the string starts with a valid lzma header, the same check HolyLib and the engine do before decompressing.
The data must be longer than the 13 bytes of the header, the properties byte must be below 225 ( ( pb * 5 + lp ) * 9 + lc ) and the dictionary size must be at least 4096 bytes.
The stream itself is not checked, so lzma.decompress can still fail on a valid header.
| Name | Type | Description |
|---|---|---|
compressed_data | string | The lzma data. |
| Type | Name | Description |
|---|---|---|
boolean | is_valid | true if the header is valid, false otherwise. |
nil | string | err_msg | The reason why the header is invalid. |