Spec-Zone.ru › Ruby 2.3

класс Zlib::GzipReader

Родитель:
Zlib::GzipFile
Включенные модули:
Enumerable

Zlib::GzipReader — это класс для чтения сжатого gzip файлом. GzipReader следует использовать как объект типа IO или подобный ему.

Zlib::GzipReader.open('hoge.gz') {|gz|
  print gz.read
}

File.open('hoge.gz') do |f|
  gz = Zlib::GzipReader.new(f)
  print gz.read
  gz.close
end

Методы

Следующие методы в Zlib::GzipReader аналогичны своим аналогам в IO, но они генерируют исключение Zlib::Error или Zlib::GzipFile::Error, если в gzip файле обнаружена ошибка.

  • each

  • each_line

  • each_byte

  • gets

  • getc

  • lineno

  • lineno=

  • read

  • readchar

  • readline

  • readlines

  • ungetc

Будьте внимательны к подписи gzip файла. Файл gzip содержит контрольную сумму предварительно сжатых данных в своей подписи. GzipReader проверяет все несжатые данные на соответствие этой контрольной сумме в следующих случаях и, если проверка не пройдена, генерирует исключение Zlib::GzipFile::NoFooter, Zlib::GzipFile::CRCError, или Zlib::GzipFile::LengthError.

  • Когда запрос на чтение выходит за пределы файла (конец сжатых данных). То есть, когда #read, #gets или другие методы чтения возвращают nil.

  • Когда вызывается метод Zlib::GzipFile#close после того, как объект достигнет конца файла.

  • Когда вызывается метод #unused после того, как объект достигнет конца файла.

Остальные методы адекватно описаны в своей собственной документации.

Публичные методы класса

Zlib::GzipReader.new(io, options = {}) Показать исходный код 
static VALUE
rb_gzreader_initialize(int argc, VALUE *argv, VALUE obj)
{
    VALUE io, opt = Qnil;
    struct gzfile *gz;
    int err;

    TypedData_Get_Struct(obj, struct gzfile, &gzfile_data_type, gz);
    rb_scan_args(argc, argv, "1:", &io, &opt);

    /* this is undocumented feature of zlib */
    err = inflateInit2(&gz->z.stream, -MAX_WBITS);
    if (err != Z_OK) {
        raise_zlib_error(err, gz->z.stream.msg);
    }
    gz->io = io;
    ZSTREAM_READY(&gz->z);
    gzfile_read_header(gz);
    rb_gzfile_ecopts(gz, opt);

    if (rb_respond_to(io, id_path)) {
        gz->path = rb_funcall(gz->io, id_path, 0);
        rb_define_singleton_method(obj, "path", rb_gzfile_path, 0);
    }

    return obj;
}

Создает объект GzipReader, связанный с io. Объект GzipReader считывает данные gzip из io, и обрабатывает/распаковывает их. Объект io должен иметь метод read, который ведет себя так же, как метод IO#read.

Хеш-таблица options может быть использована для установки кодировки данных. :external_encoding, :internal_encoding и :encoding могут быть установлены как и в IO.new.

Если заголовок gzip файла некорректен, генерируется исключение Zlib::GzipFile::Error.

Zlib::GzipReader.open(filename) {|gz| ... } Показать исходный код 
static VALUE
rb_gzreader_s_open(int argc, VALUE *argv, VALUE klass)
{
    return gzfile_s_open(argc, argv, klass, "rb");
}

Открывает файл, указанный по filename, как gzip-файл и возвращает объект GzipReader, связанный с этим файлом. Более подробные сведения об этом методе содержатся в ::new и ZLib::GzipFile.wrap.

Общедоступные методы экземпляров

bytes() Показать исходный код 
static VALUE
rb_gzreader_bytes(VALUE obj)
{
    rb_warn("Zlib::GzipReader#bytes is deprecated; use #each_byte instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(obj, ID2SYM(rb_intern("each_byte")), 0, 0);
    return rb_gzreader_each_byte(obj);
}

Это устаревшее псевдоним для each_byte.

each(*args) Показать исходный код 
static VALUE
rb_gzreader_each(int argc, VALUE *argv, VALUE obj)
{
    VALUE str;

    RETURN_ENUMERATOR(obj, 0, 0);

    while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
        rb_yield(str);
    }
    return obj;
}

См. документацию Zlib::GzipReader для описания.

