Class: Struct

Inherits:
Object show all
Includes:
Enumerable
Defined in:
struct.c

Constant Summary collapse

Tms =

for the backward compatibility

rb_cProcessTms

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #chunk, #chunk_while, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #find, #find_all, #find_index, #first, #flat_map, #grep, #grep_v, #group_by, #include?, #inject, #lazy, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #slice_after, #slice_before, #slice_when, #sort, #sort_by, #take, #take_while, #zip

Constructor Details

#initialize(*args) ⇒ Object 



544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
 
# File 'struct.c', line 544

static VALUE
rb_struct_initialize_m(int argc, const VALUE *argv, VALUE self)
{
    VALUE klass = rb_obj_class(self);
    long i, n;

    rb_struct_modify(self);
    n = num_members(klass);
    if (n < argc) {
	rb_raise(rb_eArgError, "struct size differs");
    }
    for (i=0; i<argc; i++) {
	RSTRUCT_SET(self, i, argv[i]);
    }
    if (n > argc) {
	rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self)+argc, n-argc);
    }
    return Qnil;
}

Class Method Details

.new([class_name][, member_name]) ⇒ StructClass .new([class_name][, member_name]) {|StructClass| ... } ⇒ StructClass .new(value, ...) ⇒ Object .[](value, ...) ⇒ Object

The first two forms are used to create a new Struct subclass class_name that can contain a value for each member_name. This subclass can be used to create instances of the structure like any other Class.

If the class_name is omitted an anonymous structure class will be created. Otherwise, the name of this struct will appear as a constant in class Struct, so it must be unique for all Structs in the system and must start with a capital letter. Assigning a structure class to a constant also gives the class the name of the constant.

# Create a structure with a name under Struct
Struct.new("Customer", :name, :address)
#=> Struct::Customer
Struct::Customer.new("Dave", "123 Main")
#=> #<struct Struct::Customer name="Dave", address="123 Main">

If a block is given it will be evaluated in the context of StructClass, passing the created class as a parameter:

Customer = Struct.new(:name, :address) do
  def greeting
    "Hello #{name}!"
  end
end
Customer.new("Dave", "123 Main").greeting  # => "Hello Dave!"

This is the recommended way to customize a struct. Subclassing an anonymous struct creates an extra anonymous class that will never be used.

The last two forms create a new instance of a struct subclass. The number of value parameters must be less than or equal to the number of attributes defined for the structure. Unset parameters default to nil. Passing more parameters than number of attributes will raise an ArgumentError.

# Create a structure named by its constant
Customer = Struct.new(:name, :address)
#=> Customer
Customer.new("Dave", "123 Main")
#=> #<struct Customer name="Dave", address="123 Main">

Overloads:

  • .new([class_name][, member_name]) ⇒ StructClass

    Returns:

    • (StructClass)
  • .new([class_name][, member_name]) {|StructClass| ... } ⇒ StructClass

    Yields:

    • (StructClass)

    Returns:

    • (StructClass)
  • .new(value, ...) ⇒ Object

    Returns:

  • .[](value, ...) ⇒ Object

    Returns:



486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
 
# File 'struct.c', line 486

static VALUE
rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
{
    VALUE name, rest;
    long i;
    VALUE st;
    st_table *tbl;

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    name = argv[0];
    if (SYMBOL_P(name)) {
	name = Qnil;
    }
    else {
	--argc;
	++argv;
    }
    rest = rb_ident_hash_new();
    RBASIC_CLEAR_CLASS(rest);
    tbl = RHASH_TBL(rest);
    for (i=0; i<argc; i++) {
	VALUE mem = rb_to_symbol(argv[i]);
	if (st_insert(tbl, mem, Qtrue)) {
	    rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem);
	}
    }
    rest = rb_hash_keys(rest);
    st_clear(tbl);
    RBASIC_CLEAR_CLASS(rest);
    OBJ_FREEZE_RAW(rest);
    if (NIL_P(name)) {
	st = anonymous_struct(klass);
    }
    else {
	st = new_struct(name, klass);
    }
    setup_struct(st, rest);
    if (rb_block_given_p()) {
	rb_mod_module_eval(0, 0, st);
    }

    return st;
}

Instance Method Details

#==(other) ⇒ Boolean

Equality—Returns true if other has the same struct subclass and has equal member values (according to Object#==).

Customer = Struct.new(:name, :address, :zip)
joe   = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joejr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
jane  = Customer.new("Jane Doe", "456 Elm, Anytown NC", 12345)
joe == joejr   #=> true
joe == jane    #=> false

Returns:

  • (Boolean) 


1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
 
# File 'struct.c', line 1035

static VALUE
rb_struct_equal(VALUE s, VALUE s2)
{
    if (s == s2) return Qtrue;
    if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse;
    if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse;
    if (RSTRUCT_LEN(s) != RSTRUCT_LEN(s2)) {
	rb_bug("inconsistent struct"); /* should never happen */
    }

    return rb_exec_recursive_paired(recursive_equal, s, s2, s2);
}

#[](member) ⇒ Object #[](index) ⇒ Object

Attribute Reference—Returns the value of the given struct member or the member at the given index. Raises NameError if the member does not exist and IndexError if the index is out of range.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)

