Struct

= class Struct < Object

include Enumerable

構造体クラス。Struct.new はこのクラスのサブクラスを新たに生成します。

個々の構造体はサブクラスから [[m:Struct.new]] を使って生成します。個々
の構造体サブクラスでは構造体のメンバに対するアクセスメソッドが定義され
ています。

== Class Methods

#@since 2.5.0
--- new(*args, keyword_init: false)                  -> Class
--- new(*args, keyword_init: false) {|Class| block } -> Class
#@else
--- new(*args)                  -> Class
--- new(*args) {|Class| block } -> Class
#@end

[[c:Struct]] クラスに新しいサブクラスを作って、それを返します。

サブクラスでは構造体のメンバに対するアクセスメソッドが定義されています。

#@samplecode 例
dog = Struct.new("Dog", :name, :age)
fred = dog.new("fred", 5)
fred.age = 6
printf "name:%s age:%d", fred.name, fred.age
#=> "name:fred age:6" を出力します
#@end

実装の都合により、クラス名の省略は後づけの機能でした。
メンバ名に [[c:String]] を指定できるのは後方互換性のためだと考えた方が良いでしょう。
したがって、メンバ名は [[c:Symbol]] で指定するのが無難です。

@param args 構造体を定義するための可変長引数。[[c:String]] または [[c:Symbol]] を指定します。
#@since 2.5.0
@param keyword_init true を指定すると、キーワード引数で初期化する構造体を定義します。
#@end

=== 第一引数が String の場合
args[0] が [[c:String]] の場合、クラス名になるので、大文字で始まる必要
があります。つまり、以下のような指定はエラーになります。

#@samplecode 例
p Struct.new('foo', 'bar')
# => -:1:in `new': identifier foo needs to be constant (NameError)
#@end

また args[1..-1] は、[[c:Symbol]] か [[c:String]] で指定します。

#@samplecode 例
p Struct.new("Foo", :foo, :bar)   # => Struct::Foo
#@end

=== 第一引数が Symbol の場合
args[0] が [[c:Symbol]] の場合、生成した構造体クラスは名前の無い
クラスになります。名前の無いクラスは最初に名前を求める際に代入され
ている定数名を検索し、見つかった定数名をクラス名とします。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
p Foo                             # => Foo
#@end

=== ブロックを指定した場合

Struct.new にブロックを指定した場合は定義した Struct をコンテキストにブ
ロックを評価します。また、定義した Struct はブロックパラメータにも渡さ
れます。

#@samplecode 例
Customer = Struct.new(:name, :address) do
  def greeting
    "Hello #{name}!"
  end
end
Customer.new("Dave", "123 Main").greeting # => "Hello Dave!"
#@end

Structをカスタマイズする場合はこの方法が推奨されます。無名クラスのサブ
クラスを作成する方法でカスタマイズする場合は無名クラスが使用されなくなっ
てしまうことがあるためです。

@see [[m:Class.new]]

#@since 2.5.0
=== keyword_init: true を指定した場合

キーワード引数で初期化することを想定した構造体になります。

#@samplecode 例
Point = Struct.new(:x, :y, keyword_init: true) # => Point(keyword_init: true)
Point.new(x: 1, y: 2) # => #<struct Point x=1, y=2>
Point.new(x: 1)       # => #<struct Point x=1, y=nil>
Point.new(y: 2)       # => #<struct Point x=nil, y=2>
Point.new(z: 3)       # ArgumentError (unknown keywords: z)
#@end
#@end

--- new(*args) -> Struct
--- [](*args) -> Struct
(このメソッドは Struct の下位クラスにのみ定義されています)
構造体オブジェクトを生成して返します。

@param args 構造体の初期値を指定します。メンバの初期値は指定されなければ nil です。

@return 構造体クラスのインスタンス。

@raise ArgumentError 構造体のメンバの数よりも多くの引数を指定した場合に発生します。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
foo = Foo.new(1)
p foo.values      # => [1, nil]
#@end

