Ruby/zlib is an extension library to use zlib from Ruby. Ruby/zlib also provides the features for accessing gzipped files.
You can modify or redistribute Ruby/zlib in the same manner of Ruby interpreter. The latest version of Ruby/zlib would be found at <URL:http://www.blue.sky.or.jp/>.
Any comments and suggestions are always welcome. Please send them to ruby-list ML, ruby-ext ML, ruby-talk ML, or the author's mail address <URL:mailto:katsu@blue.sky.or.jp>.
This document is experimental and broken English version. If you find some mistakes or strange expressions (including kidding or unnatural ones) in this document, please let me know for my study.
Zlib is the module which provides the other features in zlib C library. See zlib.h for detail of each module function.
Zlib.version
Returns the string which represents the version of zlib library.
Zlib.adlar32([string[, adlar]])
Calculates Alder-32 checksum for string, and returns updated value of alder. If string is omitted, it returns the Adler-32 initial value. If alder is omitted, it assumes that the initial value is given to alder.
Zlib.crc32([string[, crc]])
Calculates CRC checksum for string, and returns updated value of crc. If string is omitted, it returns the CRC initial value. crc is omitted, it assumes that the initial value is given to crc.
Zlib.crc_table
Returns the table for calculating CRC checksum as an array.
Zlib::VERSION
The string which represents the version of zlib.h.
Zlib::BINARY
Zlib::ASCII
Zlib::UNKNOWN
The integers representing data types which Zlib::ZStream#data_type method returns.
Zlib::NO_COMPRESSION
Zlib::BEST_SPEED
Zlib::BEST_COMPRESSION
Zlib::DEFAULT_COMPRESSION
The integers representing compression levels which are an argument for Zlib::Deflate.new, Zlib::Deflate#deflate, and so on.
Zlib::FILTERED
Zlib::HUFFMAN_ONLY
Zlib::DEFAULT_STRATEGY
The integers representing compression methods which are an argument for Zlib::Deflate.new and Zlib::Deflate#params.
Zlib::DEF_MEM_LEVEL
Zlib::MAX_MEM_LEVEL
The integers representing memory levels which are an argument for Zlib::Deflate.new, Zlib::Deflate#params, and so on.
Zlib::MAX_WBITS
The default value of windowBits which is an argument for Zlib::Deflate.new and Zlib::Inflate.new.
Zlib::NO_FLUSH
Zlib::SYNC_FLUSH
Zlib::FULL_FLUSH
Zlib::FINISH
The integers to control the output of the deflate stream, which are an argument for Zlib::Deflate#deflate and so on.
Zlib::OS_CODE
Zlib::OS_MSDOS
Zlib::OS_AMIGA
Zlib::OS_VMS
Zlib::OS_UNIX
Zlib::OS_ATARI
Zlib::OS_OS
Zlib::OS_MACOS
Zlib::OS_TOPS
Zlib::OS_WIN
The return values of Zlib::GzipFile#os_code method.
The superclass for all excpetions raised by Ruby/zlib.
The following exceptions are defined as subclasses of Zlib::Error. These exceptions are raised when zlib library functions return with an error status.
The abstruct class for the stream which handles the compressed data. The operations are defined in the subclasses, Zlib::Deflate for compression, and Zlib::Inflate for decpmpression.
An instance of Zlib::ZStream has one stream (struct zstream) 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 inputed 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 paticular 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 is occured during processing input buffer, an exception which is a subclass of Zlib::Error is raised. At that time, both input and output buffer keeps their conditions at the time when the error is occured.
Zlib::ZStream.new
See Zlib::Deflate.new and Zlib::Inflate.new.
Zlib::ZStream#avail_in
Returns bytes of data in input buffer. Normally, returns 0.
Zlib::ZStream#avail_out
Returns bytes of free spaces in output buffer. Because the free spaces are allocated automatically, this method returns 0 normally.
Zlib::ZStream#avail_out = size
Allocates free spaces of size bytes in output buffer. If there are more than size bytes spaces in the buffer, the buffer is truncated. Because the free spaces are allocated automatically, you usually need not to use this method.
Zlib::ZStream#flush_next_in
Flushes input buffer and returns all data in that buffer.
Zlib::ZStream#flush_next_out
Flushes output buffer and returns all data in that buffer.
Zlib::ZStream#total_in
Returns the total bytes of the input data to the stream.
Zlib::ZStream#total_out
Returns the total bytes of the output data from the stream.
Zlib::ZStream#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.
Zlib::ZStream#adler
Returns the alder-32 checksum.
Zlib::ZStream#reset
Resets and initializes the stream. All data in both input and output buffer are discarded.
Zlib::ZStream#finish
Finishes the stream and flushes output buffer. See Zlib::Deflate#finish and Zlib::Inflate#finish for detail of the behavior.
Zlib::ZStream#finished?
Zlib::ZStream#stream_end?
Returns true if the stream is finished.
Zlib::ZStream#close
Zlib::ZStream#end
Closes the stream. All operations on the closed stream will raise an exception.
Zlib::ZStream#closed?
Zlib::ZStream#ended?
Returns true if the stream closed.
The class for compressing string data.
Zlib::Deflate.deflate(string[, level])
Compresses string. The avail values of level are Zlib::NO_COMPRESSION, Zlib::BEST_SPEED, Zlib::BEST_COMPRESSION, Zlib::DEFAULT_COMPRESSION, and the integer from 0 to 9.
This method is almostly equivalant to the following code:
def deflate(string, level) z = Zlib::Deflate.new(level) dst = z.deflate(string, Zlib::FINISH) z.close dst end
Zlib::Deflate.new([level[, windowBits[, memlevel[, strategy]]]])
Creates a new deflate stream for compression. See zlib.h for details of each argument. If an argument is nil, the default value of that argument is used.
Zlib::Deflate#clone
Duplicates the deflate stream.
Zlib::Deflate#deflate(string[, flush])
Inputs string into the deflate stream and returns the output from the stream. Calling this method, both input and output buffer of the stream are flushed. If string is nil, this method finishes the stream, just like Zlib::ZStream#finish. The value of flush should be either Zlib::NO_FLUSH, Zlib::SYNC_FLUSH, Zlib::FULL_FLUSH, or Zlib::FINISH. See zlib.h for details.
Zlib::Deflate#<< string
Inputs string into the deflate stream just like Zlib::Deflate#deflate, but returns Zlib::Deflate object itself. The output from the stream is preserved in output buffer.
Zlib::Deflate#flush([flush])
This method is equivalant to deflate('', flush)
.
If flush is omitted, Zlib::SYNC_FLUSH is used
as flush. This method is just provided for
readability of your Ruby script.
Zlib::Deflate#finish
Finishes the stream. This method is equivalant to
deflate('', Zlib::FINISH)
.
Zlib::Deflate#params(level, strategy)
Changes the parameters of the deflate stream. See zlib.h for details. The output from the stream by changing the params is preserved in output buffer.
Zlib::Deflate#set_dictionary(string)
Sets the preset dictionary and returns string. This method is available just only after Zlib::Deflate.new or Zlib::ZStream#reset method was called. See zlib.h for details.
The class for decompressing compressed data. Unlike Zlib::Deflate, an instance of this class is not able to duplicate (clone, dup) itself.
Zlib::Inflate.inflate(string)
Decompresses string. Raises a Zlib::NeedDict exception if a preset dictionary is needed for decompression.
This method is almostly equivalant to the following code:
def inflate(string) zstream = Zlib::Inflate.new buf = zstream.inflate(string) zstream.finish zstream.close buf end
Zlib::Inflate.new([windowBits])
Creates a new inflate stream for decompression. See zlib.h for details of the argument. If windowBits is nil, the default value is used.
Zlib::Inflate#inflate(string)
Inputs string into the inflate stream and returns the output from the stream. Calling this method, both input and output buffer of the stream are flushed. If string is nil, this method finishes the stream, just like Zlib::ZStream#finish.
Raises a Zlib::NeedDict exception if a preset dictionary is needed to decompress. Set the dictionary by Zlib::Inflate#set_dictionary and then call this method again with an empty string.
Zlib::Inflate#<< string
Inputs string into the inflate stream just like Zlib::Inflate#inflate, but returns Zlib::Inflate object itself. The output from the stream is preserved in output buffer.
Zlib::Inflate#finish
Finishes the inflate stream and returns the garbage following the compressed data. Raises an exception if the stream is not finished (i.e. Zlib::ZStream#finished? doesn't returns true).
The inflate stream finishes itself as soon as it meets the end code of the compressed data, you need not to call thisd method explicitly. However, this method is useful for checking whether the data is correctly ended or not.
Zlib::Inflate#set_dictionary(string)
Sets the preset dictionary and returns string This method is available just only after a Zlib::NeedDict exception was raised. See zlib.h for details.
Zlib::Inflate#sync(string)
Inputs string into the end of input buffer and skips data until a full flush point can be found. If the point is found in the buffer, this method flushes the buffer and returns false. Otherwise it returns true and the following data of full flush point is preserved in the buffer.
Zlib::Inflate#sync_point?
What is this?
The abstruct class for handling a gzip formatted compressed file. The operations are defined in the subclasses, Zlib::GzipReader for reading, and Zlib::GzipWriter for writing.
GzipReader should be used with associating an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipFile.new(io)
See Zlib::GzipReader.new and Zlib::GzipWriter.new.
Zlib::GzipFile#closed?
Zlib::GzipFile#to_io
Same as IO.
Zlib::GzipFile#close([dont_close_io])
Closes the GzipReader object. If dont_close_io is ommited or not true, close method of the associated IO object is called. Returns the associated IO object.
Zlib::GzipFile#crc
Returns CRC value of the uncompressed data.
Zlib::GzipFile#level
Returns compression level.
Zlib::GzipFile#mtime
Returns last modification time recorded in the gzip file header.
Zlib::GzipFile#os_code
Returns OS code number recorded in the gzip file header.
Zlib::GzipFile#orig_name
Returns original filename recorded in the gzip file header, or nil if original filename is not present.
Zlib::GzipFile#comment
Returns comments recorded in the gzip file header, or nil if the comments is not present.
Zlib::GzipFile#sync
Zlib::GzipFile#sync= flag
Same as IO. If flag is true, the associated IO object must respond to flush method. While `sync' mode is true, the compression ratio decreases sharply.
The superclass for all exceptions raised during processing a gzip file.
The following exceptions are defined as subclasses of Zlib::GzipFile::Error.
Raised when gzip file footer has not found.
Raised when the CRC checksum recorded in gzip file footer is not equivalant to CRC checksum of the actually uncompressed data.
Raised when the data length recorded in gzip file footer is not equivalant to length of the actually uncompressed data.
The class for reading a gzipped file. GzipReader should be used with associating an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipReader.open('hoge.gz') {|gz| print gz.read }
f = File.open('hoge.gz') gz = Zlib::GzipReader.new(f) print gz.read gz.close
Zlib::GzipReader.new(io)
Zlib::GzipReader.new(io) {|gz| ... }
Creates a GzipReader object associated with io. The GzipReader object reads gzipped data from io, and parses/decompresses them. At least, io must have read method that behaves same as read method in IO class.
If the gzip file header is incorrect, raises an Zlib::GzipFile::Error exception.
If this method is called with a block, the block will be executed with a newly created GzipReader object, just like File.open. The GzipReader object will be closed automatically after executing the block. If you want to keep the associated IO object opening, you may call explicitly Zlib::GzipFile#close method with an argument in the block.
Zlib::GzipReader.open(filename)
Zlib::GzipReader.open(filename) {|gz| ... }
Opens a file specified by filename as a gzipped file, and returns a GzipReader object associated with that file. Further details of this method are same as Zlib::GzipReader.new.
Zlib::GzipReader#eof
Zlib::GzipReader#eof?
Returns true if the object reaches the end of ompressed data. Note that eof? does not return true when reaches the end of file.
Zlib::GzipReader#pos
Zlib::GzipReader#tell
Returns the total bytes of data decompressed until now. Not that it does not the position of file pointer.
Zlib::GzipReader#each([rs])
Zlib::GzipReader#each_line([rs])
Zlib::GzipReader#each_byte([rs])
Zlib::GzipReader#gets([rs])
Zlib::GzipReader#getc
Zlib::GzipReader#lineno
Zlib::GzipReader#lineno=
Zlib::GzipReader#read([length])
Zlib::GzipReader#readchar
Zlib::GzipReader#readline([rs])
Zlib::GzipReader#readlines([rs])
Zlib::GzipReader#ungetc(char)
Same as IO, but raises Zlib::Error or Zlib::GzipFile::Error exception if an error was found in the gzip file.
Be careful of the footer of gzip file. A gzip file has the checksum of pre-compressed data in its footer. GzipReader checks all uncompressed data against that checksum at the following cases, and if failed, raises Zlib::GzipFile::NoFooter, Zlib::GzipFile::CRCError, or Zlib::GzipFile::LengthError exception.
Zlib::GzipReader#rewind
Resets the position of the file pointer to the point created the GzipReader object. The associated IO object need to respond to seek method.
Zlib::GzipReader#unused
Returns the rest of the data which had read for parsing gzip format, or nil if the whole gzip file is not parsed yet.
The class for writing a gzipped file. GzipWriter should be used with associate with an instance of IO class (or an object which has the same methods as IO has).
Zlib::GzipWriter.open('hoge.gz') {|gz| gz.write 'jugemu jugemu gokou no surikire...' }
f = File.open('hoge.gz', 'w') gz = Zlib::GzipWriter.new(f) gz.write 'jugemu jugemu gokou no surikire...' gz.close
NOTE: Due to the limitation in finalizer of Ruby, you must close explicitly GzipWriter object by Zlib::GzipWriter#close etc. Otherwise, GzipWriter should be not able to write gzip footer and generate broken gzip file.
Zlib::GzipWriter.new(io[, level[, strategy]])
Zlib::GzipWriter.new(io[, level[, strategy]]) {|gz| ... }
Creates a GzipWriter object associated with io. level and strategy should be same as the arguments of Zlib::Deflate.new. The GzipWriter object writes gzipped data to io. At least, io must respond to write method that behaves same as write method in IO class.
If new is called with a block, the block will be executed with a newly created GzipWriter object, just like File.open. The GzipWriter object will be closed automatically after executing the block. If you want to keep the associated IO object opening, you may call explicitly Zlib::GzipFile#close method with an argument in the block explicitly.
Zlib::GzipWriter.open(filename[, level[, strategy]])
Zlib::GzipWriter.open(filename[, level[, strategy]]) {|gz| ... }
Opens a file specified by filename for writing gzip compressed data, and returns a GzipWriter object associated with that file. Further details of this method are same as Zlib::GzipWriter.new.
Zlib::GzipWriter#close([dont_close_io])
Writes the gzip file footer and closes the GzipWriter object.
NOTE: Due to the limitation in finalizer of Ruby, you must close GzipWriter object explicitly. Otherwise, GzipWriter should be not able to write gzip footer and generate broken gzip file.
Zlib::GzipWriter#pos
Zlib::GzipWriter#tell
Returns the total bytes of data compressed until now. Note that it does not the position of file pointer.
Zlib::GzipWriter#<< str
Zlib::GzipWriter#putc(ch)
Zlib::GzipWriter#puts(obj...)
Zlib::GzipWriter#print(arg...)
Zlib::GzipWriter#printf(format, arg...)
Zlib::GzipWriter#write(str)
Same as IO.
Zlib::GzipWriter#flush([flush])
Flushes all the internal buffers of the GzipWriter object. The meaning of flush is same as one of the argument of Zlib::Deflate#deflate. Zlib::SYNC_FLUSH is used if flush is omitted. It is no use giving flush Zlib::NO_FLUSH.
Zlib::GzipWriter#mtime= time
Sets last modification time to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Zlib::GzipWriter#orig_name= filename
Sets original filename to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Zlib::GzipWriter#comment= string
Sets comments to be stored in the gzip file header. Zlib::GzipFile::Error exception will be raised if this method is called after writing method (like Zlib::GzipWriter#write) was called.
Almost all the code are rewritten. I hope all changes are enumerated below :-)
The names of almost classes and some methods are changed. All classes and constants are now defined under module Zlib. The obsoleted names are also available for backward compatibility.
Classes
Constants
Methods