类 Data

类 Data 提供了一种便捷的方法来定义值类对象的简单类。

最简单的用法示例

Measure = Data.define(:amount, :unit)

# Positional arguments constructor is provided
distance = Measure.new(100, 'km')
#=> #<data Measure amount=100, unit="km">

# Keyword arguments constructor is provided
weight = Measure.new(amount: 50, unit: 'kg')
#=> #<data Measure amount=50, unit="kg">

# Alternative form to construct an object:
speed = Measure[10, 'mPh']
#=> #<data Measure amount=10, unit="mPh">

# Works with keyword arguments, too:
area = Measure[amount: 1.5, unit: 'm^2']
#=> #<data Measure amount=1.5, unit="m^2">

# Argument accessors are provided:
distance.amount #=> 100
distance.unit #=> "km"

构造的对象还具有 == 运算符、to_h 哈希转换以及 deconstruct / deconstruct_keys 的合理定义，可用于模式匹配。

::define 方法接受一个可选块，并在新定义的类的上下文中对其进行评估。这允许定义其他方法

Measure = Data.define(:amount, :unit) do
  def <=>(other)
    return unless other.is_a?(self.class) && other.unit == unit
    amount <=> other.amount
  end

  include Comparable
end

Measure[3, 'm'] < Measure[5, 'm'] #=> true
Measure[3, 'm'] < Measure[5, 'kg']
# comparison of Measure with Measure failed (ArgumentError)

Data 不提供成员写入器或枚举器：它旨在存储不可变原子值。但请注意，如果某些数据成员属于可变类，则 Data 不会执行额外的不可变性强制

Event = Data.define(:time, :weekdays)
event = Event.new('18:00', %w[Tue Wed Fri])
#=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri"]>

# There is no #time= or #weekdays= accessors, but changes are
# still possible:
event.weekdays << 'Sat'
event
#=> #<data Event time="18:00", weekdays=["Tue", "Wed", "Fri", "Sat"]>

另请参见 Struct，它是一个类似的概念，但具有更类似容器的 API，允许更改对象的内容并对其进行枚举。

公共类方法

define(*symbols) → class 单击以切换源

定义一个新的 Data 类。

measure = Data.define(:amount, :unit)
#=> #<Class:0x00007f70c6868498>
measure.new(1, 'km')
#=> #<data amount=1, unit="km">

# It you store the new class in the constant, it will
# affect #inspect and will be more natural to use:
Measure = Data.define(:amount, :unit)
#=> Measure
Measure.new(1, 'km')
#=> #<data Measure amount=1, unit="km">

请注意，无成员的 Data 是可以接受的，并且可能是定义几个同类数据类的有用技术，例如

class HTTPFetcher
  Response = Data.define(:body)
  NotFound = Data.define
  # ... implementation
end

现在，来自 HTTPFetcher 的不同类型的响应将具有统一的表示

#<data HTTPFetcher::Response body="<html...">
#<data HTTPFetcher::NotFound>

并且在模式匹配中使用起来很方便

case fetcher.get(url)
in HTTPFetcher::Response(body)
  # process body variable
in HTTPFetcher::NotFound
  # handle not found case
end

static VALUE
rb_data_s_def(int argc, VALUE *argv, VALUE klass)
{
    VALUE rest;
    long i;
    VALUE data_class;

    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 data 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_RAW(rest);
    data_class = anonymous_struct(klass);
    setup_data(data_class, rest);
    if (rb_block_given_p()) {
        rb_mod_module_eval(0, 0, data_class);
    }

    return data_class;
}

DataClass::members → array_of_symbols 单击以切换源

返回数据类的成员名称数组

Measure = Data.define(:amount, :unit)
Measure.members # => [:amount, :unit]

#define rb_data_s_members_m rb_struct_s_members_m

new(*args) → instance 单击以切换源

new(**kwargs) → instance

::[](*args) → instance

::[](**kwargs) → instance

使用 ::define 定义的类的构造函数接受位置参数和关键字参数。

Measure = Data.define(:amount, :unit)

Measure.new(1, 'km')
#=> #<data Measure amount=1, unit="km">
Measure.new(amount: 1, unit: 'km')
#=> #<data Measure amount=1, unit="km">

# Alternative shorter initialization with []
Measure[1, 'km']
#=> #<data Measure amount=1, unit="km">
Measure[amount: 1, unit: 'km']
#=> #<data Measure amount=1, unit="km">

