class Struct
Struct serialization/deserialization
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
- Group
-
Group is a Struct that is only available when compiled with
HAVE_GETGRENT
.The struct contains the following members:
- name
-
contains the name of the group as a String.
- passwd
-
contains the encrypted password as a String. An 'x' is returned if password access to the group is not available; an empty string is returned if no password is needed to obtain membership of the group.
Must be compiled with
HAVE_STRUCT_GROUP_GR_PASSWD
. - gid
-
contains the group's numeric ID as an integer.
- mem
-
is an Array of Strings containing the short login names of the members of the group.
- Passwd
-
Passwd is a Struct that contains the following members:
- name
-
contains the short login name of the user as a String.
- passwd
-
contains the encrypted password of the user as a String. an 'x' is returned if shadow passwords are in use. An '*' is returned if the user cannot log in using a password.
- uid
-
contains the integer user ID (uid) of the user.
- gid
-
contains the integer group ID (gid) of the user's primary group.
- dir
-
contains the path to the home directory of the user as a String.
- shell
-
contains the path to the login shell of the user as a String.
The following members below are optional, and must be compiled with special flags:¶ ↑
- gecos
-
contains a longer String description of the user, such as a full name. Some Unix systems provide structured information in the gecos field, but this is system-dependent. must be compiled with
HAVE_STRUCT_PASSWD_PW_GECOS
- change
-
password change time(integer) must be compiled with
HAVE_STRUCT_PASSWD_PW_CHANGE
- quota
-
quota value(integer) must be compiled with
HAVE_STRUCT_PASSWD_PW_QUOTA
- age
-
password age(integer) must be compiled with
HAVE_STRUCT_PASSWD_PW_AGE
- class
-
user access class(string) must be compiled with
HAVE_STRUCT_PASSWD_PW_CLASS
- comment
-
comment(string) must be compiled with
HAVE_STRUCT_PASSWD_PW_COMMENT
- expire
-
account expiration time(integer) must be compiled with
HAVE_STRUCT_PASSWD_PW_EXPIRE
- Tms
Public Class Methods
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; 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; }
Public Instance Methods
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); }
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) { 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); }
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"
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; }
Returns a hash, that will be turned into a JSON object and represent this object.
# File ext/json/lib/json/add/struct.rb, line 16 def as_json(*) klass = self.class.name klass.to_s.empty? and raise JSON::JSONError, "Only named structs are supported!" { JSON.create_id => klass, 'v' => values, } end
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; }
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; }
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); }
Returns a hash value based on this struct's contents (see 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); }
Describe the contents of this struct in a string.
static VALUE rb_struct_inspect(VALUE s) { return rb_exec_recursive(inspect_struct, s, 0); }
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)); }
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)); }
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; }
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)); }
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)); }
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; }
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)); }
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); }