класс Zlib::ZStream
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. В этом случае и входной, и выходной буферы сохраняют своё состояние на момент возникновения ошибки.
Method Каталог
Многие методы в этом классе достаточно низкого уровня и вряд ли будут интересны пользователю. На самом деле, пользователям вряд ли нужно использовать этот класс напрямую; их скорее заинтересуют 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);
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.