所有参数都是必需的（与 Struct 不同），并转换为关键字参数

Measure.new(amount: 1)
# in `initialize': missing keyword: :unit (ArgumentError)

Measure.new(1)
# in `initialize': missing keyword: :unit (ArgumentError)

请注意，Measure#initialize 始终接收关键字参数，并且在 initialize 中检查必需参数，而不是在 new 中。这对于重新定义 initialize 以转换参数或提供默认值非常重要

Measure = Data.define(:amount, :unit) do
  NONE = Data.define

  def initialize(amount:, unit: NONE.new)
    super(amount: Float(amount), unit:)
  end
end

Measure.new('10', 'km') # => #<data Measure amount=10.0, unit="km">
Measure.new(10_000)     # => #<data Measure amount=10000.0, unit=#<data NONE>>

static VALUE
rb_data_initialize_m(int argc, const VALUE *argv, VALUE self)
{
    VALUE klass = rb_obj_class(self);
    rb_struct_modify(self);
    VALUE members = struct_ivar_get(klass, id_members);
    size_t num_members = RARRAY_LEN(members);

    if (argc == 0) {
        if (num_members > 0) {
            rb_exc_raise(rb_keyword_error_new("missing", members));
        }
        return Qnil;
    }
    if (argc > 1 || !RB_TYPE_P(argv[0], T_HASH)) {
        rb_error_arity(argc, 0, 0);
    }

    if (RHASH_SIZE(argv[0]) < num_members) {
        VALUE missing = rb_ary_diff(members, rb_hash_keys(argv[0]));
        rb_exc_raise(rb_keyword_error_new("missing", missing));
    }

    struct struct_hash_set_arg arg;
    rb_mem_clear((VALUE *)RSTRUCT_CONST_PTR(self), num_members);
    arg.self = self;
    arg.unknown_keywords = Qnil;
    rb_hash_foreach(argv[0], struct_hash_set_i, (VALUE)&arg);
    // Freeze early before potentially raising, so that we don't leave an
    // unfrozen copy on the heap, which could get exposed via ObjectSpace.
    OBJ_FREEZE_RAW(self);
    if (arg.unknown_keywords != Qnil) {
        rb_exc_raise(rb_keyword_error_new("unknown", arg.unknown_keywords));
    }
    return Qnil;
}

公共实例方法

self == other → true or false 单击以切换源

如果 other 与 self 为同一类，并且所有成员都相等，则返回 true。

示例

Measure = Data.define(:amount, :unit)

Measure[1, 'km'] == Measure[1, 'km'] #=> true
Measure[1, 'km'] == Measure[2, 'km'] #=> false
Measure[1, 'km'] == Measure[1, 'm']  #=> false

Measurement = Data.define(:amount, :unit)
# Even though Measurement and Measure have the same "shape"
# their instances are never equal
Measure[1, 'km'] == Measurement[1, 'km'] #=> false

#define rb_data_equal rb_struct_equal

deconstruct → array 单击以切换源

将 self 中的值作为数组返回，以用于模式匹配

Measure = Data.define(:amount, :unit)

distance = Measure[10, 'km']
distance.deconstruct #=> [10, "km"]

# usage
case distance
in n, 'km' # calls #deconstruct underneath
  puts "It is #{n} kilometers away"
else
  puts "Don't know how to handle it"
end
# prints "It is 10 kilometers away"

或者，也可以检查类

case distance
in Measure(n, 'km')
  puts "It is #{n} kilometers away"
# ...
end

#define rb_data_deconstruct rb_struct_to_a

deconstruct_keys(array_of_names_or_nil) → hash 单击以切换源

返回名称/值对的哈希，以用于模式匹配。

Measure = Data.define(:amount, :unit)

distance = Measure[10, 'km']
distance.deconstruct_keys(nil) #=> {:amount=>10, :unit=>"km"}
distance.deconstruct_keys([:amount]) #=> {:amount=>10}

# usage
case distance
in amount:, unit: 'km' # calls #deconstruct_keys underneath
  puts "It is #{amount} kilometers away"
else
  puts "Don't know how to handle it"
end
# prints "It is 10 kilometers away"

或者，也可以检查类

case distance
in Measure(amount:, unit: 'km')
  puts "It is #{amount} kilometers away"
# ...
end

#define rb_data_deconstruct_keys rb_struct_deconstruct_keys

eql?(other) → true 或 false 单击以切换源

当两个数据项是 Hash 的键时，使用此相等性检查。

