Class: Struct
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
-
.new ⇒ Object
The first two forms are used to create a new Struct subclass
class_name
that can contain a value for eachmember_name
.
Instance Method Summary collapse
-
#==(other) ⇒ Boolean
Equality—Returns
true
ifother
has the same struct subclass and has equal member values (according to Object#==). -
#[] ⇒ Object
Attribute Reference—Returns the value of the given struct
member
or the member at the givenindex
. -
#[]= ⇒ Object
Attribute Assignment—Sets the value of the given struct
member
or the member at the givenindex
. -
#each ⇒ Object
Yields the value of each struct member in order.
-
#each_pair ⇒ Object
Yields the name and value of each struct member in order.
-
#eql?(other) ⇒ Boolean
Hash equality—
other
andstruct
refer to the same hash key if they have the same struct subclass and have equal member values (according to Object#eql?). -
#hash ⇒ Fixnum
Returns a hash value based on this struct’s contents (see Object#hash).
- #initialize ⇒ Object constructor
-
#initialize_copy ⇒ Object
:nodoc:.
-
#inspect ⇒ Object
(also: #to_s)
Describe the contents of this struct in a string.
-
#length ⇒ Object
Returns the number of struct members.
-
#members ⇒ Array
Returns the struct members as an array of symbols:.
-
#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). -
#size ⇒ Object
Returns the number of struct members.
-
#to_a ⇒ Object
Returns the values for this struct as an Array.
-
#to_h ⇒ Hash
Returns a Hash containing the names and values for the struct’s members.
-
#values ⇒ Object
Returns the values for this struct as an Array.
-
#values_at(selector, ...) ⇒ Array
Returns the struct member values for each
selector
as an Array.
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
437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 |
# File 'struct.c', line 437
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">
386 387 388 389 390 391 392 393 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 |
# File 'struct.c', line 386
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
939 940 941 942 943 944 945 946 947 948 949 950 |
# File 'struct.c', line 939
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"
748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 |
# File 'struct.c', line 748
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"
818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 |
# File 'struct.c', line 818
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
540 541 542 543 544 545 546 547 548 549 550 |
# File 'struct.c', line 540
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
571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 |
# File 'struct.c', line 571
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?).
1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 |
# File 'struct.c', line 1003
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).
959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 |
# File 'struct.c', line 959
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:
698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 |
# File 'struct.c', line 698
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.
649 650 651 652 653 |
# File 'struct.c', line 649
static VALUE
rb_struct_inspect(VALUE s)
{
return rb_exec_recursive(inspect_struct, s, 0);
}
|
#length ⇒ Fixnum #size ⇒ Fixnum
1028 1029 1030 1031 1032 |
# File 'struct.c', line 1028
static VALUE
rb_struct_size(VALUE s)
{
return LONG2FIX(RSTRUCT_LEN(s));
}
|
#members ⇒ Array
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]
890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 |
# File 'struct.c', line 890
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
1028 1029 1030 1031 1032 |
# File 'struct.c', line 1028
static VALUE
rb_struct_size(VALUE s)
{
return LONG2FIX(RSTRUCT_LEN(s));
}
|
#to_a ⇒ Array #values ⇒ Array
667 668 669 670 671 |
# File 'struct.c', line 667
static VALUE
rb_struct_to_a(VALUE s)
{
return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
}
|
#to_h ⇒ Hash
684 685 686 687 688 689 690 691 692 693 694 695 |
# File 'struct.c', line 684
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
667 668 669 670 671 |
# File 'struct.c', line 667
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]
870 871 872 873 874 |
# File 'struct.c', line 870
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);
}
|