ExCodecs.Compression.Bzip2 (ex_codecs v0.2.3)

Bzip2 compression codec (pure-Rust backend).

Options

:block_size — 1..9 (default 9)
:max_output_size — Maximum allowed decompressed size in bytes (default: 256 MiB)

Security

Do not decompress untrusted inputs without a tight :max_output_size.

Examples

iex> {:ok, compressed} = ExCodecs.encode(:bzip2, "hello world")
iex> {:ok, decompressed} = ExCodecs.decode(:bzip2, compressed)
iex> decompressed
"hello world"

iex> {:ok, compressed} = ExCodecs.encode(:bzip2, "hello world", block_size: 6)
iex> is_binary(compressed)
true

Summary

Functions

__codec_info__()

Returns the registry metadata for the Bzip2 codec.

decode(data, opts)

Decompresses Bzip2 data.

encode(data, opts)

Compresses a binary with Bzip2.

Functions

__codec_info__()

Returns the registry metadata for the Bzip2 codec.

Arguments

This function takes no arguments.

Returns

An ExCodecs.Codec.t() with these Bzip2-specific fields:

name: :bzip2 and category: :compression
module: ExCodecs.Compression.Bzip2
native?: true because compression runs in a NIF
streaming?: false because only complete payloads are supported
configurable?: true because encode/2 accepts :block_size
version: "bzip2-0.6/libbz2-rs" for the backend implementation

Raises / Exceptions

This function does not invoke the NIF and does not raise.

Examples

iex> ExCodecs.Compression.Bzip2.__codec_info__()
%ExCodecs.Codec{
  name: :bzip2,
  category: :compression,
  module: ExCodecs.Compression.Bzip2,
  native?: true,
  streaming?: false,
  configurable?: true,
  version: "bzip2-0.6/libbz2-rs"
}

decode(data, opts)

Decompresses Bzip2 data.

Arguments

data (binary()) — a complete Bzip2 stream
opts (keyword()) — optional :max_output_size (positive integer bytes, default 256 MiB)

Returns

{:ok, decompressed :: binary()} on success
{:error, %ExCodecs.Error{reason: :invalid_data}} when data is not a binary, opts is not a list, or the NIF raises an argument error
{:error, %ExCodecs.Error{reason: :invalid_options}} when :max_output_size is not a positive integer
{:error, %ExCodecs.Error{reason: :output_limit_exceeded}} when the decompressed size would exceed :max_output_size
{:error, %ExCodecs.Error{reason: :decompression_failed}} when data is corrupt, truncated, or not a Bzip2 stream
{:error, %ExCodecs.Error{reason: :nif_not_loaded}} when the native library is unavailable

Raises / Exceptions

Guard failures and ErlangError/ArgumentError exceptions from the NIF call are converted to error tuples. Unexpected exception classes may propagate.

Examples

iex> payload = "quarterly results"
iex> {:ok, compressed} = ExCodecs.Compression.Bzip2.encode(payload, [])
iex> ExCodecs.Compression.Bzip2.decode(compressed, [])
{:ok, "quarterly results"}

iex> {:error, error} = ExCodecs.Compression.Bzip2.decode("not bzip2", [])
iex> error.reason
:decompression_failed

encode(data, opts)

Compresses a binary with Bzip2.

Arguments

data (binary()) — uncompressed bytes
opts (keyword()) — options containing :block_size, an integer from 1 (100 KiB blocks) through 9 (900 KiB blocks); defaults to 9. Unknown keys are ignored.

Returns

{:ok, compressed :: binary()} containing a Bzip2 stream
{:error, %ExCodecs.Error{reason: :invalid_data}} when data is not a binary, opts is not a list, or the NIF raises an argument error
{:error, %ExCodecs.Error{reason: :invalid_options}} when :block_size is not an integer in 1..9
{:error, %ExCodecs.Error{reason: :compression_failed}} when the native compressor fails
{:error, %ExCodecs.Error{reason: :nif_not_loaded}} when the native library is unavailable

Raises / Exceptions

Guard/option validation failures and ErlangError/ArgumentError exceptions from the NIF call are converted to error tuples. Unexpected exception classes may propagate.

Examples

iex> payload = :binary.copy("daily-report,", 10)
iex> {:ok, compressed} =
...>   ExCodecs.Compression.Bzip2.encode(payload, block_size: 6)
iex> is_binary(compressed)
true
iex> ExCodecs.Compression.Bzip2.decode(compressed, [])
{:ok, payload}

iex> {:error, error} = ExCodecs.Compression.Bzip2.encode("data", block_size: 10)
iex> error.reason
:invalid_options