{"size": 6017, "ext": "scrbl", "max_stars_repo_path": "doc/utils/rfc/zlib.scrbl", "max_stars_repo_name": "david135/sagittarius-scheme", "max_stars_repo_stars_event_min_datetime": "2015-11-07T07:13:35.000Z", "max_stars_repo_stars_event_max_datetime": "2022-02-15T03:35:14.000Z", "max_issues_repo_path": "doc/utils/rfc/zlib.scrbl", "max_issues_repo_name": "david135/sagittarius-scheme", "max_issues_repo_issues_event_min_datetime": "2016-04-28T21:59:59.000Z", "max_issues_repo_issues_event_max_datetime": "2021-07-01T08:42:21.000Z", "max_forks_repo_path": "doc/utils/rfc/zlib.scrbl", "max_forks_repo_name": "david135/sagittarius-scheme", "max_forks_repo_forks_event_min_datetime": "2016-12-28T12:41:23.000Z", "max_forks_repo_forks_event_max_datetime": "2020-02-26T20:52:02.000Z"}
{"max_stars_count": 39, "max_issues_count": 3, "max_forks_count": 4, "avg_line_length": 44.2426470588, "max_line_length": 80, "alphanum_fraction": 0.7751371115}
@; -*- coding: utf-8 -*-
@subsection[:tag "rfc.zlib"]{(rfc zlib) - zlib compression library}

@define[Library]{@name{(rfc zlib)}}
@desc{This library provides the binding for zlib compression library. For now,
it only provides the highest level APIs.
}

@define["Condition Type"]{@name{&zlib-error}}
@define[Function]{@name{zlib-error?} @args{obj}}
@define[Function]{@name{condition-zlib-stream} @args{zlib-error}}
@desc{Subcondition of @code{&error}.

This condition is raised when zlib process is finished unsuccessfully. You can
obtain the cause z-stream with the @code{condition-zlib-stream} procedure and
get the detail message with the @code{zlib-error-message} procedure. When error
occurred, however, it is raised with @code{message-condition} and it has the
error message with. So you can simply get it with @code{condition-message}
procedure.
}

@define[Function]{@name{zlib-error-message} @args{z-stream}}
@desc{@var{Z-stream} must be z-stream object.

Retrieve error message from @var{z-stream}. If @var{z-stream} does not have any
error message and this procedure is called, the behaviour is unspecified.
}

@define[Function]{@name{open-deflating-output-port}
 @args{sink :key compression-level buffer-size window-bits memory-level
 strategy dictionary owner?}}
@desc{@var{Sink} must be binary output port. Creates a custom binary output
port. The port deflates its input and put the result to @var{sink}. With the
optional keys, you can specify the following conditions:

@dl-list[
@dl-item[@var{compression-level}]{
You can specify an exact integer between 1 and 9 (inclusive) to
@var{compression-level}. When it is omitted, a default compression level is
used, which is usually 6.

The following constants are defined to specify @var{compression-level}
conveniently:
@define[Constant]{@name{Z_NO_COMPRESSION}}
@define[Constant]{@name{Z_BEST_SPEED}}
@define[Constant]{@name{Z_BEST_COMPRESSION}}
@define[Constant]{@name{Z_DEFAULT_COMPRESSION}}
}
@dl-item[@var{buffer-size}]{It specifies the buffer size of the port in bytes.
The default is 4096.
}
@dl-item[@var{window-bits}]{It specifies the size of the window in exact
integer. Typically the value should be between 8 and 15, inclusive, and it
specifies the base two logarithm of the window size used in compression. Larger
number yields better compression ratio, but more memory usage. The default value
is 15.
}
@dl-item[@var{memory-level}]{It specifies how much memory should be allocated to
keep the internal state during compression. 1 means smallest memory which causes
slow and less compression. 9 means fastest and best compression with the largest
amount of memory. The default value is 8.
}
@dl-item[@var{strategy}]{To fine tune compression algorithm, you can use the
@var{strategy} argument. The following constants are defined as the valid value
as @var{strategy}.
@define[Constant]{@name{Z_DEFAULT_STRATEGY}}
@desc{The default strategy, suitable for most ordinary data.}
@define[Constant]{@name{Z_FILTERED}}
@desc{Suitable for data generated by filters (or predictors). Filtered data
consists mostly of small values with a somewhat compress them better. The
effect of this is to force more huffman coding and less string matching.}
@define[Constant]{@name{Z_HUFFMAN_ONLY}}
@desc{Force to use huffman encoding only.}
@define[Constant]{@name{Z_RLE}}
@desc{This is designed to be almost as fast as Z_HUFFMAN_ONLY, but gives better
compression for PNG image data.}
@define[Constant]{@name{Z_FIXED}}
@desc{This prevents the use of dynamic huffman codes, allowing for a simpler
decoder for special applications.}
The choice of @var{strategy} only affects compression ratio and speed. Any
choice produces correct and decompressable data.
}
@dl-item[@var{dictionary}]{You can give an initial dictionary to the
@var{dictionary} argument to be used in compression. The compressor and
decompressor must use exactly the same dictionary.
}
@dl-item[@var{owner?}]{If this argument is specified true value, the created
port automatically closes the given output port @var{sink} when it is closed.
}
]

}

@define[Function]{@name{open-inflating-input-port}
 @args{source :key buffer-size window-bits dictionary owner?}}
@desc{@var{Source} must be a binary input port.

The @code{open-inflating-input-port} creates a custom binary input port, which
reads compressed binary data from the given port @var{source} and decompresses
the read data. When @var{source} port supports both @code{port-position} and
@code{set-port-position!} then the procedure will set @var{source} position
to offset of used bytes length when the created custom port is being closed.
Thus if the @var{source} port contains mixture of deflated data and non
deflated data then the custom port will only read deflated data and won't
forward the original port position beyond it no matter how big the
@var{buffer-size} is specified.

The meaning of @var{buffer-size} is the same as
 @code{open-deflating-output-port}.

The meaning of @var{window-bits} is almost the same, except if a value increased
by 32 is given, the inflating port automatically detecs whether the source
stream is zlib or gzip by its header.

If the input data is compressed with specified dictionary, the same dictionary
must be given to @var{dictionary} argument. Otherwise &zlib-error condition is
raised.
}

@define[Function]{@name{inflate-bytevector} @args{bv opts @dots{}}}
@define[Function]{@name{deflate-bytevector} @args{bv opts @dots{}}}
@desc{Inflate/deflate given bytevector @var{bv} respectively.

These are convenient procedures. It uses @code{open-inflating-input-port} or
@code{open-deflating-output-port} to inflate/deflate.

The @var{opts} will be passed to underlying procedures.
}

@define[Function]{@name{crc32} @args{bv :optional (checksum 0)}}
@define[Function]{@name{adler32} @args{bv :optional (checksum 0)}}
@desc{Returns CSC32/Adler32 checksum of bytevector @var{bv}, respectively.

If optional @var{checksum} is given, then returned checksum is an update of
@var{checksum} by @var{bv}.
}