与 == 的细微差别在于，成员还会与它们的 eql? 方法进行比较，这在某些情况下可能很重要

Measure = Data.define(:amount, :unit)

Measure[1, 'km'] == Measure[1.0, 'km'] #=> true, they are equal as values
# ...but...
Measure[1, 'km'].eql? Measure[1.0, 'km'] #=> false, they represent different hash keys

另请参阅 Object#eql? 以进一步了解方法用法。

#define rb_data_eql rb_struct_eql

hash → integer 单击以切换源

重新定义 Object#hash（用于将对象作为 Hash 键进行区分），以便具有相同内容的相同类的数据对象具有相同的 hash 值，并表示相同的 Hash 键。

Measure = Data.define(:amount, :unit)

Measure[1, 'km'].hash == Measure[1, 'km'].hash #=> true
Measure[1, 'km'].hash == Measure[10, 'km'].hash #=> false
Measure[1, 'km'].hash == Measure[1, 'm'].hash #=> false
Measure[1, 'km'].hash == Measure[1.0, 'km'].hash #=> false

# Structurally similar data class, but shouldn't be considered
# the same hash key
Measurement = Data.define(:amount, :unit)

Measure[1, 'km'].hash == Measurement[1, 'km'].hash #=> false

#define rb_data_hash rb_struct_hash

inspect → string 单击以切换源

返回 self 的字符串表示形式

Measure = Data.define(:amount, :unit)

distance = Measure[10, 'km']

p distance  # uses #inspect underneath
#<data Measure amount=10, unit="km">

puts distance  # uses #to_s underneath, same representation
#<data Measure amount=10, unit="km">

static VALUE
rb_data_inspect(VALUE s)
{
    return rb_exec_recursive(inspect_struct, s, rb_str_new2("#<data "));
}

别名：to_s

members → array_of_symbols 单击以切换源

将 self 中的成员名称作为数组返回

Measure = Data.define(:amount, :unit)
distance = Measure[10, 'km']

distance.members #=> [:amount, :unit]

#define rb_data_members_m rb_struct_members_m

to_h → hash 单击以切换源

to_h {|name, value| ... } → hash

返回数据对象的 Hash 表示形式。

Measure = Data.define(:amount, :unit)
distance = Measure[10, 'km']

distance.to_h
#=> {:amount=>10, :unit=>"km"}

与 Enumerable#to_h 类似，如果提供了块，则预期它会生成键值对来构造哈希

distance.to_h { |name, val| [name.to_s, val.to_s] }
#=> {"amount"=>"10", "unit"=>"km"}

请注意，to_h 和 initialize 之间存在有用的对称性

distance2 = Measure.new(**distance.to_h)
#=> #<data Measure amount=10, unit="km">
distance2 == distance
#=> true

#define rb_data_to_h rb_struct_to_h

to_s → string

返回 self 的字符串表示形式

Measure = Data.define(:amount, :unit)

distance = Measure[10, 'km']

p distance  # uses #inspect underneath
#<data Measure amount=10, unit="km">

puts distance  # uses #to_s underneath, same representation
#<data Measure amount=10, unit="km">

别名：inspect

with(**kwargs) → instance 单击以切换源

返回 self 的浅拷贝——复制 self 的实例变量，但不复制它们引用的对象。

如果方法提供了任何关键字参数，则将创建该副本，并使用提供的关键字参数值更新各个字段值。请注意，提供 Data 类不作为成员的关键字是错误的。

Point = Data.define(:x, :y)

origin = Point.new(x: 0, y: 0)

up = origin.with(x: 1)
right = origin.with(y: 1)
up_and_right = up.with(y: 1)

p origin       # #<data Point x=0, y=0>
p up           # #<data Point x=1, y=0>
p right        # #<data Point x=0, y=1>
p up_and_right # #<data Point x=1, y=1>

out = origin.with(z: 1) # ArgumentError: unknown keyword: :z
some_point = origin.with(1, 2) # ArgumentError: expected keyword arguments, got positional arguments

static VALUE
rb_data_with(int argc, const VALUE *argv, VALUE self)
{
    VALUE kwargs;
    rb_scan_args(argc, argv, "0:", &kwargs);
    if (NIL_P(kwargs)) {
        return self;
    }

    VALUE h = rb_struct_to_h(self);
    rb_hash_update_by(h, kwargs, 0);
    return rb_class_new_instance_kw(1, &h, rb_obj_class(self), TRUE);
}