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