# <!-- 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::GzipWriter is a class for writing gzipped files.  GzipWriter should be
  # used with an instance of IO, or IO-like, object.
  #
  # Following two example generate the same result.
  #
  #     Zlib::GzipWriter.open('hoge.gz') do |gz|
  #       gz.write 'jugemu jugemu gokou no surikire...'
  #     end
  #
  #     File.open('hoge.gz', 'w') do |f|
  #       gz = Zlib::GzipWriter.new(f)
  #       gz.write 'jugemu jugemu gokou no surikire...'
  #       gz.close
  #     end
  #
  # To make like gzip(1) does, run following:
  #
  #     orig = 'hoge.txt'
  #     Zlib::GzipWriter.open('hoge.gz') do |gz|
  #       gz.mtime = File.mtime(orig)
  #       gz.orig_name = orig
  #       gz.write IO.binread(orig)
  #     end
  #
  # NOTE: Due to the limitation of Ruby's finalizer, you must explicitly close
  # GzipWriter objects by Zlib::GzipWriter#close etc.  Otherwise, GzipWriter will
  # be not able to write the gzip footer and will generate a broken gzip file.
  #
  class GzipWriter < Zlib::GzipFile
    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib::GzipWriter.open(filename, level=nil, strategy=nil) { |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 found in Zlib::GzipWriter.new and Zlib::GzipFile.wrap.
    #
    def self.open: (String filename) { (instance gz) -> void } -> instance

    public

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

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - comment=(p1)
    # -->
    # Specify the comment (`str`) in the gzip header.
    #
    def comment=: (String arg0) -> void

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - flush(flush=nil)
    # -->
    # Flushes all the internal buffers of the GzipWriter object.  The meaning of
    # `flush` is same as in Zlib::Deflate#deflate.  `Zlib::SYNC_FLUSH` is used if
    # `flush` is omitted.  It is no use giving flush `Zlib::NO_FLUSH`.
    #
    def flush: (?Integer flush) -> String

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - mtime=(p1)
    # -->
    # Specify the modification time (`mtime`) in the gzip header. Using an Integer.
    #
    # Setting the mtime in the gzip header does not effect the mtime of the file
    # generated. Different utilities that expand the gzipped files may use the mtime
    # header. For example the gunzip utility can use the `-N` flag which will set
    # the resultant file's mtime to the value in the header. By default many tools
    # will set the mtime of the expanded file to the mtime of the gzipped file, not
    # the mtime in the header.
    #
    # If you do not set an mtime, the default value will be the time when
    # compression started. Setting a value of 0 indicates no time stamp is
    # available.
    #
    def mtime=: (string | _ToPath | IO file_name) -> Time

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - orig_name=(p1)
    # -->
    # Specify the original name (`str`) in the gzip header.
    #
    def orig_name=: (String arg0) -> void

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - pos()
    # -->
    # Total number of input bytes read so far.
    #
    def pos: () -> Integer

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - print(*args)
    # -->
    # Same as IO.
    #
    def print: (*untyped arg0) -> NilClass

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - printf(*args)
    # -->
    # Same as IO.
    #
    def printf: (String format_string, *untyped arg0) -> NilClass

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - putc(p1)
    # -->
    # Same as IO.
    #
    def putc: (Numeric | String arg0) -> untyped

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - puts(*args)
    # -->
    # Same as IO.
    #
    def puts: (*untyped arg0) -> NilClass

    # <!-- rdoc-file=ext/zlib/zlib.c -->
    # Total number of input bytes read so far.
    #
    def tell: () -> Integer

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - write(*args)
    # -->
    # Same as IO.
    #
    def write: (*_ToS string) -> Integer

    private

    # <!--
    #   rdoc-file=ext/zlib/zlib.c
    #   - Zlib::GzipWriter.new(io, level = nil, strategy = nil, options = {})
    # -->
    # Creates a GzipWriter object associated with `io`. `level` and `strategy`
    # should be the same as the arguments of Zlib::Deflate.new.  The GzipWriter
    # object writes gzipped data to `io`.  `io` must respond to the `write` method
    # that behaves the same as IO#write.
    #
    # The `options` hash may be used to set the encoding of the data.
    # `:external_encoding`, `:internal_encoding` and `:encoding` may be set as in
    # IO::new.
    #
    def initialize: (_Writer io, Integer level, Integer strategy, **untyped opts) -> void
  end
end