# <!-- rdoc-file=ext/zlib/zlib.c -->
# 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
  # <!-- rdoc-file=ext/zlib/zlib.c -->
  # 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
    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib.inflate(string)
    #   - Zlib::Inflate.inflate(string)
    # -->
    # 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

    public

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - <<(p1)
    # -->
    # Same as IO.
    #
    def <<: (_ToS obj) -> self

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - add_dictionary(string)
    # -->
    # 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

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - inflate(deflate_string, buffer: nil)                 -> String
    #   - inflate(deflate_string, buffer: nil) { |chunk| ... } -> nil
    # -->
    # 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

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - set_dictionary(p1)
    # -->
    # 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

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - 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.
    #
    def sync: (String string) -> bool

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - sync_point?()
    # -->
    # Quoted verbatim from original documentation:
    #
    #     What is this?
    #
    # `:)`
    #
    def sync_point?: () -> bool

    private

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib::Inflate.new(window_bits = Zlib::MAX_WBITS)
    # -->
    # 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
