%a{annotate:rdoc:skip}
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

    # <!--
    #   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
