класс Zlib::ZStream
Zlib::ZStream — это абстрактный класс для потока, который обрабатывает сжатые данные. Операции определены в подклассах: Zlib::Deflate для сжатия и Zlib::Inflate для распаковки.
Экземпляр Zlib::ZStream имеет один поток (структура zstream в исходном коде) и два буфера переменной длины, связанные с входом (next_in) потока и выходом (next_out) потока. В этом документе «буфер ввода» означает буфер для ввода, а «буфер вывода» означает буфер для вывода.
Данные на вход экземпляру Zlib::ZStream временно сохраняются в конце буфера ввода, а затем данные в буфере ввода обрабатываются с начала буфера до тех пор, пока не будет произведено больше вывода из потока (то есть, пока #avail_out > 0 после обработки). Во время обработки буфер вывода выделяется и расширяется автоматически для хранения всех выходных данных.
Некоторые конкретные методы экземпляра потребляют данные в буфере вывода и возвращают их в виде строки.
Вот ASCII-арт для описания вышеизложенного:
+================ an instance of Zlib::ZStream ================+
|| ||
|| +--------+ +-------+ +--------+ ||
|| +--| output |<---------|zstream|<---------| input |<--+ ||
|| | | buffer | next_out+-------+next_in | buffer | | ||
|| | +--------+ +--------+ | ||
|| | | ||
+===|======================================================|===+
| |
v |
"output data" "input data" Если при обработке буфера ввода произошла ошибка, генерируется исключение, которое является подклассом Zlib::Error. В этот момент и буфер ввода, и буфер вывода сохраняют свои состояния на момент возникновения ошибки.
Методы
Многие методы в этом классе довольно низкого уровня и, скорее всего, не представляют интереса для пользователей. Фактически, пользователи вряд ли будут использовать этот класс напрямую; скорее, они будут заинтересованы в Zlib::Inflate и Zlib::Deflate.
Методы более высокого уровня перечислены ниже.
Публичные методы экземпляров
static VALUE
rb_zstream_adler(VALUE obj)
{
return rb_uint2inum(get_zstream(obj)->stream.adler);
} Возвращает контрольную сумму adler-32.
static VALUE
rb_zstream_avail_in(VALUE obj)
{
struct zstream *z;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
return INT2FIX(NIL_P(z->input) ? 0 : (int)(RSTRING_LEN(z->input)));
} Возвращает байты данных в буфере ввода. Обычно возвращает 0.
static VALUE
rb_zstream_avail_out(VALUE obj)
{
struct zstream *z;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
return rb_uint2inum(z->stream.avail_out);
} Возвращает количество байтов свободного места в буфере вывода. Поскольку свободное место выделяется автоматически, этот метод обычно возвращает 0.
static VALUE
rb_zstream_set_avail_out(VALUE obj, VALUE size)
{
struct zstream *z = get_zstream(obj);
Check_Type(size, T_FIXNUM);
zstream_expand_buffer_into(z, FIX2INT(size));
return size;
} Выделяет size байт свободного места в буфере вывода. Если в буфере уже содержится более size байт, буфер усекается. Поскольку свободное место выделяется автоматически, обычно нет необходимости использовать этот метод.
static VALUE
rb_zstream_end(VALUE obj)
{
zstream_end(get_zstream(obj));
return Qnil;
} Закрывает поток. Все операции с закрытым потоком приведут к исключению.
static VALUE
rb_zstream_closed_p(VALUE obj)
{
struct zstream *z;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
return ZSTREAM_IS_READY(z) ? Qfalse : Qtrue;
} Возвращает true, если поток закрыт.
static VALUE
rb_zstream_data_type(VALUE obj)
{
return INT2FIX(get_zstream(obj)->stream.data_type);
} Определяет тип данных, которые были введены в поток. Возвращаемое значение — это либо BINARY, либо ASCII, либо UNKNOWN.
static VALUE
rb_zstream_end(VALUE obj)
{
zstream_end(get_zstream(obj));
return Qnil;
} Закрывает поток. Все операции с закрытым потоком приведут к исключению.
static VALUE
rb_zstream_closed_p(VALUE obj)
{
struct zstream *z;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
return ZSTREAM_IS_READY(z) ? Qfalse : Qtrue;
} Возвращает true, если поток закрыт.
static VALUE
rb_zstream_finish(VALUE obj)
{
struct zstream *z = get_zstream(obj);
zstream_run(z, (Bytef*)"", 0, Z_FINISH);
return zstream_detach_buffer(z);
} Завершает поток и очищает буфер вывода. Если задан блок, каждый кусок передаётся в блок, пока буфер ввода не будет очищен в буфер вывода.
static VALUE
rb_zstream_finished_p(VALUE obj)
{
return ZSTREAM_IS_FINISHED(get_zstream(obj)) ? Qtrue : Qfalse;
} Возвращает true, если поток завершен.
static VALUE
rb_zstream_flush_next_in(VALUE obj)
{
struct zstream *z;
VALUE dst;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
dst = zstream_detach_input(z);
OBJ_INFECT(dst, obj);
return dst;
} static VALUE
rb_zstream_flush_next_out(VALUE obj)
{
struct zstream *z;
TypedData_Get_Struct(obj, struct zstream, &zstream_data_type, z);
return zstream_detach_buffer(z);
} Очищает буфер вывода и возвращает все данные в этом буфере. Если задан блок, каждый кусок передаётся в блок, пока текущий буфер вывода не будет очищен.
static VALUE
rb_zstream_reset(VALUE obj)
{
zstream_reset(get_zstream(obj));
return Qnil;
} Сбрасывает и инициализирует поток. Все данные в буфере ввода и буфере вывода отбрасываются.
static VALUE
rb_zstream_finished_p(VALUE obj)
{
return ZSTREAM_IS_FINISHED(get_zstream(obj)) ? Qtrue : Qfalse;
} Возвращает true, если поток завершен.
static VALUE
rb_zstream_total_in(VALUE obj)
{
return rb_uint2inum(get_zstream(obj)->stream.total_in);
} Возвращает общее количество байт входных данных для потока. FIXME
static VALUE
rb_zstream_total_out(VALUE obj)
{
return rb_uint2inum(get_zstream(obj)->stream.total_out);
} Возвращает общее количество байт выходных данных из потока. FIXME
Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.