each_byte() Показать исходный код 
static VALUE
rb_gzreader_each_byte(VALUE obj)
{
    VALUE c;

    RETURN_ENUMERATOR(obj, 0, 0);

    while (!NIL_P(c = rb_gzreader_getbyte(obj))) {
        rb_yield(c);
    }
    return Qnil;
}

См. документацию Zlib::GzipReader для описания.

each_char() Показать исходный код 
static VALUE
rb_gzreader_each_char(VALUE obj)
{
    VALUE c;

    RETURN_ENUMERATOR(obj, 0, 0);

    while (!NIL_P(c = rb_gzreader_getc(obj))) {
        rb_yield(c);
    }
    return Qnil;
}

См. документацию Zlib::GzipReader для описания.

each_line(*args) Показать исходный код 
static VALUE
rb_gzreader_each(int argc, VALUE *argv, VALUE obj)
{
    VALUE str;

    RETURN_ENUMERATOR(obj, 0, 0);

    while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
        rb_yield(str);
    }
    return obj;
}

См. документацию Zlib::GzipReader для описания.

eof() Показать исходный код 
static VALUE
rb_gzfile_eof_p(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    return GZFILE_IS_FINISHED(gz) ? Qtrue : Qfalse;
}

Возвращает true или false, если поток достиг конца.

eof?() Показать исходный код 
static VALUE
rb_gzfile_eof_p(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    return GZFILE_IS_FINISHED(gz) ? Qtrue : Qfalse;
}

Возвращает true или false, если поток достиг конца.

external_encoding() Показать исходный код 
static VALUE
rb_gzreader_external_encoding(VALUE self)
{
    return rb_enc_from_encoding(get_gzfile(self)->enc);
}

См. документацию Zlib::GzipReader для описания.

