123456789_123456789_123456789_123456789_123456789_

Class: Zlib::Deflate

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ZStream
Instance Chain:
self, ZStream
Inherits: Zlib::ZStream
Defined in: ext/zlib/zlib.c,
ext/zlib/zlib.c

Overview

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

Class Method Summary

Instance Attribute Summary

ZStream - Inherited

#avail_out

Returns number of bytes of free spaces in output buffer.
#avail_out=

Allocates size bytes of free space in the output buffer.
#closed?

Alias for ZStream#ended?.
#ended?

Returns true if the stream is closed.
#finished?

Returns true if the stream is finished.
#stream_end?

Alias for ZStream#finished?.

Instance Method Summary

ZStream - Inherited

#adler

Returns the adler-32 checksum.
#avail_in

Returns bytes of data in the input buffer.
#close

Alias for ZStream#end.
#data_type

Guesses the type of the data which have been inputed into the stream.
#end

Closes the stream.
#finish

Finishes the stream and flushes output buffer.
#flush_next_in,
#flush_next_out

Flushes output buffer and returns all data in that buffer.
#reset

Resets and initializes the stream.
#total_in

Returns the total bytes of the input data to the stream.
#total_out

Returns the total bytes of the output data from the stream.

Constructor Details

.new(level = DEFAULT_COMPRESSION, window_bits = MAX_WBITS, mem_level = DEF_MEM_LEVEL, strategy = DEFAULT_STRATEGY)

Creates a new deflate stream for compression. If a given argument is nil, the default value of that argument is used.

The level sets the compression level for the deflate stream between 0 (no compression) and 9 (best compression). The following constants have been defined to make code more readable:

See www.zlib.net/manual.html#Constants for further information.

The window_bits sets the size of the history buffer and should be between 8 and 15. Larger values of this parameter result in better compression at the expense of memory usage.

The mem_level specifies how much memory should be allocated for the internal compression state. 1 uses minimum memory but is slow and reduces compression ratio while 9 uses maximum memory for optimal speed. The default value is 8. Two constants are defined:

The strategy sets the deflate compression strategy. The following strategies are available:

Zlib::DEFAULT_STRATEGY

For normal data

Zlib::FILTERED

For data produced by a filter or predictor

Zlib::FIXED

Prevents dynamic Huffman codes

Zlib::HUFFMAN_ONLY

Prevents string matching

Zlib::RLE

Designed for better compression of PNG image data

See the constants for further description.

Examples

Basic
open "compressed.file", "w+" do |io|
  io << Zlib::Deflate.new.deflate(File.read("big.file"))
end
Custom compression
open "compressed.file", "w+" do |compressed_io|
  deflate = Zlib::Deflate.new(Zlib::BEST_COMPRESSION,
                              Zlib::MAX_WBITS,
                              Zlib::MAX_MEM_LEVEL,
                              Zlib::HUFFMAN_ONLY)

  begin
    open "big.file" do |big_io|
      until big_io.eof? do
        compressed_io << zd.deflate(big_io.read(16384))
      end
    end
  ensure
    deflate.close
  end
end

While this example will work, for best optimization review the flags for your specific time, memory usage and output space requirements.

[ GitHub ] 

  


# File 'ext/zlib/zlib.c', line 1507



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);
    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, 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



  

    

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

  



  

    

Compresses the given string. Valid values of level are NO_COMPRESSION, BEST_SPEED, BEST_COMPRESSION, DEFAULT_COMPRESSION, or an integer from 0 to 9.



This method is almost equivalent to the following code:



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



See also Zlib.inflate


  





  


  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1587



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



  

    #<<(src)  
  



  

    

Same as IO.


  



  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1674



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(string, flush = Zlib::NO_FLUSH)  ⇒ String 
      #deflate(string, flush = Zlib::NO_FLUSH) {|chunk| ... } ⇒ nil 
    

  



  

    

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 ZStream#finish.



If a block is given consecutive deflated chunks from the string are yielded to the block and nil is returned.



The #flush parameter specifies the flush mode.  The following constants may be used:


Zlib::NO_FLUSH



The default


Zlib::SYNC_FLUSH



Flushes the output to a byte boundary


Zlib::FULL_FLUSH



SYNC_FLUSH + resets the compression state


Zlib::FINISH



Pending input is processed, pending output is flushed.





See the constants for further description.


  





  


  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1652



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

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

    return zstream_detach_buffer(z);
}


  








  

    

      #flush(flush = Zlib::SYNC_FLUSH)  ⇒ String 
      #flush(flush = Zlib::SYNC_FLUSH) {|chunk| ... } ⇒ nil 
    

  



  

    

This method is equivalent to deflate('', flush). This method is just provided to improve the readability of your Ruby program.  If a block is given chunks of deflate output are yielded to the block until the buffer is flushed.



See #deflate for detail on the flush constants NO_FLUSH, SYNC_FLUSH, FULL_FLUSH and FINISH.


  





  


  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1697



static VALUE
rb_deflate_flush(int argc, VALUE *argv, VALUE obj)
{
    struct zstream *z = get_zstream(obj);
    VALUE v_flush;
    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);
    }

    return zstream_detach_buffer(z);
}


  








  

    #initialize_copy(orig)  
  



  

    

Duplicates the deflate stream.


  



  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1533



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

    TypedData_Get_Struct(self, struct zstream, &zstream_data_type, z1);
    z2 = get_zstream(orig);

    if (z1 == z2) return self;
    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->flags = z2->flags;

    return self;
}


  








  

    #params(level, strategy)    



  

    

Changes the parameters of the deflate stream to allow changes between different types of data that require different types of compression.  Any unprocessed data is flushed before changing the params.



See .new for a description of level and strategy.


  



  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1725



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;
    long filled;

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

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

    return Qnil;
}


  








  

    #set_dictionary(string)    



  

    

Sets the preset dictionary and returns string. This method is available just only after .new or 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)


  



  [ GitHub ]


  

  


# File 'ext/zlib/zlib.c', line 1770



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;
}