类 Struct

类 Struct 提供了一种创建可存储和获取值的简单类的便捷方式。

此示例创建 Struct 的子类 Struct::Customer；第一个参数（字符串）是子类的名称；其他参数（符号）决定新子类的成员。

Customer = Struct.new('Customer', :name, :address, :zip)
Customer.name       # => "Struct::Customer"
Customer.class      # => Class
Customer.superclass # => Struct

每个成员都对应两个方法：一个写入器和一个读取器，用于存储和获取值

methods = Customer.instance_methods false
methods # => [:zip, :address=, :zip=, :address, :name, :name=]

可以通过方法 ::new 创建子类的实例并为其成员赋值

joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345>

成员值可以通过以下方式管理

joe.name    # => "Joe Smith"
joe.name = 'Joseph Smith'
joe.name    # => "Joseph Smith"

因此；请注意，成员名称可以表示为字符串或符号

joe[:name]  # => "Joseph Smith"
joe[:name] = 'Joseph Smith, Jr.'
joe['name'] # => "Joseph Smith, Jr."

请参阅 Struct::new。

这里有什么¶ ↑

首先，其他地方有什么。类 Struct

继承自类 Object。
包含模块 Enumerable，该模块提供数十个额外的方法。

另请参阅 Data，它是一个有些类似的概念，但更严格，用于定义不可变的值对象。

在此，类 Struct 提供了一些有用的方法，用于

创建 `Struct` 子类的方法¶ ↑

::new: 返回 Struct 的新子类。

查询方法¶ ↑

hash: 返回整数哈希码。
size (别名为 length): 返回成员的数量。

比较方法¶ ↑

==: 返回给定对象是否等于 self，使用 == 来比较成员值。
eql?: 返回给定对象是否等于 self，使用 eql? 来比较成员值。

获取方法¶ ↑

[]: 返回与给定成员名称关联的值。
to_a (别名为 values, deconstruct): 返回 self 中作为数组的成员值。
deconstruct_keys: 返回给定成员名称的名称/值对的哈希。
dig: 返回嵌套对象中由给定成员名称和其他参数指定的对象。
members: 返回成员名称的数组。
select (别名为 filter): 返回 self 中的成员值数组，由给定的块选择。
values_at: 返回包含给定成员名称的值的数组。

赋值方法¶ ↑

[]=: 将给定值分配给给定成员名称。

迭代方法¶ ↑

each: 使用每个成员名称调用给定的块。
each_pair: 使用每个成员名称/值对调用给定的块。

转换方法¶ ↑

inspect (别名为 to_s): 返回 self 的字符串表示形式。
to_h: 返回 self 中成员名称/值对的哈希。

公共类方法

json_create (object)

源代码

# File ext/json/lib/json/add/struct.rb, line 9
def self.json_create(object)
  new(*object['v'])
end

请参阅 as_json。

StructClass::keyword_init? → true 或 falsy 值

源代码

static VALUE
rb_struct_s_keyword_init_p(VALUE obj)
{
}

如果类是用 keyword_init: true 初始化的，则返回 true。否则返回 nil 或 false。

示例

Foo = Struct.new(:a)
Foo.keyword_init? # => nil
Bar = Struct.new(:a, keyword_init: true)
Bar.keyword_init? # => true
Baz = Struct.new(:a, keyword_init: false)
Baz.keyword_init? # => false

StructClass::members → array_of_symbols

源代码

static VALUE
rb_struct_s_members_m(VALUE klass)
{
    VALUE members = rb_struct_s_members(klass);

    return rb_ary_dup(members);
}

以数组的形式返回 Struct 后代的成员名称

Customer = Struct.new(:name, :address, :zip)
Customer.members # => [:name, :address, :zip]

new(*member_names, keyword_init: nil){|Struct_subclass| ... } → Struct_subclass

new(class_name, *member_names, keyword_init: nil){|Struct_subclass| ... } → Struct_subclass

new(*member_names) → Struct_subclass_instance

new(**member_names) → Struct_subclass_instance

源代码

