Class: LibBin::Structure::Str

Inherits:
Scalar
  • Object
show all
Defined in:
lib/libbin/data_types.rb,
ext/libbin/data_types.c

Overview

A string type, can be NULL terminated or have an arbitrary length.

Class Method Summary collapse

Class Method Details

.align ⇒ Integer

Returns the alignement of the underlying character type.

Returns:

  • (Integer) 


361
362
363
364
 
# File 'ext/libbin/data_types.c', line 361

static VALUE cStr_align(VALUE self) {
  (void)self;
  return INT2FIX(sizeof(char));
}

.convert(input, output, input_big = LibBin::default_big?, output_big = !input_big, parent = nil, index = nil, length = nil) ⇒ String

Convert a string field by loading it from input, dumping it to output, and returning the loaded field.

Parameters:

  • input (IO) —

    the stream to load the field from.

  • output (IO) —

    the stream to dump the field to.

  • input_big (Boolean) (defaults to: LibBin::default_big?) —

    the endianness of input

  • output_big (Boolean) (defaults to: !input_big) —

    the endianness of output.

  • parent (Structure) (defaults to: nil) —

    ignored.

  • index (Integer) (defaults to: nil) —

    ignored.

  • length (Integer) (defaults to: nil) —

    if given the length of the string to reqd. Else the string is considered NULL terminated.

Returns:

  • (String) —

    the Ruby representation of the string.



438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
 
# File 'ext/libbin/data_types.c', line 438

static VALUE cStr_convert(int argc, VALUE* argv, VALUE self) {
  (void)self;
  VALUE input;
  VALUE output;
  VALUE length;
  rb_scan_args(argc, argv, "25", &input, &output, NULL, NULL, NULL, NULL, &length);
  VALUE str;
  if (NIL_P(length))
    str = rb_funcall(input, rb_intern("readline"), 1, rb_str_new_static("", 1));
  else {
    str = rb_funcall(input, id_read, 1, length);
    if (NIL_P(str) || RSTRING_LEN(str) < NUM2LONG(length))
      rb_raise(rb_eRuntimeError,
        "could not read enough data: got %ld needed %zu", RSTRING_LEN(str), NUM2LONG(length));
  }
  rb_funcall(output, id_write, 1, str);
  return str;
}

.dump(value, output, output_big = LibBin::default_big?, parent = nil, index = nil, length = nil) ⇒ nil

Dump a string field to output.

Parameters:

  • value (Numeric, Array<Numeric>) —

    the Ruby representation of the string.

  • output (IO) —

    the stream to dump the field to.

  • output_big (Boolean) (defaults to: LibBin::default_big?) —

    the endianness of output.

  • parent (Structure) (defaults to: nil) —

    ignored.

  • index (Integer) (defaults to: nil) —

    ignored.

  • length (Integer) (defaults to: nil) —

    if given the length of the string to dump. Else the length is the size of the string.

Returns:

  • (nil) 


413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
 
# File 'ext/libbin/data_types.c', line 413

static VALUE cStr_dump(int argc, VALUE* argv, VALUE self) {
  (void)self;
  VALUE value;
  VALUE output;
  VALUE length;
  rb_scan_args(argc, argv, "24", &value, &output, NULL, NULL, NULL, &length);
  if (NIL_P(length))
    rb_funcall(output, id_write, 1, value);
  else {
    long l = NUM2LONG(length);
    long vl = RSTRING_LEN(value);
    VALUE str;
    if (vl > l)
      str = rb_str_new(RSTRING_PTR(value), l);
    else {
      str = rb_str_buf_new(l);
      rb_str_cat(str, RSTRING_PTR(value), vl);
      for (long i = 0; i < l - vl; i++)
        rb_str_cat(str, "", 1);
    }
    rb_funcall(output, id_write, 1, str);
  }
  return Qnil;
}

.load(input, input_big = LibBin::default_big?, parent = nil, index = nil, length = nil) ⇒ String

