класс 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_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);
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_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–2022 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.
