# # 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:Inflate is the class for decompressing compressed data. Unlike # Zlib::Deflate, an instance of this class is not able to duplicate (clone, dup) # itself. # class Inflate < Zlib::ZStream # # Decompresses `string`. Raises a Zlib::NeedDict exception if a preset # dictionary is needed for decompression. # # This method is almost equivalent to the following code: # # def inflate(string) # zstream = Zlib::Inflate.new # buf = zstream.inflate(string) # zstream.finish # zstream.close # buf # end # # See also Zlib.deflate # def self.inflate: (string string) -> String # # Same as IO. # def <<: (_ToS obj) -> self # # Provide the inflate stream with a dictionary that may be required in the # future. Multiple dictionaries may be provided. The inflate stream will # automatically choose the correct user-provided dictionary based on the # stream's required dictionary. # def add_dictionary: (String arg0) -> void # # Inputs `deflate_string` into the inflate stream and returns the output from # the stream. Calling this method, both the input and the output buffer of the # stream are flushed. If string is `nil`, this method finishes the stream, just # like Zlib::ZStream#finish. # # If a block is given consecutive inflated chunks from the `deflate_string` are # yielded to the block and `nil` is returned. # # If a :buffer keyword argument is given and not nil: # # * The :buffer keyword should be a String, and will used as the output # buffer. Using this option can reuse the memory required during inflation. # * When not passing a block, the return value will be the same object as the # :buffer keyword argument. # * When passing a block, the yielded chunks will be the same value as the # :buffer keyword argument. # # # 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 to flush the stream: # # inflater = Zlib::Inflate.new # # begin # out = inflater.inflate compressed # rescue Zlib::NeedDict # # ensure the dictionary matches the stream's required dictionary # raise unless inflater.adler == Zlib.adler32(dictionary) # # inflater.set_dictionary dictionary # inflater.inflate '' # end # # # ... # # inflater.close # # See also Zlib::Inflate.new # def inflate: (string string, ?buffer: String) -> String | (string string, ?buffer: String) { (String chunk) -> nil } -> nil # # 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. # def set_dictionary: (String p1) -> 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. # def sync: (String string) -> bool # # Quoted verbatim from original documentation: # # What is this? # # `:)` # def sync_point?: () -> bool private # # Creates a new inflate stream for decompression. `window_bits` sets the size # of the history buffer and can have the following values: # # 0 # : Have inflate use the window size from the zlib header of the compressed # stream. # # (8..15) # : Overrides the window size of the inflate header in the compressed stream. # The window size must be greater than or equal to the window size of the # compressed stream. # # Greater than 15 # : Add 32 to window_bits to enable zlib and gzip decoding with automatic # header detection, or add 16 to decode only the gzip format (a # Zlib::DataError will be raised for a non-gzip stream). # # (-8..-15) # : Enables raw deflate mode which will not generate a check value, and will # not look for any check values for comparison at the end of the stream. # # This is for use with other formats that use the deflate compressed data # format such as zip which provide their own check values. # # # ## Example # # open "compressed.file" do |compressed_io| # zi = Zlib::Inflate.new(Zlib::MAX_WBITS + 32) # # begin # open "uncompressed.file", "w+" do |uncompressed_io| # uncompressed_io << zi.inflate(compressed_io.read) # end # ensure # zi.close # end # end # def initialize: (?Integer window_bits) -> void end end