class Zlib::Inflate - Documentation for Ruby 3.2

# class Zlib::Inflate

Zlib:Inflate is the class for decompressing compressed data. Unlike `Zlib::Deflate`, an instance of this class is not able to duplicate (clone, dup) itself.

### Public Class Methods

inflate(string) click to toggle source
Zlib::Inflate.inflate(string)

Decompresses `string`. Raises a `Zlib::NeedDict` exception if a preset dictionary is needed for decompression.

This method is almost equivalent to the following code:

    def inflate(string)
      zstream = Zlib::Inflate.new
      buf = zstream.inflate(string)
      zstream.finish
      zstream.close
      buf
    end

See also `Zlib.deflate`

    static VALUE
    rb_inflate_s_inflate(VALUE obj, VALUE src)
    {
        struct zstream z;
        VALUE dst, args[2];
        int err;

        StringValue(src);
        zstream_init_inflate(&z);
        err = inflateInit(&z.stream);
        if (err != Z_OK) {
            raise_zlib_error(err, z.stream.msg);
        }
        ZSTREAM_READY(&z);

        args[0] = (VALUE)&z;
        args[1] = src;
        dst = rb_ensure(inflate_run, (VALUE)args, zstream_ensure_end, (VALUE)&z);

        return dst;
    }

Zlib::Inflate.new(window_bits = Zlib::MAX_WBITS) click to toggle source

Creates a new inflate stream for decompression. `window_bits` sets the size of the history buffer and can have the following values:

0

  Have inflate use the window size from the zlib header of the compressed stream.

(8..15)

  Overrides the window size of the inflate header in the compressed stream. The window size must be greater than or equal to the window size of the compressed stream.

Greater than 15

  Add 32 to window_bits to enable zlib and gzip decoding with automatic header detection, or add 16 to decode only the gzip format (a `Zlib::DataError` will be raised for a non-gzip stream).

(-8..-15)

  Enables raw deflate mode which will not generate a check value, and will not look for any check values for comparison at the end of the stream.

  This is for use with other formats that use the deflate compressed data format such as zip which provide their own check values.

## Example¶ ↑

    open "compressed.file" do |compressed_io|
      zi = Zlib::Inflate.new(Zlib::MAX_WBITS + 32)

      begin
        open "uncompressed.file", "w+" do |uncompressed_io|
          uncompressed_io << zi.inflate(compressed_io.read)
        end
      ensure
        zi.close
      end
    end

    static VALUE
    rb_inflate_initialize(int argc, VALUE *argv, VALUE obj)
    {
        struct zstream *z;
        VALUE wbits;
        int err;

        rb_scan_args(argc, argv, "01", &wbits);
        TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);

        err = inflateInit2(&z->stream, ARG_WBITS(wbits));
        if (err != Z_OK) {
            raise_zlib_error(err, z->stream.msg);
        }
        ZSTREAM_READY(z);

        return obj;
    }

### Public Instance Methods

<<(p1) click to toggle source

Same as `IO`.

    static VALUE
    rb_inflate_addstr(VALUE obj, VALUE src)
    {
        struct zstream *z = get_zstream(obj);

        if (ZSTREAM_IS_FINISHED(z)) {
            if (!NIL_P(src)) {
                StringValue(src);
                zstream_append_buffer2(z, src);
            }
        }
        else {
            do_inflate(z, src);
            if (ZSTREAM_IS_FINISHED(z)) {
                zstream_passthrough_input(z);
            }
        }

        return obj;
    }

add_dictionary(string) click to toggle source

Provide the inflate stream with a dictionary that may be required in the future. Multiple dictionaries may be provided. The inflate stream will automatically choose the correct user-provided dictionary based on the stream’s required dictionary.

    static VALUE
    rb_inflate_add_dictionary(VALUE obj, VALUE dictionary)
    {
        VALUE dictionaries = rb_ivar_get(obj, id_dictionaries);
        VALUE checksum = do_checksum(1, &dictionary, adler32);

        rb_hash_aset(dictionaries, checksum, dictionary);

        return obj;
    }

inflate(deflate_string, buffer: nil) → String click to toggle source
inflate(deflate_string, buffer: nil) { |chunk| ... } → nil

Inputs `deflate_string` into the inflate stream and returns the output from the stream. Calling this method, both the input and the output buffer of the stream are flushed. If string is `nil`, this method finishes the stream, just like `Zlib::ZStream#finish`.

If a block is given consecutive inflated chunks from the `deflate_string` are yielded to the block and `nil` is returned.

