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 =
    # File 'process.c', line 8772:Tmsfor 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 Structsubclassclass_namethat can contain a value for eachmember_name.
Instance Method Summary
- 
    
      #==(other)  ⇒ Boolean 
    
    Equality—Returns trueifotherhas the same struct subclass and has equal member values (according toObject#==).
- 
    
      #[](member)  ⇒ Object 
    
    Attribute Reference—Returns the value of the given struct memberor the member at the givenindex.
- 
    
      #[]=(member, obj)  ⇒ Object 
    
    Attribute Assignment—Sets the value of the given struct memberor 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 keyobjects by callingdigat each step, returningnilif 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 
    
    ::Hashequality—otherandstructrefer 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 ::Arraycontaining the member values from thestructfor 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 ::Hashcontaining 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 selectoras 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);
}