joe["name"]   #=> "Joe Smith"
joe[:name]    #=> "Joe Smith"
joe[0]        #=> "Joe Smith"

Overloads:



892
893
894
895
896
897
898
 
# File 'struct.c', line 892

VALUE
rb_struct_aref(VALUE s, VALUE idx)
{
    int i = rb_struct_pos(s, &idx);
    if (i < 0) invalid_struct_pos(s, idx);
    return RSTRUCT_GET(s, i);
}

#[]=(member) ⇒ Object #[]=(index) ⇒ Object

Attribute Assignment—Sets the value of the given struct member or the member at the given index. Raises NameError if the member does not exist and IndexError if the index is out of range.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)

joe["name"] = "Luke"
joe[:zip]   = "90210"

joe.name   #=> "Luke"
joe.zip    #=> "90210"

Overloads:



919
920
921
922
923
924
925
926
927
 
# File 'struct.c', line 919

VALUE
rb_struct_aset(VALUE s, VALUE idx, VALUE val)
{
    int i = rb_struct_pos(s, &idx);
    if (i < 0) invalid_struct_pos(s, idx);
    rb_struct_modify(s);
    RSTRUCT_SET(s, i, val);
    return val;
}

#dig(key, ...) ⇒ Object

Extracts the nested value specified by the sequence of idx objects by calling dig at each step, returning nil if any intermediate step is nil.

klass = Struct.new(:a)
o = klass.new(klass.new({b: [1, 2, 3]}))

o.dig(:a, :a, :b, 0)              #=> 1
o.dig(:b, 0)                      #=> nil

Returns:



1147
1148
1149
1150
1151
1152
1153
1154
1155
 
# File 'struct.c', line 1147

static VALUE
rb_struct_dig(int argc, VALUE *argv, VALUE self)
{
    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    self = rb_struct_lookup(self, *argv);
    if (!--argc) return self;
    ++argv;
    return rb_obj_dig(argc, argv, self, Qnil);
}

#each {|obj| ... } ⇒ Object #each ⇒ Object

Yields the value of each struct member in order. If no block is given an enumerator is returned.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each {|x| puts(x) }

Produces:

Joe Smith
123 Maple, Anytown NC
12345

Overloads:

  • #each {|obj| ... } ⇒ Object

    Yields:

    • (obj) 


647
648
649
650
651
652
653
654
655
656
657
 
# File 'struct.c', line 647

static VALUE
rb_struct_each(VALUE s)
{
    long i;

    RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
    for (i=0; i<RSTRUCT_LEN(s); i++) {
	rb_yield(RSTRUCT_GET(s, i));
    }
    return s;
}

#each_pair {|sym, obj| ... } ⇒ Object #each_pair ⇒ Object

Yields the name and value of each struct member in order. If no block is given an enumerator is returned.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each_pair {|name, value| puts("#{name} => #{value}") }

Produces:

name => Joe Smith
address => 123 Maple, Anytown NC
zip => 12345

Overloads:

  • #each_pair {|sym, obj| ... } ⇒ Object

    Yields:

    • (sym, obj) 


678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
 
# File 'struct.c', line 678

static VALUE
rb_struct_each_pair(VALUE s)
{
    VALUE members;
    long i;

    RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
    members = rb_struct_members(s);
    if (rb_block_arity() > 1) {
	for (i=0; i<RSTRUCT_LEN(s); i++) {
	    VALUE key = rb_ary_entry(members, i);
	    VALUE value = RSTRUCT_GET(s, i);
	    rb_yield_values(2, key, value);
	}
    }
    else {
	for (i=0; i<RSTRUCT_LEN(s); i++) {
	    VALUE key = rb_ary_entry(members, i);
	    VALUE value = RSTRUCT_GET(s, i);
	    rb_yield(rb_assoc_new(key, value));
	}
    }
    return s;
}

#eql?(other) ⇒ Boolean

