класс 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.
