类 Zlib::ZStream

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

一个 Zlib::ZStream 实例有一个流（源代码中的 struct zstream）和两个可变长度的缓冲区，它们与流的输入（next_in）和流的输出（next_out）相关联。在本文档中，“输入缓冲区”是指用于输入的缓冲区，“输出缓冲区”是指用于输出的缓冲区。

输入到 Zlib::ZStream 实例的 Data 会暂时存储到输入缓冲区的末尾，然后从缓冲区的开头处理输入缓冲区中的数据，直到不再产生流的输出（即，直到处理后 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 感兴趣。

以下是更高级别的方法列表。

公共实例方法

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

返回流的输入数据的总字节数。待修复

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

total_out() 点击切换源代码

返回流的输出数据的总字节数。待修复

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

类 Zlib::ZStream

Method 目录¶ ↑

`Method` 目录¶ ↑