static VALUE
rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
{
    VALUE name = Qnil, rest, keyword_init = Qnil;
    long i;
    VALUE st;
    VALUE opt;

    argc = rb_scan_args(argc, argv, "0*:", NULL, &opt);
    if (argc >= 1 && !SYMBOL_P(argv[0])) {
        name = argv[0];
        --argc;
        ++argv;
    }

    if (!NIL_P(opt)) {
        static ID keyword_ids[1];

        if (!keyword_ids[0]) {
            keyword_ids[0] = rb_intern("keyword_init");
        }
        rb_get_kwargs(opt, keyword_ids, 0, 1, &keyword_init);
        if (UNDEF_P(keyword_init)) {
            keyword_init = Qnil;
        }
        else if (RTEST(keyword_init)) {
            keyword_init = Qtrue;
        }
    }

    rest = rb_ident_hash_new();
    RBASIC_CLEAR_CLASS(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 (RTEST(rb_hash_has_key(rest, mem))) {
            rb_raise(rb_eArgError, "duplicate member: %"PRIsVALUE, mem);
        }
        rb_hash_aset(rest, mem, Qtrue);
    }
    rest = rb_hash_keys(rest);
    RBASIC_CLEAR_CLASS(rest);
    OBJ_FREEZE(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;
}

Struct.new 返回 Struct 的新子类。新子类

可以是匿名的，也可以具有由 class_name 给定的名称。
可以具有由 member_names 给定的成员。
可以通过普通参数或通过关键字参数进行初始化

新子类有自己的方法 ::new；因此

Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
f = Foo.new(0, 1)                   # => #<struct Struct::Foo foo=0, bar=1>

类名

使用字符串参数 class_name，返回名为 Struct::class_name 的 Struct 的新子类

Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
Foo.name                            # => "Struct::Foo"
Foo.superclass                      # => Struct

不使用字符串参数 class_name，返回 Struct 的新匿名子类

Struct.new(:foo, :bar).name # => nil

块

如果给定了块，则将创建的子类传递给该块

Customer = Struct.new('Customer', :name, :address) do |new_class|
  p "The new subclass is #{new_class}"
  def greeting
    "Hello #{name} at #{address}"
  end
end           # => Struct::Customer
dave = Customer.new('Dave', '123 Main')
dave # =>     #<struct Struct::Customer name="Dave", address="123 Main">
dave.greeting # => "Hello Dave at 123 Main"

来自 Struct.new 的输出

"The new subclass is Struct::Customer"

成员名称

Symbol 参数 member_names 决定新子类的成员

Struct.new(:foo, :bar).members        # => [:foo, :bar]
Struct.new('Foo', :foo, :bar).members # => [:foo, :bar]

新子类具有与 member_names 相对应的实例方法

Foo = Struct.new('Foo', :foo, :bar)
Foo.instance_methods(false) # => [:foo, :bar, :foo=, :bar=]
f = Foo.new                 # => #<struct Struct::Foo foo=nil, bar=nil>
f.foo                       # => nil
f.foo = 0                   # => 0
f.bar                       # => nil
f.bar = 1                   # => 1
f                           # => #<struct Struct::Foo foo=0, bar=1>

单例方法

Struct.new 返回的子类具有以下单例方法

方法 ::new 创建子类的实例

Foo.new          # => #<struct Struct::Foo foo=nil, bar=nil>
Foo.new(0)       # => #<struct Struct::Foo foo=0, bar=nil>
Foo.new(0, 1)    # => #<struct Struct::Foo foo=0, bar=1>
Foo.new(0, 1, 2) # Raises ArgumentError: struct size differs

# Initialization with keyword arguments:
Foo.new(foo: 0)         # => #<struct Struct::Foo foo=0, bar=nil>
Foo.new(foo: 0, bar: 1) # => #<struct Struct::Foo foo=0, bar=1>
Foo.new(foo: 0, bar: 1, baz: 2)
# Raises ArgumentError: unknown keywords: baz

方法 :inspect 返回子类的字符串表示形式
```
Foo.inspect
# => "Struct::Foo"
```
方法 ::members 返回成员名称的数组
```
Foo.members # => [:foo, :bar]
```

关键字参数

默认情况下，用于初始化新子类实例的参数可以是位置参数和关键字参数。

可选的关键字参数 keyword_init: 允许强制仅接受一种类型的参数

KeywordsOnly = Struct.new(:foo, :bar, keyword_init: true)
KeywordsOnly.new(bar: 1, foo: 0)
# => #<struct KeywordsOnly foo=0, bar=1>
KeywordsOnly.new(0, 1)
# Raises ArgumentError: wrong number of arguments

PositionalOnly = Struct.new(:foo, :bar, keyword_init: false)
PositionalOnly.new(0, 1)
# => #<struct PositionalOnly foo=0, bar=1>
PositionalOnly.new(bar: 1, foo: 0)
# => #<struct PositionalOnly foo={:foo=>1, :bar=>2}, bar=nil>
# Note that no error is raised, but arguments treated as one hash value

# Same as not providing keyword_init:
Any = Struct.new(:foo, :bar, keyword_init: nil)
Any.new(foo: 1, bar: 2)
# => #<struct Any foo=1, bar=2>
Any.new(1, 2)
# => #<struct Any foo=1, bar=2>

公共实例方法

self == other → true 或 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);
}

