Class: Zlib::ZStream

Inherits:
Object
  • Object
show all
Defined in:
ext/rubysl/zlib/zlib.c,
ext/rubysl/zlib/zlib.c

Overview

Zlib::ZStream is the abstract class for the stream which handles the compressed data. The operations are defined in the subclasses: Zlib::Deflate for compression, and Zlib::Inflate for decompression.

An instance of Zlib::ZStream has one stream (struct zstream in the source) and two variable-length buffers which associated to the input (next_in) of the stream and the output (next_out) of the stream. In this document, “input buffer” means the buffer for input, and “output buffer” means the buffer for output.

Data input into an instance of Zlib::ZStream are temporally stored into the end of input buffer, and then data in input buffer are processed from the beginning of the buffer until no more output from the stream is produced (i.e. until avail_out > 0 after processing). During processing, output buffer is allocated and expanded automatically to hold all output data.

Some particular instance methods consume the data in output buffer and return them as a String.

Here is an ascii art for describing above:

+================ an instance of Zlib::ZStream ================+
||                                                            ||
||     +--------+          +-------+          +--------+      ||
||  +--| output |<---------|zstream|<---------| input  |<--+  ||
||  |  | buffer |  next_out+-------+next_in   | buffer |   |  ||
||  |  +--------+                             +--------+   |  ||
||  |                                                      |  ||
+===|======================================================|===+
    |                                                      |
    v                                                      |
"output data"                                         "input data"

If an error occurs during processing input buffer, an exception which is a subclass of Zlib::Error is raised. At that time, both input and output buffer keep their conditions at the time when the error occurs.

Method Catalogue

Many of the methods in this class are fairly low-level and unlikely to be of interest to users. In fact, users are unlikely to use this class directly; rather they will be interested in Zlib::Inflate and Zlib::Deflate.

The higher level methods are listed below.

  • #total_in

  • #total_out

  • #data_type

  • #adler

  • #reset

  • #finish

  • #finished?

  • #close

  • #closed?

Direct Known Subclasses

Deflate, Inflate

Instance Method Summary collapse

Instance Method Details

#adler ⇒ Object

Returns the adler-32 checksum.



1188
1189
1190
1191
1192
 
# File 'ext/rubysl/zlib/zlib.c', line 1188

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

#avail_in ⇒ Object

Returns bytes of data in the input buffer. Normally, returns 0.



1148
1149
1150
1151
1152
1153
1154
 
# File 'ext/rubysl/zlib/zlib.c', line 1148

static VALUE
rb_zstream_avail_in(VALUE obj)
{
    struct zstream *z;
    Data_Get_Struct(obj, struct zstream, z);
    return INT2FIX(NIL_P(z->input) ? 0 : (int)(RSTRING_LEN(z->input)));
}

#avail_out ⇒ Object

Returns number of bytes of free spaces in output buffer. Because the free space is allocated automatically, this method returns 0 normally.



1121
1122
1123
1124
1125
1126
1127
 
# File 'ext/rubysl/zlib/zlib.c', line 1121

static VALUE
rb_zstream_avail_out(VALUE obj)
{
    struct zstream *z;
    Data_Get_Struct(obj, struct zstream, z);
    return rb_uint2inum(z->stream.avail_out);
}

#avail_out=(size) ⇒ Object

Allocates size bytes of free space in the output buffer. If there are more than size bytes already in the buffer, the buffer is truncated. Because free space is allocated automatically, you usually don’t need to use this method.



1135
1136
1137
1138
1139
1140
1141
1142
1143
 
# File 'ext/rubysl/zlib/zlib.c', line 1135

static VALUE
rb_zstream_set_avail_out(VALUE obj, VALUE size)
{
    struct zstream *z = get_zstream(obj);

    Check_Type(size, T_FIXNUM);
    zstream_expand_buffer_into(z, FIX2INT(size));
    return size;
}

#close ⇒ Object

Closes the stream. All operations on the closed stream will raise an exception.



1052
1053
1054
1055
1056
1057
 
# File 'ext/rubysl/zlib/zlib.c', line 1052

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

