Class Struct provides a convenient way to create a simple class that can store and fetch values.
This example creates a subclass of Struct, Struct::Customer; the first argument, a string, is the name of the subclass; the other arguments, symbols, determine the members of the new subclass.
Customer = Struct.new('Customer', :name, :address, :zip)
Customer.name
Customer.class
Customer.superclass
Corresponding to each member are two methods, a writer and a reader, that store and fetch values:
methods = Customer.instance_methods false methods
An instance of the subclass may be created, and its members assigned values, via method ::new:
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe
The member values may be managed thus:
joe.name joe.name = 'Joseph Smith' joe.name
And thus; note that member name may be expressed as either a string or a symbol:
joe[:name] joe[:name] = 'Joseph Smith, Jr.' joe['name']
See Struct::new.
First, whatâs elsewhere. Class Struct:
Inherits from class Object.
Includes module Enumerable, which provides dozens of additional methods.
Here, class Struct provides methods that are useful for:
Methods for Creating aStruct Subclass¶ ↑
::new
Returns a new subclass of Struct.
hash
Returns the integer hash code.
length, size
Returns the number of members.
Returns whether a given object is equal to self, using == to compare member values.
eql?
Returns whether a given object is equal to self, using eql? to compare member values.
[]
Returns the value associated with a given member name.
to_a, values, deconstruct
Returns the member values in self as an array.
deconstruct_keys
Returns a hash of the name/value pairs for given member names.
dig
Returns the object in nested objects that is specified by a given member name and additional arguments.
members
Returns an array of the member names.
select, filter
Returns an array of member values from self, as selected by the given block.
values_at
Returns an array containing values for given member names.
[]=
Assigns a given value to a given member name.
each
Calls a given block with each member name.
each_pair
Calls a given block with each member name/value pair.
inspect, to_s
Returns a string representation of self.
to_h
Returns a hash of the member name/value pairs in self.
Group is a Struct that is only available when compiled with HAVE_GETGRENT.
The struct contains the following members:
contains the name of the group as a String.
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.
contains the groupâs numeric ID as an integer.
is an Array of Strings containing the short login names of the members of the group.
Passwd is a Struct that contains the following members:
contains the short login name of the user as a String.
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.
contains the integer user ID (uid) of the user.
contains the integer group ID (gid) of the userâs primary group.
contains the path to the home directory of the user as a String.
contains the path to the login shell of the user as a String.
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
password change time(integer) must be compiled with HAVE_STRUCT_PASSWD_PW_CHANGE
quota value(integer) must be compiled with HAVE_STRUCT_PASSWD_PW_QUOTA
password age(integer) must be compiled with HAVE_STRUCT_PASSWD_PW_AGE
user access class(string) must be compiled with HAVE_STRUCT_PASSWD_PW_CLASS
comment(string) must be compiled with HAVE_STRUCT_PASSWD_PW_COMMENT
account expiration time(integer) must be compiled with HAVE_STRUCT_PASSWD_PW_EXPIRE
json_create(object) click to toggle source
Deserializes JSON string by constructing new Struct object with values v serialized by to_json.
def self.json_create(object) new(*object['v']) end
StructClass::keyword_init? → true or falsy value click to toggle source
Returns true if the class was initialized with keyword_init: true. Otherwise returns nil or false.
Examples:
Foo = Struct.new(:a) Foo.keyword_init? Bar = Struct.new(:a, keyword_init: true) Bar.keyword_init? Baz = Struct.new(:a, keyword_init: false) Baz.keyword_init?
static VALUE
rb_struct_s_keyword_init_p(VALUE obj)
{
}
StructClass::members → array_of_symbols click to toggle source
Returns the member names of the Struct descendant as an array:
Customer = Struct.new(:name, :address, :zip) Customer.members
static VALUE
rb_struct_s_members_m(VALUE klass)
{
VALUE members = rb_struct_s_members(klass);
return rb_ary_dup(members);
}
new(*member_names, keyword_init: false){|Struct_subclass| ... } → Struct_subclass click to toggle source
new(class_name, *member_names, keyword_init: false){|Struct_subclass| ... } → Struct_subclass
new(*member_names) → Struct_subclass_instance
new(**member_names) → Struct_subclass_instance
Struct.new returns a new subclass of Struct. The new subclass:
May be anonymous, or may have the name given by class_name.
May have members as given by member_names.
May have initialization via ordinary arguments (the default) or via keyword arguments (if keyword_init: true is given).
The new subclass has its own method ::new; thus:
Foo = Struct.new('Foo', :foo, :bar)
f = Foo.new(0, 1)
Class Name
With string argument class_name, returns a new subclass of Struct named Struct::class_name:
Foo = Struct.new('Foo', :foo, :bar)
Foo.name
Foo.superclass
Without string argument class_name, returns a new anonymous subclass of Struct:
Struct.new(:foo, :bar).name
Block
With a block given, the created subclass is yielded to the block:
Customer = Struct.new('Customer', :name, :address) do |new_class|
p "The new subclass is #{new_class}"
def greeting
"Hello #{name} at #{address}"
end
end
dave = Customer.new('Dave', '123 Main')
dave
dave.greeting
Output, from Struct.new:
"The new subclass is Struct::Customer"
Member Names
Symbol arguments member_names determines the members of the new subclass:
Struct.new(:foo, :bar).members
Struct.new('Foo', :foo, :bar).members
The new subclass has instance methods corresponding to member_names:
Foo = Struct.new('Foo', :foo, :bar)
Foo.instance_methods(false)
f = Foo.new
f.foo
f.foo = 0
f.bar
f.bar = 1
f
Singleton Methods
A subclass returned by Struct.new has these singleton methods:
Method ::new creates an instance of the subclass:
Foo.new Foo.new(0) Foo.new(0, 1) Foo.new(0, 1, 2)
Method ::[] is an alias for method ::new.
Method :inspect returns a string representation of the subclass:
Foo.inspect
Method ::members returns an array of the member names:
Foo.members
Keyword Argument
By default, the arguments for initializing an instance of the new subclass are ordinary arguments (not keyword arguments). With optional keyword argument keyword_init: true, the new subclass is initialized with keyword arguments:
Foo = Struct.new('Foo', :foo, :bar)
Foo
Foo.new(0, 1)
Bar = Struct.new(:foo, :bar, keyword_init: true)
Bar
Bar.new(bar: 1, foo: 0)
static VALUE
rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
{
VALUE name, rest, keyword_init = Qnil;
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 = Qnil;
}
else if (RTEST(keyword_init)) {
keyword_init = Qtrue;
}
--argc;
}
rest = rb_ident_hash_new();
RBASIC_CLEAR_CLASS(rest);
OBJ_WB_UNPROTECT(rest);
tbl = RHASH_TBL_RAW(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;
} Public Instance Methods
self == other → true or false click to toggle source
Returns true if and only if the following are true; otherwise returns false:
other.class == self.class.
For each member name name, other.name == self.name.
Examples:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe_jr == joe
joe_jr[:name] = 'Joe Smith, Jr.'
joe_jr == joe
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[name] → object click to toggle source
struct[n] → object
Returns a value from self.
With symbol or string argument name given, returns the value for the named member:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[:zip]
Raises NameError if name is not the name of a member.
With integer argument n given, returns self.values[n] if n is in range; see Array Indexes:
joe[2] joe[-2]
Raises IndexError if n is out of range.
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[name] = value → value click to toggle source
struct[n] = value → value
Assigns a value to a member.
With symbol or string argument name given, assigns the given value to the named member; returns value:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[:zip] = 54321
joe
Raises NameError if name is not the name of a member.
With integer argument n given, assigns the given value to the n-th member if n is in range; see Array Indexes:
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[2] = 54321
joe[-3] = 'Joseph Smith'
joe
Raises IndexError if n is out of range.
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;
}
as_json(*) click to toggle source
Returns a hash, that will be turned into a JSON object and represent this object.
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
deconstruct_keys(array_of_names) → hash click to toggle source
Returns a hash of the name/value pairs for the given member names.
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
h = joe.deconstruct_keys([:zip, :address])
h
Returns all names and values if array_of_names is nil:
h = joe.deconstruct_keys(nil) h
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(name, *identifiers) → object click to toggle source
dig(n, *identifiers) → object
Finds and returns an object among nested objects. The nested objects may be instances of various classes. See Dig Methods.
Given symbol or string argument name, returns the object that is specified by name and identifiers:
Foo = Struct.new(:a)
f = Foo.new(Foo.new({b: [1, 2, 3]}))
f.dig(:a)
f.dig(:a, :a)
f.dig(:a, :a, :b)
f.dig(:a, :a, :b, 0)
f.dig(:b, 0)
Given integer argument n, returns the object that is specified by n and identifiers:
f.dig(0) f.dig(0, 0) f.dig(0, 0, :b) f.dig(0, 0, :b, 0) f.dig(:b, 0)
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 {|value| ... } → self click to toggle source
each → enumerator
Calls the given block with the value of each member; returns self:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each {|value| p value }
Output:
"Joe Smith" "123 Maple, Anytown NC" 12345
Returns an Enumerator if no block is given.
Related: each_pair.
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 {|(name, value)| ... } → self click to toggle source
each_pair → enumerator
Calls the given block with each member name/value pair; returns self:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each_pair {|(name, value)| p "#{name} => #{value}" }
Output:
"name => Joe Smith" "address => 123 Maple, Anytown NC" "zip => 12345"
Returns an Enumerator if no block is given.
Related: each.
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_pair_yield_optimizable()) {
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
Returns true if and only if the following are true; otherwise returns false:
other.class == self.class.
For each member name name, other.name.eql?(self.name).
Customer = Struct.new(:name, :address, :zip) joe = Customer.new(âJoe Smithâ, â123 Maple, Anytown NCâ, 12345) joe_jr = Customer.new(âJoe Smithâ, â123 Maple, Anytown NCâ, 12345) joe_jr.eql?(joe) # => true joe_jr = âJoe Smith, Jr.â joe_jr.eql?(joe) # => false
Related: Object#==.
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);
}
filter(*args)
With a block given, returns an array of values from self for which the block returns a truthy value:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
a = joe.select {|value| value.is_a?(String) }
a
a = joe.select {|value| value.is_a?(Integer) }
a
With no block given, returns an Enumerator.
Struct#filter is an alias for Struct#select.
hash → integer click to toggle source
Returns the integer hash value for self.
Two structs of the same class and with the same content will have the same hash code (and will compare using Struct#eql?):
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe_jr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.hash == joe_jr.hash
joe_jr[:name] = 'Joe Smith, Jr.'
joe.hash == joe_jr.hash
Related: Object#hash.
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);
}
inspect → string click to toggle source
Returns a string representation of self:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.inspect
Struct#to_s is an alias for Struct#inspect.
static VALUE
rb_struct_inspect(VALUE s)
{
return rb_exec_recursive(inspect_struct, s, 0);
}
length()
Returns the number of members.
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.size
Struct#length is an alias for Struct#size.
members → array_of_symbols click to toggle source
Returns the member names from self as an array:
Customer = Struct.new(:name, :address, :zip) Customer.new.members
Related: to_a.
static VALUE
rb_struct_members_m(VALUE obj)
{
return rb_struct_s_members_m(rb_obj_class(obj));
}
select {|value| ... } → array click to toggle source
select → enumerator
With a block given, returns an array of values from self for which the block returns a truthy value:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
a = joe.select {|value| value.is_a?(String) }
a
a = joe.select {|value| value.is_a?(Integer) }
a
With no block given, returns an Enumerator.
Struct#filter is an alias for Struct#select.
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 → integer click to toggle source
Returns the number of members.
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.size
Struct#length is an alias for Struct#size.
VALUE
rb_struct_size(VALUE s)
{
return LONG2FIX(RSTRUCT_LEN(s));
}
to_a → array click to toggle source
Returns the values in self as an array:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.to_a
Struct#values and Struct#deconstruct are aliases for Struct#to_a.
Related: members.
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
to_h {|name, value| ... } → hash
Returns a hash containing the name and value for each member:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
h = joe.to_h
h
If a block is given, it is called with each name/value pair; the block should return a 2-element array whose elements will become a key/value pair in the returned hash:
h = joe.to_h{|name, value| [name.upcase, value.to_s.upcase]}
h
Raises ArgumentError if the block returns an inappropriate value.
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;
}
to_json(*args) click to toggle source
Stores class name (Struct) with Struct values v as a JSON string. Only named structs are supported.
def to_json(*args) as_json.to_json(*args) end
to_s()
Returns a string representation of self:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.inspect
Struct#to_s is an alias for Struct#inspect.
values_at(*integers) → array click to toggle source
values_at(integer_range) → array
Returns an array of values from self.
With integer arguments integers given, returns an array containing each value given by one of integers:
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.values_at(0, 2)
joe.values_at(2, 0)
joe.values_at(2, 1, 0)
joe.values_at(0, -3)
Raises IndexError if any of integers is out of range; see Array Indexes.
With integer range argument integer_range given, returns an array containing each value given by the elements of the range; fills with nil values for range elements larger than the structure:
joe.values_at(0..2) joe.values_at(-3..-1) joe.values_at(1..4)
Raises RangeError if any element of the range is negative and out of range; see Array Indexes.
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);
}
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4