Class: Zlib::ZStream

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

An instance of Zlib::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 Zlib::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 Zlib::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 Zlib::Inflate and Zlib::Deflate.

The higher level methods are listed below.

total_in
total_out
data_type
adler
reset
finish
finished?
close
closed?

Methods

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

Public Instance methods

adler()

Returns the adler-32 checksum.

avail_in()

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

avail_out()

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

avail_out=(p1)

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.

close()

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

closed?()

Returns true if the stream is closed.

data_type()

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

end()

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

ended?()

Returns true if the stream is closed.

finish()

Finishes the stream and flushes output buffer. See Zlib::Deflate#finish and Zlib::Inflate#finish for details of this behavior.