#closed? ⇒ Boolean

Returns true if the stream is closed.

Returns:

  • (Boolean) 


1206
1207
1208
1209
1210
1211
1212
 
# File 'ext/rubysl/zlib/zlib.c', line 1206

static VALUE
rb_zstream_closed_p(VALUE obj)
{
    struct zstream *z;
    Data_Get_Struct(obj, struct zstream, z);
    return ZSTREAM_IS_READY(z) ? Qfalse : Qtrue;
}

#data_type ⇒ Object

Guesses the type of the data which have been inputed into the stream. The returned value is either BINARY, ASCII, or UNKNOWN.



1179
1180
1181
1182
1183
 
# File 'ext/rubysl/zlib/zlib.c', line 1179

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

#end ⇒ Object

Closes the stream. All operations on the closed stream will raise an exception.



1052
1053
1054
1055
1056
1057
 
# File 'ext/rubysl/zlib/zlib.c', line 1052

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

#ended? ⇒ Boolean

Returns true if the stream is closed.

Returns:

  • (Boolean) 


1206
1207
1208
1209
1210
1211
1212
 
# File 'ext/rubysl/zlib/zlib.c', line 1206

static VALUE
rb_zstream_closed_p(VALUE obj)
{
    struct zstream *z;
    Data_Get_Struct(obj, struct zstream, z);
    return ZSTREAM_IS_READY(z) ? Qfalse : Qtrue;
}

#finish ⇒ Object

Finishes the stream and flushes output buffer. See Zlib::Deflate#finish and Zlib::Inflate#finish for details of this behavior.



1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
 
# File 'ext/rubysl/zlib/zlib.c', line 1074

static VALUE
rb_zstream_finish(VALUE obj)
{
    struct zstream *z = get_zstream(obj);
    VALUE dst;

    zstream_run(z, (Bytef*)"", 0, Z_FINISH);
    dst = zstream_detach_buffer(z);

    OBJ_INFECT(dst, obj);
    return dst;
}

#finished? ⇒ Boolean

Returns true if the stream is finished.

Returns:

  • (Boolean) 


1197
1198
1199
1200
1201
 
# File 'ext/rubysl/zlib/zlib.c', line 1197

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

#flush_next_in ⇒ Object

Flushes input buffer and returns all data in that buffer.



1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
 
# File 'ext/rubysl/zlib/zlib.c', line 1090

static VALUE
rb_zstream_flush_next_in(VALUE obj)
{
    struct zstream *z;
    VALUE dst;

    Data_Get_Struct(obj, struct zstream, z);
    dst = zstream_detach_input(z);
    OBJ_INFECT(dst, obj);
    return dst;
}

#flush_next_out ⇒ Object

Flushes output buffer and returns all data in that buffer.



1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
 
# File 'ext/rubysl/zlib/zlib.c', line 1105

static VALUE
rb_zstream_flush_next_out(VALUE obj)
{
    struct zstream *z;
    VALUE dst;

    Data_Get_Struct(obj, struct zstream, z);
    dst = zstream_detach_buffer(z);
    OBJ_INFECT(dst, obj);
    return dst;
}

#reset ⇒ Object

Resets and initializes the stream. All data in both input and output buffer are discarded.



1063
1064
1065
1066
1067
1068
 
# File 'ext/rubysl/zlib/zlib.c', line 1063

static VALUE
rb_zstream_reset(VALUE obj)
{
    zstream_reset(get_zstream(obj));
    return Qnil;
}

#stream_end? ⇒ Boolean

Returns true if the stream is finished.

Returns:

  • (Boolean) 


1197
1198
1199
1200
1201
 
# File 'ext/rubysl/zlib/zlib.c', line 1197

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

#total_in ⇒ Object

Returns the total bytes of the input data to the stream. FIXME



1159
1160
1161
1162
1163
 
# File 'ext/rubysl/zlib/zlib.c', line 1159

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

#total_out ⇒ Object

Returns the total bytes of the output data from the stream. FIXME



1168
1169
1170
1171
1172
 
# File 'ext/rubysl/zlib/zlib.c', line 1168

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