getbyte() Показать исходный код 
static VALUE
rb_gzreader_getbyte(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    VALUE dst;

    dst = gzfile_read(gz, 1);
    if (!NIL_P(dst)) {
        dst = INT2FIX((unsigned int)(RSTRING_PTR(dst)[0]) & 0xff);
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

getc() Показать исходный код 
static VALUE
rb_gzreader_getc(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);

    return gzfile_getc(gz);
}

См. документацию Zlib::GzipReader для описания.

gets(*args) Показать исходный код 
static VALUE
rb_gzreader_gets(int argc, VALUE *argv, VALUE obj)
{
    VALUE dst;
    dst = gzreader_gets(argc, argv, obj);
    if (!NIL_P(dst)) {
        rb_lastline_set(dst);
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

lineno() Показать исходный код 
static VALUE
rb_gzfile_lineno(VALUE obj)
{
    return INT2NUM(get_gzfile(obj)->lineno);
}

Номер строки последней прочитанной строки из этого файла.

lineno=(p1) Показать исходный код 
static VALUE
rb_gzfile_set_lineno(VALUE obj, VALUE lineno)
{
    struct gzfile *gz = get_gzfile(obj);
    gz->lineno = NUM2INT(lineno);
    return lineno;
}

Укажите номер строки последней прочитанной строки из этого файла.

lines(*args) Показать исходный код 
static VALUE
rb_gzreader_lines(int argc, VALUE *argv, VALUE obj)
{
    rb_warn("Zlib::GzipReader#lines is deprecated; use #each_line instead");
    if (!rb_block_given_p())
        return rb_enumeratorize(obj, ID2SYM(rb_intern("each_line")), argc, argv);
    return rb_gzreader_each(argc, argv, obj);
}

Это устаревший псевдоним для each_line.

pos() Показать исходный код 
static VALUE
rb_gzfile_total_out(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    uLong total_out = gz->z.stream.total_out;
    long buf_filled = gz->z.buf_filled;

    if (total_out >= (uLong)buf_filled) {
        return rb_uint2inum(total_out - buf_filled);
    } else {
        return LONG2FIX(-(buf_filled - (long)total_out));
    }
}

Общее количество выведенных байтов.

read(p1 = v1) Показать исходный код 
static VALUE
rb_gzreader_read(int argc, VALUE *argv, VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    VALUE vlen;
    long len;

    rb_scan_args(argc, argv, "01", &vlen);
    if (NIL_P(vlen)) {
        return gzfile_read_all(gz);
    }

    len = NUM2INT(vlen);
    if (len < 0) {
        rb_raise(rb_eArgError, "negative length %ld given", len);
    }
    return gzfile_read(gz, len);
}

См. документацию Zlib::GzipReader для описания.

readbyte() Показать исходный код 
static VALUE
rb_gzreader_readbyte(VALUE obj)
{
    VALUE dst;
    dst = rb_gzreader_getbyte(obj);
    if (NIL_P(dst)) {
        rb_raise(rb_eEOFError, "end of file reached");
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

readchar() Показать исходный код 
static VALUE
rb_gzreader_readchar(VALUE obj)
{
    VALUE dst;
    dst = rb_gzreader_getc(obj);
    if (NIL_P(dst)) {
        rb_raise(rb_eEOFError, "end of file reached");
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

readline(*args) Показать исходный код 
static VALUE
rb_gzreader_readline(int argc, VALUE *argv, VALUE obj)
{
    VALUE dst;
    dst = rb_gzreader_gets(argc, argv, obj);
    if (NIL_P(dst)) {
        rb_raise(rb_eEOFError, "end of file reached");
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

readlines(*args) Показать исходный код 
static VALUE
rb_gzreader_readlines(int argc, VALUE *argv, VALUE obj)
{
    VALUE str, dst;
    dst = rb_ary_new();
    while (!NIL_P(str = gzreader_gets(argc, argv, obj))) {
        rb_ary_push(dst, str);
    }
    return dst;
}

См. документацию Zlib::GzipReader для описания.

readpartial(maxlen [, outbuf]) → string, outbuf Показать исходный код 
static VALUE
rb_gzreader_readpartial(int argc, VALUE *argv, VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    VALUE vlen, outbuf;
    long len;

    rb_scan_args(argc, argv, "11", &vlen, &outbuf);

    len = NUM2INT(vlen);
    if (len < 0) {
        rb_raise(rb_eArgError, "negative length %ld given", len);
    }
    if (!NIL_P(outbuf))
        Check_Type(outbuf, T_STRING);
    return gzfile_readpartial(gz, len, outbuf);
}

Читает не более maxlen байтов из сжатого потока, но блокируется только если у gzipreader нет данных, немедленно доступных. Если присутствует необязательный аргумент outbuf, он должен ссылаться на строку, в которой будут получены данные. Он вызывает EOFError в конце файла.

rewind() Показать исходный код 
static VALUE
rb_gzreader_rewind(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    gzfile_reader_rewind(gz);
    return INT2FIX(0);
}

Сбрасывает позицию указателя файла до точки, созданной объектом GzipReader. Соответствующий объект IO должен отвечать на метод seek.

tell() Показать исходный код 
static VALUE
rb_gzfile_total_out(VALUE obj)
{
    struct gzfile *gz = get_gzfile(obj);
    uLong total_out = gz->z.stream.total_out;
    long buf_filled = gz->z.buf_filled;

    if (total_out >= (uLong)buf_filled) {
        return rb_uint2inum(total_out - buf_filled);
    } else {
        return LONG2FIX(-(buf_filled - (long)total_out));
    }
}

Общее количество выведенных байтов.

ungetbyte(p1) Показать исходный код 
static VALUE
rb_gzreader_ungetbyte(VALUE obj, VALUE ch)
{
    struct gzfile *gz = get_gzfile(obj);
    gzfile_ungetbyte(gz, NUM2CHR(ch));
    return Qnil;
}

См. документацию Zlib::GzipReader для описания.

ungetc(p1) Показать исходный код 
static VALUE
rb_gzreader_ungetc(VALUE obj, VALUE s)
{
    struct gzfile *gz;

    if (FIXNUM_P(s))
        return rb_gzreader_ungetbyte(obj, s);
    gz = get_gzfile(obj);
    StringValue(s);
    if (gz->enc2 && gz->enc2 != rb_ascii8bit_encoding()) {
        s = rb_str_conv_enc(s, rb_enc_get(s), gz->enc2);
    }
    gzfile_ungets(gz, (const Bytef*)RSTRING_PTR(s), RSTRING_LEN(s));
    RB_GC_GUARD(s);
    return Qnil;
}

См. документацию Zlib::GzipReader для описания.

unused() Показать исходный код 
static VALUE
rb_gzreader_unused(VALUE obj)
{
    struct gzfile *gz;
    TypedData_Get_Struct(obj, struct gzfile, &gzfile_data_type, gz);
    return gzfile_reader_get_unused(gz);
}

Возвращает оставшиеся данные, прочитанные для разбора формата gzip, или nil если весь файл gzip ещё не обработан.

Ruby Core © 1993–2017 Yukihiro Matsumoto
Licensed under the Ruby License.
Ruby Standard Library © contributors
Licensed under their own licenses.

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API