当且仅当以下情况为真时返回 true；否则返回 false

other.class == self.class.
对于每个成员名称 name，other.name == 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 == joe # => true
joe_jr[:name] = 'Joe Smith, Jr.'
# => "Joe Smith, Jr."
joe_jr == joe # => false

struct[name] → object

struct[n] → object

源代码

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

从 self 返回一个值。

如果给定了符号或字符串参数 name，则返回命名成员的值

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[:zip] # => 12345

如果 name 不是成员的名称，则引发 NameError。

如果给定了整数参数 n，则如果 n 在范围内，则返回 self.values[n]；请参阅 Array 的数组索引

joe[2]  # => 12345
joe[-2] # => "123 Maple, Anytown NC"

如果 n 超出范围，则引发 IndexError。

struct[name] = value → value

struct[n] = value → value

源代码

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

将值分配给成员。

如果给定了符号或字符串参数 name，则将给定的 value 分配给命名成员；返回 value

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[:zip] = 54321 # => 54321
joe # => #<struct Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=54321>

如果 name 不是成员的名称，则引发 NameError。

如果给定了整数参数 n，则如果 n 在范围内，则将给定的 value 分配给第 n 个成员；请参阅 Array 的数组索引

joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe[2] = 54321           # => 54321
joe[-3] = 'Joseph Smith' # => "Joseph Smith"
joe # => #<struct Customer name="Joseph Smith", address="123 Maple, Anytown NC", zip=54321>

如果 n 超出范围，则引发 IndexError。

as_json (*)

源代码

# File ext/json/lib/json/add/struct.rb, line 30
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

方法 Struct#as_json 和 Struct.json_create 可用于序列化和反序列化 Struct 对象；请参阅 Marshal。

方法 Struct#as_json 序列化 self，返回表示 self 的 2 元素哈希

require 'json/add/struct'
Customer = Struct.new('Customer', :name, :address, :zip)
x = Struct::Customer.new.as_json
# => {"json_class"=>"Struct::Customer", "v"=>[nil, nil, nil]}

方法 JSON.create 反序列化这样的哈希，返回 Struct 对象

Struct::Customer.json_create(x)
# => #<struct Struct::Customer name=nil, address=nil, zip=nil>

deconstruct

别名：to_a

deconstruct_keys(array_of_names) → hash

源代码

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

返回给定成员名称的名称/值对的哈希。

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
h = joe.deconstruct_keys([:zip, :address])
h # => {:zip=>12345, :address=>"123 Maple, Anytown NC"}

如果 array_of_names 为 nil，则返回所有名称和值

h = joe.deconstruct_keys(nil)
h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}

dig(name, *identifiers) → object

dig(n, *identifiers) → object

源代码

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

在嵌套对象中查找并返回对象。嵌套对象可以是各种类的实例。请参阅 Dig 方法。

给定符号或字符串参数 name，返回由 name 和 identifiers 指定的对象

Foo = Struct.new(:a)
f = Foo.new(Foo.new({b: [1, 2, 3]}))
f.dig(:a) # => #<struct Foo a={:b=>[1, 2, 3]}>
f.dig(:a, :a) # => {:b=>[1, 2, 3]}
f.dig(:a, :a, :b) # => [1, 2, 3]
f.dig(:a, :a, :b, 0) # => 1
f.dig(:b, 0) # => nil

给定整数参数 n，返回由 n 和 identifiers 指定的对象

f.dig(0) # => #<struct Foo a={:b=>[1, 2, 3]}>
f.dig(0, 0) # => {:b=>[1, 2, 3]}
f.dig(0, 0, :b) # => [1, 2, 3]
f.dig(0, 0, :b, 0) # => 1
f.dig(:b, 0) # => nil

each {|value| ... } → self

each → enumerator

源代码

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

使用每个成员的值调用给定的块；返回 self

Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each {|value| p value }

输出

"Joe Smith"
"123 Maple, Anytown NC"
12345

如果没有给出块，则返回一个 Enumerator。