Hash equality—other and struct refer to the same hash key if they have the same struct subclass and have equal member values (according to Object#eql?).

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
 
# File 'struct.c', line 1101

static VALUE
rb_struct_eql(VALUE s, VALUE s2)
{
    if (s == s2) return Qtrue;
    if (!RB_TYPE_P(s2, T_STRUCT)) return Qfalse;
    if (rb_obj_class(s) != rb_obj_class(s2)) return Qfalse;
    if (RSTRUCT_LEN(s) != RSTRUCT_LEN(s2)) {
	rb_bug("inconsistent struct"); /* should never happen */
    }

    return rb_exec_recursive_paired(recursive_eql, s, s2, s2);
}

#hash ⇒ Fixnum

Returns a hash value based on this struct’s contents (see Object#hash).

See also Object#hash.

Returns:



1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
 
# File 'struct.c', line 1057

static VALUE
rb_struct_hash(VALUE s)
{
    long i, len;
    st_index_t h;
    VALUE n;
    const VALUE *ptr;

    h = rb_hash_start(rb_hash(rb_obj_class(s)));
    ptr = RSTRUCT_CONST_PTR(s);
    len = RSTRUCT_LEN(s);
    for (i = 0; i < len; i++) {
	n = rb_hash(ptr[i]);
	h = rb_hash_uint(h, NUM2LONG(n));
    }
    h = rb_hash_end(h);
    return INT2FIX(h);
}

#initialize_copy(s) ⇒ Object

:nodoc:



805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
 
# File 'struct.c', line 805

VALUE
rb_struct_init_copy(VALUE copy, VALUE s)
{
    long i, len;

    if (!OBJ_INIT_COPY(copy, s)) return copy;
    if (RSTRUCT_LEN(copy) != RSTRUCT_LEN(s)) {
	rb_raise(rb_eTypeError, "struct size mismatch");
    }

    for (i=0, len=RSTRUCT_LEN(copy); i<len; i++) {
	RSTRUCT_SET(copy, i, RSTRUCT_GET(s, i));
    }

    return copy;
}

#to_s ⇒ String #inspect ⇒ String Also known as: to_s

Describe the contents of this struct in a string.

Overloads:



756
757
758
759
760
 
# File 'struct.c', line 756

static VALUE
rb_struct_inspect(VALUE s)
{
    return rb_exec_recursive(inspect_struct, s, 0);
}

#length ⇒ Fixnum #size ⇒ Fixnum

Returns the number of struct members.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.length   #=> 3

Overloads:



1126
1127
1128
1129
1130
 
# File 'struct.c', line 1126

static VALUE
rb_struct_size(VALUE s)
{
    return LONG2FIX(RSTRUCT_LEN(s));
}

#members ⇒ Array

Returns the struct members as an array of symbols:

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.members   #=> [:name, :address, :zip]

Returns:



198
199
200
201
202
 
# File 'struct.c', line 198

static VALUE
rb_struct_members_m(VALUE obj)
{
    return rb_struct_s_members_m(rb_obj_class(obj));
}

#select {|i| ... } ⇒ Array #select ⇒ Object

Yields each member value from the struct to the block and returns an Array containing the member values from the struct for which the given block returns a true value (equivalent to Enumerable#select).

Lots = Struct.new(:a, :b, :c, :d, :e, :f)
l = Lots.new(11, 22, 33, 44, 55, 66)
l.select {|v| (v % 2).zero? }   #=> [22, 44, 66]

Overloads:

  • #select {|i| ... } ⇒ Array

    Yields:

    • (i)

    Returns:



986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
 
# File 'struct.c', line 986

static VALUE
rb_struct_select(int argc, VALUE *argv, VALUE s)
{
    VALUE result;
    long i;

    rb_check_arity(argc, 0, 0);
    RETURN_SIZED_ENUMERATOR(s, 0, 0, struct_enum_size);
    result = rb_ary_new();
    for (i = 0; i < RSTRUCT_LEN(s); i++) {
	if (RTEST(rb_yield(RSTRUCT_GET(s, i)))) {
	    rb_ary_push(result, RSTRUCT_GET(s, i));
	}
    }

    return result;
}

#length ⇒ Fixnum #size ⇒ Fixnum

Returns the number of struct members.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.length   #=> 3

Overloads:



1126
1127
1128
1129
1130
 
# File 'struct.c', line 1126

static VALUE
rb_struct_size(VALUE s)
{
    return LONG2FIX(RSTRUCT_LEN(s));
}

#to_a ⇒ Array #values ⇒ Array

Returns the values for this struct as an Array.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.to_a[1]   #=> "123 Maple, Anytown NC"

Overloads:



774
775
776
777
778
 
# File 'struct.c', line 774

static VALUE
rb_struct_to_a(VALUE s)
{
    return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
}

#to_h ⇒ Hash

Returns a Hash containing the names and values for the struct’s members.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.to_h[:address]   #=> "123 Maple, Anytown NC"

Returns:



791
792
793
794
795
796
797
798
799
800
801
802
 
# File 'struct.c', line 791

static VALUE
rb_struct_to_h(VALUE s)
{
    VALUE h = rb_hash_new();
    VALUE members = rb_struct_members(s);
    long i;

    for (i=0; i<RSTRUCT_LEN(s); i++) {
	rb_hash_aset(h, rb_ary_entry(members, i), RSTRUCT_GET(s, i));
    }
    return h;
}

#to_a ⇒ Array #values ⇒ Array

Returns the values for this struct as an Array.

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.to_a[1]   #=> "123 Maple, Anytown NC"

Overloads:



774
775
776
777
778
 
# File 'struct.c', line 774

static VALUE
rb_struct_to_a(VALUE s)
{
    return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
}

#values_at(selector, ...) ⇒ Array

Returns the struct member values for each selector as an Array. A selector may be either an Integer offset or a Range of offsets (as in Array#values_at).

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.values_at 0, 2 #=> ["Joe Smith", 12345]

Returns:



966
967
968
969
970
 
# File 'struct.c', line 966

static VALUE
rb_struct_values_at(int argc, VALUE *argv, VALUE s)
{
    return rb_get_values_at(s, RSTRUCT_LEN(s), argc, argv, struct_entry);
}