Class: Zlib::Deflate

Inherits:

ZStream

• Object
• ZStream
• Zlib::Deflate

Defined in:

zlib.c

Overview

Zlib::Deflate is the class for compressing data. See Zlib::ZStream for more information.

Class Method Summary

• .deflate ⇒ Object

  call-seq: Zlib.deflate(string[, level]) Zlib::Deflate.deflate(string[, level]).

Instance Method Summary

• #<< ⇒ Object

  call-seq: << string.

• #deflate ⇒ Object

  call-seq: deflate(string[, flush]).

• #flush ⇒ Object

  call-seq: flush(flush).

• #initialize ⇒ Object constructor

  call-seq: Zlib::Deflate.new(level=nil, windowBits=nil, memlevel=nil, strategy=nil).

• #initialize_copy ⇒ Object

  Duplicates the deflate stream.

• #params ⇒ Object

  call-seq: params(level, strategy).

• #set_dictionary ⇒ Object

  call-seq: set_dictionary(string).

Methods inherited from ZStream

#adler, #avail_in, #avail_out, #avail_out=, #close, #closed?, #data_type, #end, #ended?, #finish, #finished?, #flush_next_in, #flush_next_out, #reset, #stream_end?, #total_in, #total_out

Constructor Details

#initialize ⇒ Object

call-seq: Zlib::Deflate.new(level=nil, windowBits=nil, memlevel=nil, strategy=nil)

Arguments

level

An Integer compression level between BEST_SPEED and BEST_COMPRESSION

windowBits

An Integer for the windowBits size. Should be in the range 8..15, larger values of this parameter result in better at the expense of memory usage.

memlevel

Specifies how much memory should be allocated for the internal compression state. Between DEF_MEM_LEVEL and MAX_MEM_LEVEL

strategy

A parameter to tune the compression algorithm. Use the DEFAULT_STRATEGY for normal data, FILTERED for data produced by a filter (or predictor), HUFFMAN_ONLY to force Huffman encoding only (no string match).

Description

Creates a new deflate stream for compression. See zlib.h for details of each argument. If an argument is nil, the default value of that argument is used.

examples

basic

f = File.new("compressed.file","w+")
#=> #<File:compressed.file>
f << Zlib::Deflate.new().deflate(File.read("big.file"))
#=> #<File:compressed.file>
f.close
#=> nil

a little more robust

compressed_file = File.open("compressed.file", "w+")
#=> #<File:compressed.file>
zd = Zlib::Deflate.new(Zlib::BEST_COMPRESSION, 15, Zlib::MAX_MEM_LEVEL, Zlib::HUFFMAN_ONLY)
#=> #<Zlib::Deflate:0x000000008610a0>
compressed_file << zd.deflate(File.read("big.file"))
#=> "\xD4z\xC6\xDE\b\xA1K\x1Ej\x8A ..."
compressed_file.close
#=> nil
zd.close
#=> nil

(while this example will work, for best optimization the flags need to be reviewed for your specific function)

# File 'zlib.c', line 1301

static VALUE
rb_deflate_initialize(int argc, VALUE *argv, VALUE obj)
{
    struct zstream *z;
    VALUE level, wbits, memlevel, strategy;
    int err;

    rb_scan_args(argc, argv, "04", &level, &wbits, &memlevel, &strategy);
    Data_Get_Struct(obj, struct zstream, z);

    err = deflateInit2(&z->stream, ARG_LEVEL(level), Z_DEFLATED,
		       ARG_WBITS(wbits), ARG_MEMLEVEL(memlevel),
		       ARG_STRATEGY(strategy));
    if (err != Z_OK) {
	raise_zlib_error(err, z->stream.msg);
    }
    ZSTREAM_READY(z);

    return obj;
}

Class Method Details

.deflate ⇒ Object

call-seq: Zlib.deflate(string[, level])

Zlib::Deflate.deflate(string[, level])

Compresses the given string. Valid values of level are NO_COMPRESSION, BEST_SPEED, BEST_COMPRESSION, DEFAULT_COMPRESSION, and an integer from 0 to 9 (the default is 6).

This method is almost equivalent to the following code:

def deflate(string, level)
  z = Zlib::Deflate.new(level)
  dst = z.deflate(string, Zlib::NO_FLUSH)
  z.close
  dst
end

See also Zlib.inflate

# File 'zlib.c', line 1381

static VALUE
rb_deflate_s_deflate(int argc, VALUE *argv, VALUE klass)
{
    struct zstream z;
    VALUE src, level, dst, args[2];
    int err, lev;

    rb_scan_args(argc, argv, "11", &src, &level);

    lev = ARG_LEVEL(level);
    StringValue(src);
    zstream_init_deflate(&z);
    err = deflateInit(&z.stream, lev);
    if (err != Z_OK) {
	raise_zlib_error(err, z.stream.msg);
    }
    ZSTREAM_READY(&z);

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

    OBJ_INFECT(dst, src);
    return dst;
}

Instance Method Details

#<< ⇒ Object

call-seq: << string

Inputs string into the deflate stream just like Zlib::Deflate#deflate, but returns the Zlib::Deflate object itself. The output from the stream is preserved in output buffer.