If a :buffer keyword argument is given and not nil:

- The :buffer keyword should be a `String`, and will used as the output buffer. Using this option can reuse the memory required during inflation.

- When not passing a block, the return value will be the same object as the :buffer keyword argument.

- When passing a block, the yielded chunks will be the same value as the :buffer keyword argument.

Raises a `Zlib::NeedDict` exception if a preset dictionary is needed to decompress. `Set` the dictionary by `Zlib::Inflate#set_dictionary` and then call this method again with an empty string to flush the stream:

    inflater = Zlib::Inflate.new

    begin
      out = inflater.inflate compressed
    rescue Zlib::NeedDict
      # ensure the dictionary matches the stream's required dictionary
      raise unless inflater.adler == Zlib.adler32(dictionary)

      inflater.set_dictionary dictionary
      inflater.inflate ''
    end

    # ...

    inflater.close

See also `Zlib::Inflate.new`

    static VALUE
    rb_inflate_inflate(int argc, VALUE* argv, VALUE obj)
    {
        struct zstream *z = get_zstream(obj);
        VALUE dst, src, opts, buffer = Qnil;

        if (OPTHASH_GIVEN_P(opts)) {
            VALUE buf;
            rb_get_kwargs(opts, &id_buffer, 0, 1, &buf);
            if (buf != Qundef && buf != Qnil) {
                buffer = StringValue(buf);
            }
        }
        if (buffer != Qnil) {
            if (!(ZSTREAM_REUSE_BUFFER_P(z) && z->buf == buffer)) {
                long len = RSTRING_LEN(buffer);
                if (len >= ZSTREAM_AVAIL_OUT_STEP_MAX) {
                    rb_str_modify(buffer);
                }
                else {
                    len = ZSTREAM_AVAIL_OUT_STEP_MAX - len;
                    rb_str_modify_expand(buffer, len);
                }
                rb_str_set_len(buffer, 0);
                z->flags |= ZSTREAM_REUSE_BUFFER;
                z->buf = buffer;
            }
        } else if (ZSTREAM_REUSE_BUFFER_P(z)) {
            z->flags &= ~ZSTREAM_REUSE_BUFFER;
            z->buf = Qnil;
        }
        rb_scan_args(argc, argv, "10", &src);

        if (ZSTREAM_IS_FINISHED(z)) {
            if (NIL_P(src)) {
                dst = zstream_detach_buffer(z);
            }
            else {
                StringValue(src);
                zstream_append_buffer2(z, src);
                if (ZSTREAM_REUSE_BUFFER_P(z)) {
                    dst = rb_str_resize(buffer, 0);
                } else {
                    dst = rb_str_new(0, 0);
                }
            }
        }
        else {
            do_inflate(z, src);
            dst = zstream_detach_buffer(z);
            if (ZSTREAM_IS_FINISHED(z)) {
                zstream_passthrough_input(z);
            }
        }

        return dst;
    }

set_dictionary(p1) click to toggle source

Sets the preset dictionary and returns `string`. This method is available just only after a `Zlib::NeedDict` exception was raised. See zlib.h for details.

    static VALUE
    rb_inflate_set_dictionary(VALUE obj, VALUE dic)
    {
        struct zstream *z = get_zstream(obj);
        VALUE src = dic;
        int err;

        StringValue(src);
        err = inflateSetDictionary(&z->stream,
                                   (Bytef*)RSTRING_PTR(src), RSTRING_LENINT(src));
        if (err != Z_OK) {
            raise_zlib_error(err, z->stream.msg);
        }

        return dic;
    }

sync(string) click to toggle source

Inputs `string` into the end of input buffer and skips data until a full flush point can be found. If the point is found in the buffer, this method flushes the buffer and returns false. Otherwise it returns `true` and the following data of full flush point is preserved in the buffer.

    static VALUE
    rb_inflate_sync(VALUE obj, VALUE src)
    {
        struct zstream *z = get_zstream(obj);

        StringValue(src);
        return zstream_sync(z, (Bytef*)RSTRING_PTR(src), RSTRING_LEN(src));
    }

sync_point?() click to toggle source

Quoted verbatim from original documentation:

    What is this?

`:)`

    static VALUE
    rb_inflate_sync_point_p(VALUE obj)
    {
        struct zstream *z = get_zstream(obj);
        int err;

        err = inflateSyncPoint(&z->stream);
        if (err == 1) {
            return Qtrue;
        }
        if (err != Z_OK) {
            raise_zlib_error(err, z->stream.msg);
        }
        return Qfalse;
    }