3.11. Data Compression Functions

This section documents functions for compressing and uncompressing data.

3.11.1. compress()

Synopsis

Performs zlib-based "deflate" data compression (RFC 1951) and returns a binary object of the compressed data. The optional second argument specifies the compression level; if no second argument is given, then a tradeoff between speed and compression size is taken (default: 6). Note that strings are compressed without the trailing null character.

Usage
compress(string | binary, [level])
Example
$bin = compress("hello");

Table 3.288. Arguments and Return Values for compress()

Argument Type

Return Type

Description

string | binary, [level]

Binary

Compresses the input data and returns a binary object. The optional level argument should be an integer between 1 and 9, 9 meaning the highest compression level. If this argument is not present then a default value of 6 is assumed.


Table 3.289. Exceptions Thrown by compress()

err

desc

ZLIB-LEVEL-ERROR

the compression level is invalid (must be between 1 - 9 inclusive).

ZLIB-ERROR

zlib returned an error while processing.


3.11.2. gunzip_to_binary()

Synopsis

Uncompresses gzipped data using zlib functions and returns a binary object of the uncompressed data.

Usage
gunzip_to_binary(binary)
Example
$bin = gunzip_to_binary($data);

Table 3.290. Arguments and Return Values for gunzip_to_binary()

Argument Type

Return Type

Description

binary

Binary

Uncompresses the input data and returns a binary object.


Table 3.291. Exceptions Thrown by gunzip_to_binary()

err

desc

ZLIB-ERROR

zlib returned an error while processing.


3.11.3. gunzip_to_string()

Synopsis

Uncompresses gzipped data using zlib functions and returns a string of the uncompressed data. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.

Usage
gunzip_to_string(binary, [encoding])
Example
$str = gunzip_to_string($gzipped_string);

Table 3.292. Arguments and Return Values for gunzip_to_string()

Argument Type

Return Type

Description

binary, [encoding]

Binary

Uncompresses the input data and returns a string. The optional encoding argument may be passed to specify the encoding of the string.


Table 3.293. Exceptions Thrown by gunzip_to_string()

err

desc

ZLIB-ERROR

zlib returned an error while processing.


3.11.4. gzip()

Synopsis

Performs zlib-based "gzip" data compression (RFC 1952) and returns a binary object of the compressed data. The optional second argument specifies the compression level; if no second argument is given, then a tradeoff between speed and compression size is taken (default: 6). Note that strings are compressed without the trailing null character.

Usage
gzip(string | binary, [level])
Example
$bin = gzip($data);

Table 3.294. Arguments and Return Values for gzip()

Argument Type

Return Type

Description

string | binary, [level]

Binary

Compresses the input data and returns a binary object of the gzipped data. The optional level argument should be an integer between 1 and 9, 9 meaning the highest compression level. If this argument is not present then a default value of 6 is assumed.


Table 3.295. Exceptions Thrown by gzip()

err

desc

ZLIB-LEVEL-ERROR

the compression level is invalid (must be between 1 - 9 inclusive).

ZLIB-ERROR

zlib returned an error while processing.


3.11.5. bunzip2_to_binary()

Synopsis

Uncompresses data compressed with bzip2 and returns a binary object of the uncompressed data.

Usage
bunzip2_to_binary(binary)
Example
$bin = bunzip2_to_binary($data);

Table 3.296. Arguments and Return Values for bunzip2_to_binary()

Argument Type

Return Type

Description

binary

Binary

Uncompresses the input data and returns a binary object.


Table 3.297. Exceptions Thrown by bunzip2_to_binary()

err

desc

BZIP2-DECOMPRESS-ERROR

libbz2 returned an error while processing.


3.11.6. bunzip2_to_string()

Synopsis

Uncompresses data compressed with bzip2 and returns a string of the uncompressed data. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.

Usage
bunzip2_to_string(binary, [encoding])
Example
$str = bunzip2_to_string($gzipped_string);

Table 3.298. Arguments and Return Values for bunzip2_to_string()

Argument Type

Return Type

Description

binary, [encoding]

Binary

Uncompresses the input data and returns a string. The optional encoding argument may be passed to specify the encoding of the string.


Table 3.299. Exceptions Thrown by bunzip2_to_string()

err

desc

BZIP2-DECOMPRESS-ERROR

libbz2 returned an error while processing.


3.11.7. bzip2()

Synopsis

Performs "bzip2" data compression and returns a binary object of the compressed data. The optional second argument specifies the compression buffer size as an argument from 1 - 9; if no second argument is given, then the maximum buffer size is assumed (default: 9). Note that strings are compressed without the trailing null character.

Usage
bzip2(string | binary, [level])
Example
$bin = bzip2($data);

Table 3.300. Arguments and Return Values for bzip2()

Argument Type

Return Type

Description

string | binary, [level]

Binary

Compresses the input data and returns a binary object of the bzip2 data. The optional level argument should be an integer between 1 and 9, 9 meaning the largest compression buffer size. If this argument is not present then a default value of 9 is assumed.


Table 3.301. Exceptions Thrown by bzip2()

err

desc

BZLIB2-LEVEL-ERROR

the compression level is invalid (must be between 1 - 9 inclusive).

BZLIB2-COMPRESSION-ERROR

zlib returned an error while processing.


3.11.8. uncompress_to_binary()

Synopsis

Uncompresses data using zlib functions and returns a binary object of the uncompressed data.

Usage
uncompress_to_binary(binary)
Example
$bin = uncompress_to_binary($compressed_data);

Table 3.302. Arguments and Return Values for uncompress_to_binary()

Argument Type

Return Type

Description

binary

Binary

Uncompresses the input data and returns a binary object.


Table 3.303. Exceptions Thrown by uncompress_to_binary()

err

desc

ZLIB-ERROR

zlib returned an error while processing.


3.11.9. uncompress_to_string()

Synopsis

Uncompresses data using zlib functions and returns a string of the uncompressed data. An optional second string argument may be passed to give the character encoding of the string; if not present, the default character encoding for the process is assumed.

Usage
uncompress_to_string(binary, [encoding])
Example
$str = uncompress_to_string($compressed_data);

Table 3.304. Arguments and Return Values for uncompress_to_string()

Argument Type

Return Type

Description

binary, [encoding]

Binary

Uncompresses the input data and returns a string. The optional encoding argument may be passed to specify the encoding of the string.


Table 3.305. Exceptions Thrown by uncompress_to_string()

err

desc

ZLIB-ERROR

zlib returned an error while processing.