Difference between revisions of "Lua API:Bz2"

From The Powder Toy
Jump to: navigation, search
(Add bzip2 api)
 
(98.0 update: Replace with LBPHacker's version)
 
Line 1: Line 1:
−
The bz2 api provides access to our bzip2 library. It can be used for compressing and decompressing blocks of data, such as tpt saves.
+
The <code>bz2</code> API provides access to the bzip2 library TPT bundles. It can be used for compressing and decompressing blocks of data, such as TPT saves.
 +
 
 +
Only one-shot functionality is exposed because streaming functionality is only useful for tasks that are beyond the scope of this API.
 +
 
 +
Unless stated otherwise, all functions raise errors if supplied with parameters that disagree with their descriptions.
 +
 
 +
__TOC__
  
 
== Methods ==
 
== Methods ==
  
 
=== bz2.compress ===
 
=== bz2.compress ===
−
bz2.compress(sourceData, maxSize)
 
−
Accepts source data and returns a string containing the compressed data. maxSize controls the maximum amount of memory to use while compressing the sourceData, and can be 0 to allow unlimited memory.
 
  
−
On success, returns 1 argument - the compressed data
+
Compress data with bzip2 at compression level 9.
  
−
On failure, returns 3 arguments - nil, error code, error string. Error code will be one of the constants documented below
+
<pre>compressedData, errCode, errStr = bz2.compress(data, [maxSize])</pre>
 +
* <code>data</code>: string, the data to be compressed
 +
* <code>maxSize</code>: number, upper limit on the length of <code>compressedData</code>; defaults to <code>0</code>, which means no limit
 +
* <code>compressedData</code>: string, the compressed data, or <code>nil</code> on error
 +
* <code>errCode</code>: <code>nil</code>, or one of the following values on error:
 +
** <code>bz2.COMPRESS_NOMEM</code>: out of memory, TPT will probably crash soon
 +
** <code>bz2.COMPRESS_LIMIT</code>: the length of <code>compressedData</code> would exceed <code>maxSize</code>
 +
* <code>errStr</code>: <code>nil</code>, or a human-friendly string that explains the error
  
 
=== bz2.decompress ===
 
=== bz2.decompress ===
−
bz2.compress(sourceData, maxSize)
 
−
Accepts source data and returns a string containing the decompressed data. maxSize controls the maximum amount of memory to use while decompressing the sourceData, and can be 0 to allow unlimited memory.
 
−
 
−
On success, returns 1 argument - the decompressed data
 
−
 
−
On failure, returns 3 arguments - nil, error code, error string. Error code will be one of the constants documented below
 
  
−
== Constants ==
+
Decompress bzip2-compressed data.
  
−
; compressOk
+
<pre>data, errCode, errStr = bz2.decompress(compressedData, [maxSize])</pre>
−
Compression OK
+
* <code>compressedData</code>: string, the compressed data
−
; compressNomem
+
* <code>maxSize</code>: number, upper limit on the length of <code>data</code>; defaults to <code>0</code>, which means no limit
−
Compression failed, ran out of memory
+
* <code>data</code>: string, the original data, or <code>nil</code> on error
−
; compressLimit
+
* <code>errCode</code>: <code>nil</code>, or one of the following values on error:
−
Compression failed, maxSize limit exceeded
+
** <code>bz2.DECOMPRESS_NOMEM</code>: out of memory, TPT will probably crash soon
−
; decompressOk
+
** <code>bz2.DECOMPRESS_LIMIT</code>: the length of <code>data</code> would exceed <code>maxSize</code>
−
Decompression OK
+
** <code>bz2.DECOMPRESS_TYPE</code>: <code>compressedData</code> is not bzip2-compressed data
−
; decompressNomem
+
** <code>bz2.DECOMPRESS_BAD</code>: <code>compressedData</code> is otherwise corrupt
−
Decompression failed, ran out of memory
+
** <code>bz2.DECOMPRESS_EOF</code>: <code>compressedData</code> contains data beyond the end of the bzip2 stream
−
; decompressLimit
+
* <code>errStr</code>: <code>nil</code>, or a human-friendly string that explains the error
−
Decompression failed, maxSize limit exceeded
 
−
; decompressType
 
−
Decompression failed, sourceData does not have bzip2 header and is likely not bzip2 data
 
−
; decompressBad
 
−
Decompression failed, sourceData is not valid bzip2 data
 
−
; decompressEof
 

Latest revision as of 03:04, 13 March 2024

The bz2 API provides access to the bzip2 library TPT bundles. It can be used for compressing and decompressing blocks of data, such as TPT saves.

Only one-shot functionality is exposed because streaming functionality is only useful for tasks that are beyond the scope of this API.

Unless stated otherwise, all functions raise errors if supplied with parameters that disagree with their descriptions.

Methods

bz2.compress

Compress data with bzip2 at compression level 9. 

compressedData, errCode, errStr = bz2.compress(data, [maxSize])
  • data: string, the data to be compressed
  • maxSize: number, upper limit on the length of compressedData; defaults to 0, which means no limit
  • compressedData: string, the compressed data, or nil on error
  • errCode: nil, or one of the following values on error:
    • bz2.COMPRESS_NOMEM: out of memory, TPT will probably crash soon
    • bz2.COMPRESS_LIMIT: the length of compressedData would exceed maxSize
  • errStr: nil, or a human-friendly string that explains the error

bz2.decompress

Decompress bzip2-compressed data. 

data, errCode, errStr = bz2.decompress(compressedData, [maxSize])
  • compressedData: string, the compressed data
  • maxSize: number, upper limit on the length of data; defaults to 0, which means no limit
  • data: string, the original data, or nil on error
  • errCode: nil, or one of the following values on error:
    • bz2.DECOMPRESS_NOMEM: out of memory, TPT will probably crash soon
    • bz2.DECOMPRESS_LIMIT: the length of data would exceed maxSize
    • bz2.DECOMPRESS_TYPE: compressedData is not bzip2-compressed data
    • bz2.DECOMPRESS_BAD: compressedData is otherwise corrupt
    • bz2.DECOMPRESS_EOF: compressedData contains data beyond the end of the bzip2 stream
  • errStr: nil, or a human-friendly string that explains the error
Retrieved from "https://powdertoy.co.uk/Wiki/index.php?title=Lua_API:Bz2&oldid=9187"