Reference

LibDeflate.Compressor — Type

Compressor(compresslevel::UInt8=0x06)

Create an object which can compress using the DEFLATE algorithm. compresslevel can be from level 1 (fast) to 12 (slow), and defaults to 6. Level 0 means no compression.

Creating this object allocates, so when compressing multiple DEFLATE blocks, keep the same compressor in memory rather than making one for each block. If the C library fails to allocate this object, an OutOfMemory error is thrown.

Warning

Compressor is not thread safe, and therefore should not be used by different tasks concurrently. Concurrent use may cause undefined behaviour.

Examples:

julia> compressor = Compressor();

julia> data = b"Hello, world!";

julia> out = zeros(UInt8, deflate_compress_bound(compressor, UInt(sizeof(data))));

julia> n = compress!(compressor, out, data);

julia> roundtrip = zeros(UInt8, sizeof(data));

julia> decompress!(Decompressor(), roundtrip, view(out, 1:n), UInt(sizeof(data)));

julia> roundtrip == data
true

source

LibDeflate.Decompressor — Type

Decompressor()

Create an object which can decompress using the DEFLATE algorithm.

Creating this object allocates, so when decompressing multiple DEFLATE blocks, keep the same decompressor in memory rather than making one for each block. If the C library fails to allocate this object, an OutOfMemory error is thrown.

Warning

Decompressor is not thread safe, and therefore should not be used by different tasks concurrently. Concurrent use may cause undefined behaviour.

Examples:

julia> decompressor = Decompressor();

julia> compressed =
       b"\x01\x0d\0\xf2\xff\x48\x65\x6c\x6c\x6f\x2c\x20\x77\x6f\x72\x6c\x64\x21";

julia> out = zeros(UInt8, 13);

julia> decompress!(decompressor, out, compressed);

julia> String(out)
"Hello, world!"

source

LibDeflate.GzipDecompressAllResult — Type

GzipDecompressAllResult

Result of successfully decompressing one or more complete gzip members, i.e. a gzip file composed of multiple, concatenated gzip data.

GzipDecompressAllResult is currently a NamedTuple, but may be changed to a named struct in a future release. The type name and properties are part of the public API; users should refer to this type as GzipDecompressAllResult instead of the NamedTuple subtype.

It has the following properties:

read::UInt: total input bytes occupied by the completed members
written::UInt: total decompressed bytes written by the completed members
members::UInt: number of completed members

Examples:

julia> combined = vcat(
           b"\x1f\x8b\x08\0\0\0\0\0\xff\0\x01\x05\0\xfa",
           b"\xff\x48\x65\x6c\x6c\x6f\x82\x89\xd1\xf7\x05\0\0\0",
           b"\x1f\x8b\x08\0\0\0\0\0\xff\0\x01\x05\0\xfa",
           b"\xff\x57\x6f\x72\x6c\x64\x47\x3e\xb6\xfb\x05\0\0\0",
       ); # gzip "Hello", then gzip "World"

julia> out = zeros(UInt8, 10);

julia> scratch = GzipDecompressAllScratch();

julia> result = gzip_decompress_all!(decompressor, out, combined, scratch);

julia> result.members === UInt(2)
true

julia> String(out)
"HelloWorld"

source

LibDeflate.GzipDecompressAllScratch — Type

GzipDecompressAllScratch()
GzipDecompressAllScratch(extra_fields, member_results)

Storage used by gzip_decompress_all! and unsafe_gzip_decompress_all!.

It has the following properties:

extra_fields::Vector{GzipExtraField}: extra fields accumulated from every completed member.
member_results::Vector{GzipDecompressResult}: one result for every completed member.

When a GzipDecompressAllScratch is passed to a function, both vectors are emptied before validation. On success, the scratch contains exactly the GzipExtraFields and GzipDecompressResults from all members. On error, it contains entries only from members completed before the failing member; the failing member contributes to neither vector.

source

LibDeflate.GzipDecompressResult — Type

GzipDecompressResult

Result of LibDeflate's gzip decompression.

It has the following properties:

written::UInt number of decompressed bytes written
read::UInt number of bytes read from input
header::GzipHeader metadata

