# # This module provides access to the [zlib library](http://zlib.net). Zlib is # designed to be a portable, free, general-purpose, legally unencumbered -- that # is, not covered by any patents -- lossless data-compression library for use on # virtually any computer hardware and operating system. # # The zlib compression library provides in-memory compression and decompression # functions, including integrity checks of the uncompressed data. # # The zlib compressed data format is described in RFC 1950, which is a wrapper # around a deflate stream which is described in RFC 1951. # # The library also supports reading and writing files in gzip (.gz) format with # an interface similar to that of IO. The gzip format is described in RFC 1952 # which is also a wrapper around a deflate stream. # # The zlib format was designed to be compact and fast for use in memory and on # communications channels. The gzip format was designed for single-file # compression on file systems, has a larger header than zlib to maintain # directory information, and uses a different, slower check method than zlib. # # See your system's zlib.h for further information about zlib # # ## Sample usage # # Using the wrapper to compress strings with default parameters is quite simple: # # require "zlib" # # data_to_compress = File.read("don_quixote.txt") # # puts "Input size: #{data_to_compress.size}" # #=> Input size: 2347740 # # data_compressed = Zlib::Deflate.deflate(data_to_compress) # # puts "Compressed size: #{data_compressed.size}" # #=> Compressed size: 887238 # # uncompressed_data = Zlib::Inflate.inflate(data_compressed) # # puts "Uncompressed data is: #{uncompressed_data}" # #=> Uncompressed data is: The Project Gutenberg EBook of Don Quixote... # # ## Class tree # # * Zlib::Deflate # * Zlib::Inflate # * Zlib::ZStream # * Zlib::Error # * Zlib::StreamEnd # * Zlib::NeedDict # * Zlib::DataError # * Zlib::StreamError # * Zlib::MemError # * Zlib::BufError # * Zlib::VersionError # * Zlib::InProgressError # # # # (if you have GZIP_SUPPORT) # * Zlib::GzipReader # * Zlib::GzipWriter # * Zlib::GzipFile # * Zlib::GzipFile::Error # * Zlib::GzipFile::LengthError # * Zlib::GzipFile::CRCError # * Zlib::GzipFile::NoFooter # module Zlib # # 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? # class ZStream public # # Returns the adler-32 checksum. # def adler: () -> Integer # # Returns bytes of data in the input buffer. Normally, returns 0. # def avail_in: () -> Integer # # Returns number of bytes of free spaces in output buffer. Because the free # space is allocated automatically, this method returns 0 normally. # def avail_out: () -> Integer # # 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. # def avail_out=: (Integer p1) -> void # # Closes the stream. All operations on the closed stream will raise an # exception. # def close: () -> void # # Returns true if the stream is closed. # def closed?: () -> bool # # Guesses the type of the data which have been inputed into the stream. The # returned value is either `BINARY`, `ASCII`, or `UNKNOWN`. # def data_type: () -> String # # Closes the stream. All operations on the closed stream will raise an # exception. # def end: () -> void # # Returns true if the stream is closed. # def ended?: () -> bool # # 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. # def finish: () -> void # # Returns true if the stream is finished. # def finished?: () -> bool # # def flush_next_in: () -> String # # 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. # def flush_next_out: () -> String? # # Resets and initializes the stream. All data in both input and output buffer # are discarded. # def reset: () -> void # # Returns true if the stream is finished. # def stream_end?: () -> bool # # Returns the total bytes of the input data to the stream. FIXME # def total_in: () -> Integer # # Returns the total bytes of the output data from the stream. FIXME # def total_out: () -> Integer end end