Load a string field from input, and return it.

Parameters:

  • input (IO) —

    the stream to load the field from.

  • input_big (Boolean) (defaults to: LibBin::default_big?) —

    the endianness of input

  • parent (Structure) (defaults to: nil) —

    ignored.

  • index (Integer) (defaults to: nil) —

    ignored.

  • length (Integer) (defaults to: nil) —

    if given the length of the string. Else the string is considered NULL terminated.

Returns:

  • (String) —

    the Ruby representation of the string.



397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
 
# File 'ext/libbin/data_types.c', line 397

static VALUE cStr_load(int argc, VALUE* argv, VALUE self) {
  (void)self;
  VALUE input;
  VALUE length;
  rb_scan_args(argc, argv, "14", &input, NULL, NULL, NULL, &length);
  if (NIL_P(length))
    return rb_funcall(input, rb_intern("readline"), 1, rb_str_new_static("", 1));
  else {
    VALUE str = rb_funcall(input, id_read, 1, length);
    if (NIL_P(str) || RSTRING_LEN(str) < NUM2LONG(length))
      rb_raise(rb_eRuntimeError,
        "could not read enough data: got %ld needed %zu", RSTRING_LEN(str), NUM2LONG(length));
    return str;
  }
}

.shape(value, offset = 0, parent = nil, index = nil, kind = DataShape, length = nil) ⇒ kind

Returns the shape of a string field

Parameters:

  • value (Object) —

    ignored.

  • offset (Integer) (defaults to: 0) —

    start of the shape.

  • parent (Structure) (defaults to: nil) —

    ignored.

  • index (Integer) (defaults to: nil) —

    ignored.

  • kind (Class) (defaults to: DataShape) —

    shape class. Will be instantiated through new with the offset and offset + sizeof($3) * length - 1.

  • length (Integer) (defaults to: nil) —

    if given the length of the string to consider. Else the length is the size of the string.

Returns:

  • (kind) —

    a new instance of kind



377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
 
# File 'ext/libbin/data_types.c', line 377

static VALUE cStr_shape(int argc, VALUE* argv, VALUE self) {
  (void)self;
  VALUE value;
  VALUE previous_offset;
  VALUE kind;
  VALUE length;
  rb_scan_args(argc, argv, "15", &value, &previous_offset, NULL, NULL, &kind, &length);
  if (NIL_P(previous_offset))
    previous_offset = INT2FIX(0);
  if (NIL_P(kind))
    kind = cDataShape;
  if (NIL_P(length)) {
    VALUE args[] = { previous_offset, LL2NUM(NUM2LL(previous_offset) - 1 + RSTRING_LEN(value)) };
    return rb_class_new_instance(2, args, kind);
  } else {
    VALUE args[] = { previous_offset, LL2NUM(NUM2LL(previous_offset) - 1 + NUM2LL(length)) };
    return rb_class_new_instance(2, args, kind);
  }
}

.size(value, offset = 0, parent = nil, index = nil, length = nil) ⇒ Integer

Returns the size of a string. the size of the string.

Parameters:

  • value (Object) —

    string to dump.

  • offset (Integer) (defaults to: 0) —

    ignored.

  • parent (Structure) (defaults to: nil) —

    ignored.

  • index (Integer) (defaults to: nil) —

    ignored.

  • length (Integer) (defaults to: nil) —

    if given the length of the vector. Else

Returns:

  • (Integer) —

    the size of the string or sizeof(char) * length.



366
367
368
369
370
371
372
373
374
375
 
# File 'ext/libbin/data_types.c', line 366

static VALUE cStr_size(int argc, VALUE* argv, VALUE self) {
  (void)self;
  VALUE value;
  VALUE length;
  rb_scan_args(argc, argv, "14", &value, NULL, NULL, NULL, &length);
  if (RTEST(length))
    return length;
  else
    return rb_funcall(value, rb_intern("bytesize"), 0);
}