LZ77

Gzip compression

The simplest way to compress data is to use the Gzip.archive(bytes:level:hint:) convenience method.

let text:String = "hello barbie"

let archive:[UInt8] = Gzip.archive(
    bytes: [UInt8].init(text.utf8)[...],
    level: 9)

You can extract data from a gzip archive with the Gzip.extract(from:) convenience method.

let utf8:[UInt8] = try Gzip.extract(from: archive[...])

• enum Gzip
• static func archive(bytes: ArraySlice<UInt8>, level: Int, hint: Int) -> [UInt8]

  Archives data using gzip.

• static func extract(from: ArraySlice<UInt8>) throws -> [UInt8]

  Extracts gzip-compressed data.

Gzip streaming

High-volume use cases may require streaming data in and out of an archive. You can use the Gzip.Inflator and Gzip.Deflator types to do this.

You inflate gzip streams by pushing buffers to Gzip.Inflator.push(_:) while calling Gzip.Inflator.pull(_:) repeatedly to extract the decompressed data. This method returns nil if the requested amount of data is not yet available.

It is also possible to wait until you have pushed all the buffers and then call Gzip.Inflator.pull once to obtain all of the decompressed data, although in this situation it would make more sense to use Gzip.extract(from:) instead.

var inflator:Gzip.Inflator = .init()
try inflator.push(original[...])

let utf8:[UInt8] = inflator.pull()
let text:String = .init(decoding: utf8, as: Unicode.UTF8.self)

Inflator methods

• struct Inflator
• func push(ArraySlice<UInt8>) throws -> Void?

  Pushes compressed data to the inflator, returning nil once a complete gzip DEFLATE stream has been received.

• func pull(Int) -> [UInt8]?
• func pull() -> [UInt8]

Compressing data to a stream follows a similar pattern, except you need to tell Gzip.Deflator.push(_:last:) which input buffer is the final buffer in the stream.

var deflator:Gzip.Deflator = .init(level: 13, exponent: 15, hint: 128 << 10)
    deflator.push(utf8[...], last: true)

The compressed data comes out of Gzip.Deflator.pull in blocks. Depending on how you are synchronizing the input and output streams, it may also be more performant to call Gzip.Deflator.pop instead, which avoids buffer flushes but is more complicated to synchronize.

let _:Void? = System.File.Destination.open(path: "\(path).txt.gz")
{
    while let part:[UInt8] = deflator.pull()
    {
        $0.write(part)
    }
}

Deflator methods

• struct Deflator
• func push(ArraySlice<UInt8>, last: Bool)
• func pull() -> [UInt8]?

  Returns a block of gzip-compressed data from this deflator, if available. If no compressed data blocks have been completed yet, this method flushes and returns the incomplete block.

• func pop() -> [UInt8]?

  Removes and returns a complete block of gzip-compressed data from this deflator, if available.

Zlib compression

DEFLATE, or “zlib” compression is a nearly-identical form of compression to gzip, which uses the same algorithm but with a different header format. It has slightly less overhead than gzip, but is also less widely supported.

• enum LZ77

  A namespace for LZ77-related functionality.