# File 'zlib.c', line 1477

static VALUE
rb_deflate_addstr(VALUE obj, VALUE src)
{
    OBJ_INFECT(obj, src);
    do_deflate(get_zstream(obj), src, Z_NO_FLUSH);
    return obj;
}

#deflate ⇒ Object

call-seq: deflate(string[, flush])

Arguments

string

String

flush

Integer representing a flush code. Either NO_FLUSH, SYNC_FLUSH, FULL_FLUSH, or FINISH. See zlib.h for details. Normally the parameter flush is set to Z_NO_FLUSH, which allows deflate to decide how much data to accumulate before producing output, in order to maximize compression.

Description

Inputs string into the deflate stream and returns the output from the stream. On calling this method, both the input and the output buffers of the stream are flushed.

If string is nil, this method finishes the stream, just like Zlib::ZStream#finish.

Usage

comp = Zlib.deflate(File.read("big.file"))

or

comp = Zlib.deflate(File.read("big.file"), Zlib::FULL_FLUSH)

# File 'zlib.c', line 1453

static VALUE
rb_deflate_deflate(int argc, VALUE *argv, VALUE obj)
{
    struct zstream *z = get_zstream(obj);
    VALUE src, flush, dst;

    rb_scan_args(argc, argv, "11", &src, &flush);
    OBJ_INFECT(obj, src);
    do_deflate(z, src, ARG_FLUSH(flush));
    dst = zstream_detach_buffer(z);

    OBJ_INFECT(dst, obj);
    return dst;
}

#flush ⇒ Object

call-seq: flush(flush)

This method is equivalent to deflate('', flush). If flush is omitted, SYNC_FLUSH is used as flush. This method is just provided to improve the readability of your Ruby program.

Please visit your zlib.h for a deeper detail on NO_FLUSH, SYNC_FLUSH, FULL_FLUSH, and FINISH

# File 'zlib.c', line 1497

static VALUE
rb_deflate_flush(int argc, VALUE *argv, VALUE obj)
{
    struct zstream *z = get_zstream(obj);
    VALUE v_flush, dst;
    int flush;

    rb_scan_args(argc, argv, "01", &v_flush);
    flush = FIXNUMARG(v_flush, Z_SYNC_FLUSH);
    if (flush != Z_NO_FLUSH) {  /* prevent Z_BUF_ERROR */
	zstream_run(z, (Bytef*)"", 0, flush);
    }
    dst = zstream_detach_buffer(z);

    OBJ_INFECT(dst, obj);
    return dst;
}

#initialize_copy ⇒ Object

Duplicates the deflate stream.

# File 'zlib.c', line 1327

static VALUE
rb_deflate_init_copy(VALUE self, VALUE orig)
{
    struct zstream *z1, *z2;
    int err;

    Data_Get_Struct(self, struct zstream, z1);
    z2 = get_zstream(orig);

    err = deflateCopy(&z1->stream, &z2->stream);
    if (err != Z_OK) {
	raise_zlib_error(err, 0);
    }
    z1->input = NIL_P(z2->input) ? Qnil : rb_str_dup(z2->input);
    z1->buf   = NIL_P(z2->buf)   ? Qnil : rb_str_dup(z2->buf);
    z1->buf_filled = z2->buf_filled;
    z1->flags = z2->flags;

    return self;
}

#params ⇒ Object

call-seq: params(level, strategy)

Changes the parameters of the deflate stream. See zlib.h for details. The output from the stream by changing the params is preserved in output buffer.

level

An Integer compression level between BEST_SPEED and BEST_COMPRESSION

strategy

A parameter to tune the compression algorithm. Use the DEFAULT_STRATEGY for normal data, FILTERED for data produced by a filter (or predictor), HUFFMAN_ONLY to force Huffman encoding only (no string match).

# File 'zlib.c', line 1534

static VALUE
rb_deflate_params(VALUE obj, VALUE v_level, VALUE v_strategy)
{
    struct zstream *z = get_zstream(obj);
    int level, strategy;
    int err;
    uInt n;

    level = ARG_LEVEL(v_level);
    strategy = ARG_STRATEGY(v_strategy);

    n = z->stream.avail_out;
    err = deflateParams(&z->stream, level, strategy);
    z->buf_filled += n - z->stream.avail_out;
    while (err == Z_BUF_ERROR) {
	rb_warning("deflateParams() returned Z_BUF_ERROR");
	zstream_expand_buffer(z);
	n = z->stream.avail_out;
	err = deflateParams(&z->stream, level, strategy);
	z->buf_filled += n - z->stream.avail_out;
    }
    if (err != Z_OK) {
	raise_zlib_error(err, z->stream.msg);
    }

    return Qnil;
}

#set_dictionary ⇒ Object

call-seq: set_dictionary(string)

Sets the preset dictionary and returns string. This method is available just only after Zlib::Deflate.new or Zlib::ZStream#reset method was called. See zlib.h for details.

Can raise errors of Z_STREAM_ERROR if a parameter is invalid (such as NULL dictionary) or the stream state is inconsistent, Z_DATA_ERROR if the given dictionary doesn't match the expected one (incorrect adler32 value)

# File 'zlib.c', line 1576

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

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

    return dic;
}