class Zlib::ZStream

Zlib::ZStream 是处理压缩数据的流的抽象类。操作在子类中定义：Zlib::Deflate 用于压缩，以及 Zlib::Inflate 用于解压缩。

Zlib::ZStream 的实例具有一个流（源代码中的 struct 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。

下面列出了更高级别的方法。

公共实例方法

adler() 点击以切换源代码

返回 adler-32 校验和。

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

avail_in() 点击以切换源代码

返回输入缓冲区中的数据字节数。通常，返回 0。

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

avail_out() 点击以切换源代码

返回输出缓冲区中空闲空间的字节数。由于空闲空间是自动分配的，因此此方法通常返回 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);
}

avail_out=(p1) 点击以切换源代码

在输出缓冲区中分配 size 字节的空闲空间。如果缓冲区中已经有超过 size 字节，则缓冲区会被截断。由于空闲空间是自动分配的，因此通常不需要使用此方法。

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

close() 点击以切换源代码

关闭流。对已关闭的流的所有操作都会引发异常。

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

也称为别名：end

closed?() 点击以切换源代码

如果流已关闭，则返回 true。

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

也称为别名：ended?

data_type() 点击以切换源代码

猜测已输入到流中的数据的类型。返回的值为 BINARY、ASCII 或 UNKNOWN。

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

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?() 点击以切换源代码

如果流已完成，则返回 true。

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

也称为别名：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() 点击以切换源代码

返回输入到流中的数据的总字节数。FIXME

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

total_out() 点击以切换源代码

返回从流输出的数据的总字节数。FIXME

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