--- members -> [Symbol]
(このメソッドは Struct の下位クラスにのみ定義されています)
構造体のメンバの名前([[c:Symbol]])の配列を返します。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
p Foo.members      # => [:foo, :bar]
#@end

== Instance Methods

--- [](member) -> object
構造体のメンバの値を返します。

@param member [[c:Integer]] でメンバのインデックスを指定します。
              [[c:Symbol]], [[c:String]] でメンバの名前を指定します。

@raise IndexError member が整数で存在しないメンバを指定した場合に発生します。

@raise NameError member が [[c:String]], [[c:Symbol]] で存在しないメンバを指定した場合に発生します。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
obj = Foo.new('FOO', 'BAR')
p obj[:foo]     # => "FOO"
p obj['bar']    # => "BAR"
# p obj[:baz]     # => in `[]': no member 'baz' in struct (NameError)
p obj[0]        # => "FOO"
p obj[1]        # => "BAR"
p obj[-1]       # => "BAR"    # Array のように負のインデックスも指定できます。
p obj[2]        # => in `[]': offset 2 too large for struct(size:2) (IndexError)
#@end

#@include(Struct.attention)

--- []=(member, value)
構造体の member で指定されたメンバの値を value にして value を返します。

@param member [[c:Integer]] でメンバのインデックスを指定します。
              [[c:Symbol]], [[c:String]] でメンバの名前を指定します。

@param value メンバに設定する値を指定します。

@raise IndexError member が整数で存在しないメンバを指定した場合に発生します。

@raise NameError member が [[c:String]], [[c:Symbol]] で存在しないメンバを指定した場合に発生します。

#@include(Struct.attention)

#@samplecode 例
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"
#@end

--- each {|value| ... } -> self
#@since 1.9.1
--- each -> Enumerator
#@else
--- each -> Enumerable::Enumerator
#@end
構造体の各メンバに対して繰り返します。

#@include(Struct.attention)

#@samplecode 例
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.each {|x| puts(x) }

# => Joe Smith
#    123 Maple, Anytown NC
#    12345
#@end

--- each_pair {|member, value| ... } -> self
#@since 1.9.1
--- each_pair -> Enumerator
#@else
--- each_pair -> Enumerable::Enumerator
#@end
構造体のメンバ名([[c:Symbol]])と値の組を引数にブロックを繰り返し実行します。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
Foo.new('FOO', 'BAR').each_pair {|m, v| p [m,v]}
# => [:foo, "FOO"]
#    [:bar, "BAR"]
#@end

#@include(Struct.attention)

--- length -> Integer
--- size -> Integer
構造体のメンバの数を返します。

#@include(Struct.attention)

#@samplecode 例
Customer = Struct.new(:name, :address, :zip)
joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
joe.length   #=> 3
#@end

--- members -> [Symbol]
構造体のメンバの名前([[c:Symbol]])の配列を返します。

#@samplecode 例
Foo = Struct.new(:foo, :bar)
p Foo.new.members  # => [:foo, :bar]
#@end

#@include(Struct.attention)

--- values -> [object]
--- to_a -> [object]
構造体のメンバの値を配列にいれて返します。

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

#@include(Struct.attention)

--- inspect -> String
--- to_s    -> String

self の内容を人間に読みやすい文字列にして返します。

#@include(Struct.attention)

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

--- select {|i| ... } -> [object]
#@since 1.9.1
--- select -> Enumerator
#@end
#@since 2.6.0
--- filter {|i| ... } -> [object]
--- filter -> Enumerator
#@end

構造体のメンバの値に対してブロックを評価した値が真であった要素を全て含
む配列を返します。真になる要素がひとつもなかった場合は空の配列を返しま
す。

#@since 1.9.1
ブロックを省略した場合は [[c:Enumerator]] を返します。
#@end

#@samplecode 例
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]
#@end

