Class: Struct

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

Overview

A Struct is a convenient way to bundle a number of attributes together, using accessor methods, without having to write an explicit class.

The Struct class generates new subclasses that hold a set of members and their values. For each member a reader and writer method is created similar to Module#attr_accessor.

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

dave = Customer.new("Dave", "123 Main")
dave.name     #=> "Dave"
dave.greeting #=> "Hello Dave!"

See Struct::new for further examples of creating struct subclasses and instances.

In the method descriptions that follow a “member” parameter refers to a struct member which is either a quoted string ("name") or a Symbol (:name).

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, #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, #group_by, #include?, #inject, #lazy, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #slice_before, #sort, #sort_by, #take, #take_while, #zip

Constructor Details

#initialize ⇒ Object 



445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
 
# File 'struct.c', line 445

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:



394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
 
# File 'struct.c', line 394

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

    rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
    name = argv[0];
    if (SYMBOL_P(name)) {
	name = Qnil;
    }
    else {
	--argc;
	++argv;
    }
    rest = rb_ary_tmp_new(argc);
    for (i=0; i<argc; i++) {
	id = rb_to_id(argv[i]);
	RARRAY_ASET(rest, i, ID2SYM(id));
	rb_ary_set_len(rest, i+1);
    }
    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) 


947
948
949
950
951
952
953
954
955
956
957
958
 
# File 'struct.c', line 947

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:



756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
 
# File 'struct.c', line 756

VALUE
rb_struct_aref(VALUE s, VALUE idx)
{
    long i;

    if (RB_TYPE_P(idx, T_SYMBOL)) {
	return rb_struct_aref_id(s, SYM2ID(idx));
    }
    else if (RB_TYPE_P(idx, T_STRING)) {
	ID id = rb_check_id(&idx);
	if (!id) {
	    rb_name_error_str(idx, "no member '%"PRIsVALUE"' in struct",
			      QUOTE(idx));
	}
	return rb_struct_aref_id(s, id);
    }

    i = NUM2LONG(idx);
    if (i < 0) i = RSTRUCT_LEN(s) + i;
    if (i < 0)
        rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)",
		 i, RSTRUCT_LEN(s));
    if (RSTRUCT_LEN(s) <= i)
        rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)",
		 i, RSTRUCT_LEN(s));
    return RSTRUCT_GET(s, i);
}

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

Attribute Assignment—Sets the value of the given struct member or the member at the given index. Raises NameError if the name 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:



826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
 
# File 'struct.c', line 826

VALUE
rb_struct_aset(VALUE s, VALUE idx, VALUE val)
{
    long i;

    if (RB_TYPE_P(idx, T_SYMBOL)) {
	return rb_struct_aset_id(s, SYM2ID(idx), val);
    }
    if (RB_TYPE_P(idx, T_STRING)) {
	ID id = rb_check_id(&idx);
	if (!id) {
	    rb_name_error_str(idx, "no member '%"PRIsVALUE"' in struct",
			      QUOTE(idx));
	}
	return rb_struct_aset_id(s, id, val);
    }

    i = NUM2LONG(idx);
    if (i < 0) i = RSTRUCT_LEN(s) + i;
    if (i < 0) {
        rb_raise(rb_eIndexError, "offset %ld too small for struct(size:%ld)",
		 i, RSTRUCT_LEN(s));
    }
    if (RSTRUCT_LEN(s) <= i) {
        rb_raise(rb_eIndexError, "offset %ld too large for struct(size:%ld)",
		 i, RSTRUCT_LEN(s));
    }
    rb_struct_modify(s);
    RSTRUCT_SET(s, i, val);
    return val;
}

#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) 


548
549
550
551
552
553
554
555
556
557
558
 
# File 'struct.c', line 548

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) 


579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
 
# File 'struct.c', line 579

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) 


1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
 
# File 'struct.c', line 1011

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).

Returns:



967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
 
# File 'struct.c', line 967

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 ⇒ Object

:nodoc:



706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
 
# File 'struct.c', line 706

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:



657
658
659
660
661
 
# File 'struct.c', line 657

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:



1036
1037
1038
1039
1040
 
# File 'struct.c', line 1036

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:



83
84
85
86
87
 
# File 'struct.c', line 83

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:



898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
 
# File 'struct.c', line 898

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:



1036
1037
1038
1039
1040
 
# File 'struct.c', line 1036

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:



675
676
677
678
679
 
# File 'struct.c', line 675

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:



692
693
694
695
696
697
698
699
700
701
702
703
 
# File 'struct.c', line 692

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:



675
676
677
678
679
 
# File 'struct.c', line 675

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:



878
879
880
881
882
 
# File 'struct.c', line 878

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