Class: Struct (Ruby 2.3.4)

    In Files

    • process.c
    • struct.c

    Class/Module Index [+]

    Quicksearch

    Struct

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

    Constants

    Tms

    Public Class Methods

    new([class_name] [, member_name]+>) → StructClass click to toggle source
    new([class_name] [, member_name]+>) {|StructClass| block } → StructClass
    new(value, ...) → obj
    StructClass[value, ...] → obj

    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">
    
     
                   static VALUE
    rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
    {
        VALUE name, rest;
        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;
        }
        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 (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);
        if (rb_block_given_p()) {
            rb_mod_module_eval(0, 0, st);
        }
    
        return st;
    }
                

    Public Instance Methods

    struct == other → true or false click to toggle source

    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
    
     
                   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);
    }
                
    struct[member] → anObject click to toggle source
    struct[index] → anObject

    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"
    
     
                   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);
    }
                
    struct[member] = obj → obj click to toggle source
    struct[index] = obj → obj

    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"
    
     
                   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;
    }
                
    dig(key, ...) → object click to toggle source

    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.

    klass = Struct.new(:a)
    o = klass.new(klass.new({b: [1, 2, 3]}))
    
    o.dig(:a, :a, :b, 0)   #=> 1
    o.dig(:b, 0)           #=> nil
    
     
                   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| block } → struct click to toggle source
    each → an_enumerator

    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
     
                   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| block } → struct click to toggle source
    each_pair → an_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
     
                   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) → true or false click to toggle source

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

     
                   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 click to toggle source

    Returns a hash value based on this struct’s contents (see Object#hash).

    See also Object#hash.

     
                   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);
    }
                
    to_s → string click to toggle source
    inspect → string

    Describe the contents of this struct in a string.

     
                   static VALUE
    rb_struct_inspect(VALUE s)
    {
        return rb_exec_recursive(inspect_struct, s, 0);
    }
                
    Also aliased as: to_s
    length → fixnum click to toggle source

    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
    
     
                   static VALUE
    rb_struct_size(VALUE s)
    {
        return LONG2FIX(RSTRUCT_LEN(s));
    }
                
    members → array click to toggle source

    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]
    
     
                   static VALUE
    rb_struct_members_m(VALUE obj)
    {
        return rb_struct_s_members_m(rb_obj_class(obj));
    }
                
    select {|i| block } → array click to toggle source
    select → an_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]
    
     
                   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;
    }
                
    size → fixnum click to toggle source

    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
    
     
                   static VALUE
    rb_struct_size(VALUE s)
    {
        return LONG2FIX(RSTRUCT_LEN(s));
    }
                
    to_a → array click to toggle source

    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"
    
     
                   static VALUE
    rb_struct_to_a(VALUE s)
    {
        return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
    }
                
    to_h → hash click to toggle source

    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"
    
     
                   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_s() click to toggle source
    Alias for: inspect
    values → array click to toggle source

    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"
    
     
                   static VALUE
    rb_struct_to_a(VALUE s)
    {
        return rb_ary_new4(RSTRUCT_LEN(s), RSTRUCT_CONST_PTR(s));
    }
                
    values_at(selector, ...) → an_array click to toggle source

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