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 =
for the backward compatibility
rb_cProcessTms
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 Attribute Summary
::Enumerable - Included
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
. -
#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?). -
#hash ⇒ Fixnum
Returns a hash value based on this struct's contents (see Object#hash).
- #initialize(*args) constructor
-
#inspect ⇒ String
Alias for #to_s.
-
#length ⇒ Fixnum
(also: #size)
Returns the number of struct members.
-
#members ⇒ Array
Returns the struct members as an array of symbols:
-
#select {|i| ... } ⇒ Array
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 ⇒ Fixnum
Alias for #length.
-
#to_a ⇒ Array
(also: #values)
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)
Describe the contents of this struct in a string.
-
#values ⇒ Array
Alias for #to_a.
-
#values_at(selector, ...) ⇒ Array
Returns the struct member values for each
selector
as an ::Array.
::Enumerable - Included
#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. |
#find | Passes each entry in enum to block. |
#find_all | Alias for Enumerable#select. |
#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 a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis. |
#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. |
#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 | Returns an array containing all elements of |
#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, either according to their own |
#sort_by | Sorts enum using a set of keys generated by mapping the values in enum through the given block. |
#take | Returns first n elements from enum. |
#take_while | Passes elements to the block until the block returns |
#to_a | Returns an array containing the items in enum. |
#to_h | Returns the result of interpreting enum as a list of |
#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">
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.
# 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">
#initialize(*args)
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
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"
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"
#dig(key, ...) ⇒ Object
#each {|obj| ... } ⇒ Struct
#each ⇒ Enumerator
Struct
#each ⇒ Enumerator
#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
#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?).
#hash ⇒ Fixnum
Returns a hash value based on this struct's contents (see Object#hash).
See also Object#hash.
Alias for #to_s.
Also known as: #size
#members ⇒ Array
#select {|i| ... } ⇒ Array
#select ⇒ Enumerator
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]
Alias for #length.
Also known as: #values
#to_h ⇒ Hash
Also known as: #inspect
Describe the contents of this struct in a string.
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]