class Zlib::ZStream

Родитель:: Object

Zlib::ZStream — абстрактный класс для потока, обрабатывающего сжатые данные. Операции определены в подклассах: Zlib::Deflate для сжатия и Zlib::Inflate для распаковки.

Экземпляр Zlib::ZStream содержит один поток (структуру zstream в исходном коде) и два буфера переменной длины, связанные с входными данными потока (next_in) и выходными данными потока (next_out). В этом документе под «входным буфером» понимается буфер для входных данных, а под «выходным буфером» — буфер для выходных данных.

Data, переданные экземпляру Zlib::ZStream, временно сохраняются в конце входного буфера, после чего данные во входном буфере обрабатываются с начала буфера до тех пор, пока поток не перестанет выдавать данные (то есть пока после обработки avail_out не станет больше 0). Во время обработки выходной буфер автоматически выделяется и расширяется, чтобы вместить все выходные данные.

Некоторые специальные методы экземпляра извлекают данные из выходного буфера и возвращают их в виде String.

Вот 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.

Методы более высокого уровня перечислены ниже.

Публичные методы экземпляра

adler () Показать исходный код

static VALUE
rb_zstream_adler(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.adler);
}

Возвращает контрольную сумму adler-32.

avail_in () Показать исходный код

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.

avail_out () Показать исходный код

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.

avail_out= (p1) Показать исходный код

static VALUE
rb_zstream_set_avail_out(VALUE obj, VALUE size)
{
    struct zstream *z = get_zstream(obj);

    zstream_expand_buffer_into(z, FIX2INT(size));
    return size;
}

Выделяет size байт свободного пространства в выходном буфере. Если в буфере уже находится больше size байт, буфер усекается. Поскольку свободное пространство выделяется автоматически, обычно этот метод не требуется.

close () Показать исходный код

static VALUE
rb_zstream_end(VALUE obj)
{
    zstream_end(get_zstream(obj));
    return Qnil;
}

Закрывает поток. Любые операции с закрытым потоком вызовут исключение.

Также имеет псевдоним: end

closed? () Показать исходный код

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, если поток закрыт.

Также имеет псевдоним: ended?

data_type () Показать исходный код

static VALUE
rb_zstream_data_type(VALUE obj)
{
    return INT2FIX(get_zstream(obj)->stream.data_type);
}

Определяет тип данных, переданных в поток. Возвращаемое значение — BINARY, ASCII или UNKNOWN.

end ()

Закрывает поток. Любые операции с закрытым потоком вызовут исключение.

Псевдоним для: close

ended? ()

Возвращает true, если поток закрыт.

Псевдоним для: closed?

finish → String Показать исходный код

finish { |chunk| ... } → nil

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);
}

Завершает поток и сбрасывает выходной буфер. Если передан блок, каждый фрагмент передаётся ему до тех пор, пока входной буфер не будет сброшен в выходной буфер.

finished? () Показать исходный код

static VALUE
rb_zstream_finished_p(VALUE obj)
{
    return ZSTREAM_IS_FINISHED(get_zstream(obj)) ? Qtrue : Qfalse;
}

Возвращает true, если поток завершён.

Также имеет псевдоним: stream_end?

flush_next_in → input Показать исходный код

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);
    return dst;
}

Сбрасывает входной буфер и возвращает все данные из него.

flush_next_out → String Показать исходный код

flush_next_out { |chunk| ... } → nil

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);
}

Сбрасывает выходной буфер и возвращает все данные из него. Если передан блок, каждый фрагмент передаётся ему до тех пор, пока текущий выходной буфер не будет сброшен.

reset () Показать исходный код

static VALUE
rb_zstream_reset(VALUE obj)
{
    zstream_reset(get_zstream(obj));
    return Qnil;
}

Сбрасывает и инициализирует поток. Все данные во входном и выходном буферах удаляются.

stream_end? ()

Возвращает true, если поток завершён.

Псевдоним для: finished?

total_in () Показать исходный код

static VALUE
rb_zstream_total_in(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.total_in);
}

Возвращает общее количество байтов входных данных потока. FIXME

total_out () Показать исходный код

static VALUE
rb_zstream_total_out(VALUE obj)
{
    return rb_uint2inum(get_zstream(obj)->stream.total_out);
}

Возвращает общее количество байтов выходных данных потока. FIXME

Ruby Core © 1993–2025 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.