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