Class: Struct
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Enumerable
|
|
Inherits: | Object |
Defined in: | struct.c, process.c, 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 .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
-
Tms =
:Tms
for backward compatibilityAn obsolete name of Process
Class Method Summary
-
.new([class_name] [, member_name]+) ⇒ Struct
constructor
The first two forms are used to create a new
Struct
subclassclass_name
that can contain a value for eachmember_name
.
Instance Method Summary
-
#==(other) ⇒ Boolean
Equality—Returns
true
ifother
has the same struct subclass and has equal member values (according toObject#==
). -
#[](member) ⇒ Object
Attribute Reference—Returns the value of the given struct
member
or the member at the givenindex
. -
#[]=(member, obj) ⇒ Object
Attribute Assignment—Sets the value of the given struct
member
or the member at the givenindex
. -
#to_a ⇒ Array
Alias for #to_a.
- #deconstruct_keys(keys)
-
#dig(key, ...) ⇒ Object
Extracts the nested value specified by the sequence of
key
objects by callingdig
at each step, returningnil
if any intermediate step isnil
. -
#each {|obj| ... } ⇒ Struct
Yields the value of each struct member in order.
-
#each_pair {|sym, obj| ... } ⇒ Struct
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?). -
#filter {|obj| ... } ⇒ Array
(also: #select)
Yields each member value from the struct to the block and returns an
::Array
containing the member values from thestruct
for which the given block returns a true value (equivalent to Enumerable#select). -
#hash ⇒ Integer
Returns a hash value based on this struct’s contents.
- #initialize(*args) constructor
-
#inspect ⇒ String
Alias for #to_s.
-
#length ⇒ Integer
(also: #size)
Returns the number of struct members.
-
#members ⇒ Array
Returns the struct members as an array of symbols:
-
#select {|obj| ... } ⇒ Array
Alias for #filter.
-
#size ⇒ Integer
Alias for #length.
-
#to_a ⇒ Array
(also: #values, #deconstruct)
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. -
#to_s ⇒ String
(also: #inspect)
Returns a description of this struct as a string.
-
#values ⇒ Array
Alias for #to_a.
-
#values_at(selector, ...) ⇒ Array
Returns the struct member values for each
selector
as an::Array
. - #initialize_copy(s) Internal use only
::Enumerable
- Included
#all? | Passes each element of the collection to the given block. |
#any? | Passes each element of the collection to the given block. |
#chain | Returns an enumerator object generated from this enumerator and given enumerables. |
#chunk | Enumerates over the items, chunking them together based on the return value of the block. |
#chunk_while | Creates an enumerator for each chunked elements. |
#collect | Alias for Enumerable#map. |
#collect_concat | Alias for Enumerable#flat_map. |
#count | Returns the number of items in |
#cycle | Calls block for each element of enum repeatedly n times or forever if none or |
#detect | Alias for Enumerable#find. |
#drop | Drops first n elements from enum, and returns rest elements in an array. |
#drop_while | Drops elements up to, but not including, the first element for which the block returns |
#each_cons | Iterates the given block for each array of consecutive <n> elements. |
#each_entry | Calls block once for each element in |
#each_slice | Iterates the given block for each slice of <n> elements. |
#each_with_index | Calls block with two arguments, the item and its index, for each item in enum. |
#each_with_object | Iterates the given block for each element with an arbitrary object given, and returns the initially given object. |
#entries | Alias for Enumerable#to_a. |
#filter | Returns an array containing all elements of |
#filter_map | Returns a new array containing the truthy results (everything except |
#find | Passes each entry in enum to block. |
#find_all | Alias for Enumerable#filter. |
#find_index | Compares each entry in enum with value or passes to block. |
#first | Returns the first element, or the first |
#flat_map | Returns a new array with the concatenated results of running block once for every element in enum. |
#grep | Returns an array of every element in enum for which |
#grep_v | Inverted version of Enumerable#grep. |
#group_by | Groups the collection by result of the block. |
#include? | Alias for Enumerable#member?. |
#inject | Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator. |
#lazy | Returns an |
#map | Returns a new array with the results of running block once for every element in enum. |
#max | Returns the object in enum with the maximum value. |
#max_by | Returns the object in enum that gives the maximum value from the given block. |
#member? | Returns |
#min | Returns the object in enum with the minimum value. |
#min_by | Returns the object in enum that gives the minimum value from the given block. |
#minmax | Returns a two element array which contains the minimum and the maximum value in the enumerable. |
#minmax_by | Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block. |
#none? | Passes each element of the collection to the given block. |
#one? | Passes each element of the collection to the given block. |
#partition | Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest. |
#reduce | Alias for Enumerable#inject. |
#reject | Returns an array for all elements of |
#reverse_each | Builds a temporary array and traverses that array in reverse order. |
#select | Alias for Enumerable#filter. |
#slice_after | Creates an enumerator for each chunked elements. |
#slice_before | Creates an enumerator for each chunked elements. |
#slice_when | Creates an enumerator for each chunked elements. |
#sort | Returns an array containing the items in enum sorted. |
#sort_by | Sorts enum using a set of keys generated by mapping the values in enum through the given block. |
#sum | Returns the sum of elements in an |
#take | Returns first n elements from enum. |
#take_while | Passes elements to the block until the block returns |
#tally | Tallies the collection, i.e., counts the occurrences of each element. |
#to_a | Returns an array containing the items in enum. |
#to_h | Returns the result of interpreting enum as a list of |
#uniq | Returns a new array by removing duplicate values in |
#zip | Takes one element from enum and merges corresponding elements from each args. |
Constructor Details
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">
# 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">
If the optional keyword_init
keyword argument is set to true
, .new
takes keyword arguments instead of normal arguments.
Customer = Struct.new(:name, :address, keyword_init: true)
Customer.new(name: "Dave", address: "123 Main")
#=> #<struct Customer name="Dave", address="123 Main">
If a block is given it will be evaluated in the context of ::Class
, 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
.
Customer = Struct.new(:name, :address)
Customer.new("Dave", "123 Main")
#=> #<struct Customer name="Dave", address="123 Main">
Customer["Dave"]
#=> #<struct Customer name="Dave", address=nil>
# File 'struct.c', line 521
static VALUE rb_struct_s_def(int argc, VALUE *argv, VALUE klass) { VALUE name, rest, keyword_init = Qfalse; 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; } if (RB_TYPE_P(argv[argc-1], T_HASH)) { static ID keyword_ids[1]; if (!keyword_ids[0]) { keyword_ids[0] = rb_intern("keyword_init"); } rb_get_kwargs(argv[argc-1], keyword_ids, 0, 1, &keyword_init); if (keyword_init == Qundef) { keyword_init = Qfalse; } --argc; } 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 (rb_is_attrset_sym(mem)) { rb_raise(rb_eArgError, "invalid struct member: %"PRIsVALUE, mem); } 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); rb_ivar_set(st, id_keyword_init, keyword_init); if (rb_block_given_p()) { rb_mod_module_eval(0, 0, st); } return st; }
#initialize(*args)
[ GitHub ]# File 'struct.c', line 622
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 (argc > 0 && RTEST(rb_struct_s_keyword_init(klass))) { struct struct_hash_set_arg arg; if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) { rb_raise(rb_eArgError, "wrong number of arguments (given %d, expected 0)", argc); } rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), n); arg.self = self; arg.unknown_keywords = Qnil; rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg); if (arg.unknown_keywords != Qnil) { rb_raise(rb_eArgError, "unknown keywords: %s", RSTRING_PTR(rb_ary_join(arg.unknown_keywords, rb_str_new2(", ")))); } } else { 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; }
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
# File 'struct.c', line 1204
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); }
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"
# File 'struct.c', line 1060
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); }
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"
# File 'struct.c', line 1087
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; }
Alias for #to_a.
#deconstruct_keys(keys)
[ GitHub ]# File 'struct.c', line 942
static VALUE rb_struct_deconstruct_keys(VALUE s, VALUE keys) { VALUE h; long i; if (NIL_P(keys)) { return rb_struct_to_h(s); } if (UNLIKELY(!RB_TYPE_P(keys, T_ARRAY))) { rb_raise(rb_eTypeError, "wrong argument type %"PRIsVALUE" (expected Array or nil)", rb_obj_class(keys)); } if (RSTRUCT_LEN(s) < RARRAY_LEN(keys)) { return rb_hash_new_with_size(0); } h = rb_hash_new_with_size(RARRAY_LEN(keys)); for (i=0; i<RARRAY_LEN(keys); i++) { VALUE key = RARRAY_AREF(keys, i); int i = rb_struct_pos(s, &key); if (i < 0) { return h; } rb_hash_aset(h, key, RSTRUCT_GET(s, i)); } return h; }
#dig(key, ...) ⇒ Object
Extracts the nested value specified by the sequence of key
objects by calling dig
at each step, returning nil
if any intermediate step is nil
.
Foo = Struct.new(:a)
f = Foo.new(Foo.new({b: [1, 2, 3]}))
f.dig(:a, :a, :b, 0) # => 1
f.dig(:b, 0) # => nil
f.dig(:a, :a, :b, :c) # TypeError: no implicit conversion of Symbol into Integer
# File 'struct.c', line 1312
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| ... } ⇒ Struct
#each ⇒ Enumerator
Struct
#each ⇒ Enumerator
# File 'struct.c', line 775
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| ... } ⇒ Struct
#each_pair ⇒ Enumerator
Struct
#each_pair ⇒ Enumerator
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
# File 'struct.c', line 806
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?).
# File 'struct.c', line 1265
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); }
Also known as: #select
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.even? } #=> [22, 44, 66]
filter
is an alias for #select.
# File 'struct.c', line 1158
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; }
#hash ⇒ Integer
Returns a hash value based on this struct’s contents.
See also Object#hash.
# File 'struct.c', line 1226
static VALUE rb_struct_hash(VALUE s) { long i, len; st_index_t h; VALUE n; h = rb_hash_start(rb_hash(rb_obj_class(s))); len = RSTRUCT_LEN(s); for (i = 0; i < len; i++) { n = rb_hash(RSTRUCT_GET(s, i)); h = rb_hash_uint(h, NUM2LONG(n)); } h = rb_hash_end(h); return ST2FIX(h); }
#initialize_copy(s)
# File 'struct.c', line 973
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; }
Alias for #to_s.
Also known as: #size
# File 'struct.c', line 1290
VALUE rb_struct_size(VALUE s) { return LONG2FIX(RSTRUCT_LEN(s)); }
#members ⇒ Array
# File 'struct.c', line 204
static VALUE rb_struct_members_m(VALUE obj) { return rb_struct_s_members_m(rb_obj_class(obj)); }
Alias for #filter.
Alias for #length.
Also known as: #values, #deconstruct
# File 'struct.c', line 901
static VALUE rb_struct_to_a(VALUE s) { return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s)); }
Returns a ::Hash
containing the names and values for the struct’s members.
If a block is given, the results of the block on each pair of the receiver will be used as pairs.
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.to_h[:address] #=> "123 Maple, Anytown NC"
joe.to_h{:ADDRESS |name, value| [name.upcase, value.to_s.upcase]}
#=> "123 MAPLE, ANYTOWN NC"
# File 'struct.c', line 924
static VALUE rb_struct_to_h(VALUE s) { VALUE h = rb_hash_new_with_size(RSTRUCT_LEN(s)); VALUE members = rb_struct_members(s); long i; int block_given = rb_block_given_p(); for (i=0; i<RSTRUCT_LEN(s); i++) { VALUE k = rb_ary_entry(members, i), v = RSTRUCT_GET(s, i); if (block_given) rb_hash_set_pair(h, rb_yield_values(2, k, v)); else rb_hash_aset(h, k, v); } return h; }
Also known as: #inspect
Returns a description of this struct as a string.
# File 'struct.c', line 883
static VALUE rb_struct_inspect(VALUE s) { return rb_exec_recursive(inspect_struct, s, 0); }
Alias for #to_a.
#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]
# File 'struct.c', line 1134
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); }