Class: Zlib::ZStream
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
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
-
#avail_out
rw
Returns number of bytes of free spaces in output buffer.
-
#avail_out=(size)
rw
Allocates
size
bytes of free space in the output buffer. -
#closed? ⇒ Boolean
readonly
Alias for #ended?.
-
#ended?
(also: #closed?)
readonly
Returns true if the stream is closed.
-
#finished? ⇒ Boolean
(also: #stream_end?)
readonly
Returns true if the stream is finished.
-
#stream_end? ⇒ Boolean
readonly
Alias for #finished?.
Instance Method Summary
-
#adler
Returns the adler-32 checksum.
-
#avail_in
Returns bytes of data in the input buffer.
-
#close
Alias for #end.
-
#data_type
Guesses the type of the data which have been inputed into the stream.
-
#end
(also: #close)
Closes the stream.
-
#finish ⇒ String
Finishes the stream and flushes output buffer.
- #flush_next_in ⇒ input
-
#flush_next_out ⇒ String
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.
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.
#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.
#closed? ⇒ Boolean
(readonly)
Alias for #ended?.
#ended? (readonly) Also known as: #closed?
Returns true if the stream is closed.
#finished? ⇒ Boolean
(readonly)
Also known as: #stream_end?
Returns true if the stream is finished.
#stream_end? ⇒ Boolean
(readonly)
Alias for #finished?.
Instance Method Details
#adler
Returns the adler-32 checksum.
#avail_in
Returns bytes of data in the input buffer. Normally, returns 0.
#close
Alias for #end.
#data_type
#end Also known as: #close
Closes the stream. All operations on the closed stream will raise an exception.
#finish ⇒ String
#finish {|chunk| ... } ⇒ nil
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.
#flush_next_in ⇒ input
#flush_next_out ⇒ String
#flush_next_out {|chunk| ... } ⇒ nil
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.
#reset
Resets and initializes the stream. All data in both input and output buffer are discarded.
#total_in
Returns the total bytes of the input data to the stream. FIXME
#total_out
Returns the total bytes of the output data from the stream. FIXME