#@include(Struct.attention)

@see [[m:Enumerable#select]]

--- values_at(*members) -> [object]
引数で指定されたメンバの値の配列を返します。

@param members [[c:Integer]] か [[c:Range]] でメンバのインデックスを指定します。

@raise IndexError member が整数で存在しないメンバを指定した場合に発生します。

#@samplecode 例
Foo = Struct.new(:foo, :bar, :baz)
obj = Foo.new('FOO', 'BAR', 'BAZ')
p obj.values_at(0, 1, 2)    # => ["FOO", "BAR", "BAZ"]
#@end

#@include(Struct.attention)

#@since 2.3.0
--- dig(key, ...) -> object | nil

self 以下のネストしたオブジェクトを dig メソッドで再帰的に参照して返し
ます。途中のオブジェクトが nil であった場合は nil を返します。

@param key キーを任意個指定します。

#@samplecode 例
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
#@end

@see [[m:Array#dig]], [[m:Hash#dig]], [[m:OpenStruct#dig]]
#@end

--- ==(other)    -> bool

self と other のクラスが同じであり、各メンバが == メソッドで比較して等しい場合に
true を返します。そうでない場合に false を返します。

@param other self と比較したいオブジェクトを指定します。

#@samplecode 例
Dog = Struct.new(:name, :age)
dog1 = Dog.new("fred", 5)
dog2 = Dog.new("fred", 5)

p dog1 == dog2                #=> true
p dog1.eql?(dog2)             #=> true
p dog1.equal?(dog2)           #=> false
#@end

#@include(Struct.attention)

@see [[m:Struct#eql?]]

--- eql?(other)    -> bool

self と other のクラスが同じであり、各メンバが eql? メソッドで比較して等しい場合に
true を返します。そうでない場合に false を返します。

@param other self と比較したいオブジェクトを指定します。

#@samplecode 例
Dog = Struct.new(:name, :age)
dog1 = Dog.new("fred", 5)
dog2 = Dog.new("fred", 5)

p dog1 == dog2                #=> true
p dog1.eql?(dog2)             #=> true
p dog1.equal?(dog2)           #=> false
#@end

#@include(Struct.attention)

@see [[m:Struct#==]]

--- equal?(other)   -> bool

指定された other が self 自身である場合のみ真を返します。
これは [[c:Object]] クラスで定義されたデフォルトの動作で
す。

#@include(Struct.attention)

#@#noexample Object#equal? のデフォルトの動作と変わらないため

@see [[m:Struct#eql?]], [[m:Struct#==]]

--- hash    -> Integer

self が保持するメンバのハッシュ値を元にして算出した整数を返します。
self が保持するメンバの値が変化すればこのメソッドが返す値も変化します。

#@samplecode 例
Dog = Struct.new(:name, :age)
dog = Dog.new("fred", 5)
p dog.hash                    #=> 7917421
dog.name = "john"
p dog.hash                    #=> -38913223
#@end

#@include(Struct.attention)
#@since 2.0.0
--- to_h -> Hash
#@since 2.6.0
--- to_h {|member, value| block } -> Hash
#@end

self のメンバ名([[c:Symbol]])と値の組を [[c:Hash]] にして返します。

#@samplecode 例
Customer = Struct.new(:name, :address, :zip)
Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345).to_h
# => {:name=>"Joe Smith", :address=>"123 Maple, Anytown NC", :zip=>12345}
#@end

#@since 2.6.0
ブロックを指定すると各ペアでブロックを呼び出し、
その結果をペアとして使います。
#@samplecode ブロック付きの例
Customer = Struct.new(:name, :address, :zip)
Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345).to_h {|member, value|
  [member, value*2]
} # => {:name=>"Joe SmithJoe Smith", :address=>"123 Maple, Anytown NC123 Maple, Anytown NC", :zip=>24690}
#@end
#@end

#@include(Struct.attention)
#@end