# <!-- 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::Deflate is the class for compressing data.  See Zlib::ZStream for more
  # information.
  #
  class Deflate < Zlib::ZStream
    type compression_level = Integer

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib.deflate(string[, level])
    #   - Zlib::Deflate.deflate(string[, level])
    # -->
    # Compresses the given `string`. Valid values of level are Zlib::NO_COMPRESSION,
    # Zlib::BEST_SPEED, Zlib::BEST_COMPRESSION, Zlib::DEFAULT_COMPRESSION, or an
    # integer from 0 to 9.
    #
    # This method is almost equivalent to the following code:
    #
    #     def deflate(string, level)
    #       z = Zlib::Deflate.new(level)
    #       dst = z.deflate(string, Zlib::FINISH)
    #       z.close
    #       dst
    #     end
    #
    # See also Zlib.inflate
    #
    def self.deflate: (string string, ?compression_level level) -> String

    public

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - << string
    # -->
    # Inputs `string` into the deflate stream just like Zlib::Deflate#deflate, but
    # returns the Zlib::Deflate object itself.  The output from the stream is
    # preserved in output buffer.
    #
    def <<: (string string) -> self

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - z.deflate(string, flush = Zlib::NO_FLUSH)                 -> String
    #   - z.deflate(string, flush = Zlib::NO_FLUSH) { |chunk| ... } -> nil
    # -->
    # Inputs `string` into the deflate stream and returns the output from the
    # stream.  On calling this method, both the input and the output buffers 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 deflated chunks from the `string` are yielded
    # to the block and `nil` is returned.
    #
    # The `flush` parameter specifies the flush mode.  The following constants may
    # be used:
    #
    # Zlib::NO_FLUSH
    # :   The default
    # Zlib::SYNC_FLUSH
    # :   Flushes the output to a byte boundary
    # Zlib::FULL_FLUSH
    # :   SYNC_FLUSH + resets the compression state
    # Zlib::FINISH
    # :   Pending input is processed, pending output is flushed.
    #
    #
    # See the constants for further description.
    #
    def deflate: (string string, ?Integer flush) -> String
               | (string string, ?Integer flush) { (String chunk) -> nil } -> nil

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - flush(flush = Zlib::SYNC_FLUSH)                 -> String
    #   - flush(flush = Zlib::SYNC_FLUSH) { |chunk| ... } -> nil
    # -->
    # This method is equivalent to `deflate('', flush)`. This method is just
    # provided to improve the readability of your Ruby program.  If a block is given
    # chunks of deflate output are yielded to the block until the buffer is flushed.
    #
    # See Zlib::Deflate#deflate for detail on the `flush` constants NO_FLUSH,
    # SYNC_FLUSH, FULL_FLUSH and FINISH.
    #
    def flush: (?Integer flush) -> String
             | (?Integer flush) {(String chunk) -> nil } -> nil

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - params(level, strategy)
    # -->
    # Changes the parameters of the deflate stream to allow changes between
    # different types of data that require different types of compression.  Any
    # unprocessed data is flushed before changing the params.
    #
    # See Zlib::Deflate.new for a description of `level` and `strategy`.
    #
    def params: (compression_level level, Integer strategy) -> void

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - 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.
    #
    # Can raise errors of Z_STREAM_ERROR if a parameter is invalid (such as NULL
    # dictionary) or the stream state is inconsistent, Z_DATA_ERROR if the given
    # dictionary doesn't match the expected one (incorrect adler32 value)
    #
    def set_dictionary: (String dictionary) -> String

    private

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib::Deflate.new(level=DEFAULT_COMPRESSION, window_bits=MAX_WBITS, mem_level=DEF_MEM_LEVEL, strategy=DEFAULT_STRATEGY)
    # -->
    # Creates a new deflate stream for compression. If a given argument is nil, the
    # default value of that argument is used.
    #
    # The `level` sets the compression level for the deflate stream between 0 (no
    # compression) and 9 (best compression). The following constants have been
    # defined to make code more readable:
    #
    # *   Zlib::DEFAULT_COMPRESSION
    # *   Zlib::NO_COMPRESSION
    # *   Zlib::BEST_SPEED
    # *   Zlib::BEST_COMPRESSION
    #
    #
    # See http://www.zlib.net/manual.html#Constants for further information.
    #
    # The `window_bits` sets the size of the history buffer and should be between 8
    # and 15.  Larger values of this parameter result in better compression at the
    # expense of memory usage.
    #
    # The `mem_level` specifies how much memory should be allocated for the internal
    # compression state.  1 uses minimum memory but is slow and reduces compression
    # ratio while 9 uses maximum memory for optimal speed.  The default value is 8.
    # Two constants are defined:
    #
    # *   Zlib::DEF_MEM_LEVEL
    # *   Zlib::MAX_MEM_LEVEL
    #
    #
    # The `strategy` sets the deflate compression strategy.  The following
    # strategies are available:
    #
    # Zlib::DEFAULT_STRATEGY
    # :   For normal data
    # Zlib::FILTERED
    # :   For data produced by a filter or predictor
    # Zlib::FIXED
    # :   Prevents dynamic Huffman codes
    # Zlib::HUFFMAN_ONLY
    # :   Prevents string matching
    # Zlib::RLE
    # :   Designed for better compression of PNG image data
    #
    #
    # See the constants for further description.
    #
    # ## Examples
    #
    # ### Basic
    #
    #     open "compressed.file", "w+" do |io|
    #       io << Zlib::Deflate.new.deflate(File.read("big.file"))
    #     end
    #
    # ### Custom compression
    #
    #     open "compressed.file", "w+" do |compressed_io|
    #       deflate = Zlib::Deflate.new(Zlib::BEST_COMPRESSION,
    #                                   Zlib::MAX_WBITS,
    #                                   Zlib::MAX_MEM_LEVEL,
    #                                   Zlib::HUFFMAN_ONLY)
    #
    #       begin
    #         open "big.file" do |big_io|
    #           until big_io.eof? do
    #             compressed_io << zd.deflate(big_io.read(16384))
    #           end
    #         end
    #       ensure
    #         deflate.close
    #       end
    #     end
    #
    # While this example will work, for best optimization review the flags for your
    # specific time, memory usage and output space requirements.
    #
    def initialize: (?compression_level level, ?Integer window_bits, ?Integer mem_level, ?Integer strategy) -> void

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - initialize_copy(p1)
    # -->
    # Duplicates the deflate stream.
    #
    def initialize_copy: (self other) -> self
  end
end