Examples:

julia> compressed = vcat(
           b"\x1f\x8b\x08\0\0\0\0\0\xff\0\x01\x0d\0\xf2\xff\x48\x65\x6c",
           b"\x6c\x6f\x2c\x20\x77\x6f\x72\x6c\x64\x21\xe6\xc6\xe6\xeb\x0d\0\0\0",
       ); # gzip "Hello, world!"

julia> out = zeros(UInt8, 13);

julia> fields = GzipExtraField[];

julia> result = gzip_decompress!(decompressor, out, compressed, fields);

julia> result.written === UInt(13)
true

julia> String(out)
"Hello, world!"

source

LibDeflate.GzipExtraField — Type

GzipExtraField

Data structure for gzip extra data. Public properties:

tag::NTuple{2, UInt8} two-byte tag
data::UnitRange{UInt} one-based location of subfield data in the original input. The range is empty when the subfield data has length zero.

Examples:

julia> header_bytes = b"\x1f\x8b\x08\x04\0\0\0\0\0\xff"; # FEXTRA flag set

julia> extra_bytes = b"\x06\0\x41\x42\x02\0\x01\x02"; # XLEN, tag, len, data

julia> bytes = vcat(header_bytes, extra_bytes);

julia> fields = GzipExtraField[];

julia> parse_gzip_header(bytes, fields);

julia> fields[1].tag
(0x41, 0x42)

julia> bytes[fields[1].data] == b"\x01\x02"
true

source

LibDeflate.GzipHeader — Type

GzipHeader

Struct representing a gzip header. It has the following properties:

mtime::Union{Nothing, NonZeroUInt32}: modification time of the file, as expressed by a UNIX timestamp mod 2^32. A zero timestamp means that the time is unavailable, and is represented by nothing; a nonzero timestamp is stored in a NonZeroUInt32.
filename::Union{Nothing, UnitRange{UInt}}: index of the filename in the header. nothing means that the FNAME flag is absent, while an empty range means that the flag is present but the filename is empty.
comment::Union{Nothing, UnitRange{UInt}}: index of the comment in the header. nothing means that the FCOMMENT flag is absent, while an empty range means that the flag is present but the comment is empty.
extra::Union{Nothing, UnitRange{UInt}}: the indices of the gzip extra fields in the passed-in Vector{GzipExtraField} (or GzipDecompressAllScratch). Note that these scratch types are mutated when passed to a function, which invalidates this range. nothing means that the FEXTRA flag is absent, while an empty range means that the flag is present with XLEN == 0.
flags::UInt8, extra_flags::UInt8, os::UInt8: the raw bytes from the stream.

The filename and comment ranges refer to raw bytes. Their encoding is not validated; RFC 1952 specifies ISO 8859-1 (Latin-1) for these fields.

Examples:

julia> header_bytes = b"\x1f\x8b\x08\x08\0\0\0\0\0\xff";

julia> bytes = vcat(header_bytes, b"hi", b"\0"); # gzip header, filename "hi"

julia> fields = GzipExtraField[];

julia> header = parse_gzip_header(bytes, fields).header;

julia> String(bytes[header.filename])
"hi"

source

LibDeflate.NonZeroUInt32 — Type

NonZeroUInt32

Container that stores an UInt32 value, which cannot be zero. Obtain the inner value with the .x property:

Examples

julia> x = NonZeroUInt32(UInt32(3)); x.x
0x00000003

julia> NonZeroUInt32(UInt32(0))
ERROR: ArgumentError: Cannot construct a NonZeroUInt32 from zero
[...]

source

LibDeflate.ReadableMemory — Type

ReadableMemory

Struct that wraps a pointer and a length. This struct is not garbage-collector aware, so must be used with GC.@preserve. This type can be constructed from DenseArray{UInt8}, String, SubString{String} and some SubArrays. It may also be directly constructed from a Ptr and an Integer. To make custom types available as input for LibDeflate, add a constructor taking your custom type. This type implements pointer(::ReadableMemory)::Ptr{Nothing} and sizeof(::ReadableMemory)::Int.