123456789_123456789_123456789_123456789_123456789_

Class: Zlib::ZStream

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Deflate, Inflate
Inherits: Object
Defined in: ext/zlib/zlib.c,
ext/zlib/zlib.c

Overview

ZStream is the abstract class for the stream which handles the compressed data. The operations are defined in the subclasses: Deflate for compression, and Inflate for decompression.

An instance of ZStream has one stream (struct zstream in the source) and two variable-length buffers which associated to the input (next_in) of the stream and the output (next_out) of the stream. In this document, “input buffer” means the buffer for input, and “output buffer” means the buffer for output.

Data input into an instance of ZStream are temporally stored into the end of input buffer, and then data in input buffer are processed from the beginning of the buffer until no more output from the stream is produced (i.e. until avail_out > 0 after processing). During processing, output buffer is allocated and expanded automatically to hold all output data.

Some particular instance methods consume the data in output buffer and return them as a String.

Here is an ascii art for describing above:

+================ an instance of Zlib::ZStream ================+
||                                                            ||
||     --------          -------          --------      ||
||  +--| output |<---------|zstream|<---------| input  |<--+  ||
||  |  | buffer |  next_out-------next_in   | buffer |   |  ||
||  |  --------                             --------   |  ||
||  |                                                      |  ||
===|======================================================|===
    |                                                      |
    v                                                      |
"output data"                                         "input data"

If an error occurs during processing input buffer, an exception which is a subclass of Error is raised. At that time, both input and output buffer keep their conditions at the time when the error occurs.

Method Catalogue

Many of the methods in this class are fairly low-level and unlikely to be of interest to users. In fact, users are unlikely to use this class directly; rather they will be interested in Inflate and Deflate.

The higher level methods are listed below.

Instance Attribute Summary

Instance Method Summary

Instance Attribute Details

#avail_out (rw)

Returns number of bytes of free spaces in output buffer. Because the free space is allocated automatically, this method returns 0 normally.

[ GitHub ] 

  


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



static VALUE
rb_zstream_avail_out(VALUE obj)
{
    struct zstream *z;
    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
    return rb_uint2inum(z->stream.avail_out);
}


  








  

    #avail_out=(size)   (rw)
  



  

    

Allocates size bytes of free space in the output buffer. If there are more than size bytes already in the buffer, the buffer is truncated. Because free space is allocated automatically, you usually don’t need to use this method.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_set_avail_out(VALUE obj, VALUE size)
{
    struct zstream *z = get_zstream(obj);

    zstream_expand_buffer_into(z, FIX2INT(size));
    return size;
}


  








  

    #closed?  ⇒ Boolean  (readonly)
  



  

    

Alias for #ended?.


  





  








  

    #ended?   (readonly)
    Also known as: #closed?
  



  

    

Returns true if the stream is closed.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_closed_p(VALUE obj)
{
    struct zstream *z;
    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
    return ZSTREAM_IS_READY(z) ? Qfalse : Qtrue;
}


  








  

    #finished?  ⇒ Boolean  (readonly)
    Also known as: #stream_end?
  



  

    

Returns true if the stream is finished.


  





  


  [ GitHub ]


  

  


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



static VALUE
rb_zstream_finished_p(VALUE obj)
{
    return ZSTREAM_IS_FINISHED(get_zstream(obj)) ? Qtrue : Qfalse;
}


  








  

    #stream_end?  ⇒ Boolean  (readonly)
  



  

    

Alias for #finished?.


  





  







Instance Method Details



  

    #adler  
  



  

    

Returns the adler-32 checksum.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_adler(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.adler);
}


  








  

    #avail_in  
  



  

    

Returns bytes of data in the input buffer. Normally, returns 0.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_avail_in(VALUE obj)
{
    struct zstream *z;
    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
    return INT2FIX(NIL_P(z->input) ? 0 : (int)(RSTRING_LEN(z->input)));
}


  








  

    #close  
  



  

    

Alias for #end.


  









  

    #data_type  
  



  

    

Guesses the type of the data which have been inputed into the stream. The returned value is either BINARY, ASCII, or UNKNOWN.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_data_type(VALUE obj)
{
    return INT2FIX(get_zstream(obj)->stream.data_type);
}


  








  

    #end  
    Also known as: #close
  



  

    

Closes the stream. All operations on the closed stream will raise an exception.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_end(VALUE obj)
{
    zstream_end(get_zstream(obj));
    return Qnil;
}


  








  

    

      #finish  ⇒ String 
      #finish {|chunk| ... } ⇒ nil 
    

  



  

    

Finishes the stream and flushes output buffer.  If a block is given each chunk is yielded to the block until the input buffer has been flushed to the output buffer.


  





  


  [ GitHub ]


  

  


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



static VALUE
rb_zstream_finish(VALUE obj)
{
    struct zstream *z = get_zstream(obj);

    zstream_run(z, (Bytef*)"", 0, Z_FINISH);

    return zstream_detach_buffer(z);
}


  








  

    #flush_next_in  ⇒ input   



  

    
  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_flush_next_in(VALUE obj)
{
    struct zstream *z;
    VALUE dst;

    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
    dst = zstream_detach_input(z);
    OBJ_INFECT(dst, obj);
    return dst;
}


  








  

    

      #flush_next_out  ⇒ String 
      #flush_next_out {|chunk| ... } ⇒ nil 
    

  



  

    

Flushes output buffer and returns all data in that buffer.  If a block is given each chunk is yielded to the block until the current output buffer has been flushed.


  





  


  [ GitHub ]


  

  


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



static VALUE
rb_zstream_flush_next_out(VALUE obj)
{
    struct zstream *z;

    TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);

    return zstream_detach_buffer(z);
}


  








  

    #reset  
  



  

    

Resets and initializes the stream. All data in both input and output buffer are discarded.


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_reset(VALUE obj)
{
    zstream_reset(get_zstream(obj));
    return Qnil;
}


  








  

    #total_in  
  



  

    

Returns the total bytes of the input data to the stream.  FIXME


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_total_in(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.total_in);
}


  








  

    #total_out  
  



  

    

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


  



  [ GitHub ]


  

  


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



static VALUE
rb_zstream_total_out(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.total_out);
}