Merge pull request #2894 from sanfrecce-osaka/add-deconstruct-and-dec…

…onstruct-keys

deconstruct と deconstruct keys についての説明を追加

refm/api/src/_builtin/Data

@@ -229,7 +229,7 @@ p dog1.equal?(dog2) # => false
 
 @see [[m:Object#==]], [[m:Data#eql?]]
 
---- deconstruct -> array
+--- deconstruct -> [object]
 
 self のメンバの値を配列で返します。
 
@@ -264,7 +264,9 @@ end
 
 #@include(Data.attention)
 
---- deconstruct_keys(array_of_names_or_nil) -> hash
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+
+--- deconstruct_keys(array_of_names_or_nil) -> Hash
 
 self のメンバの名前と値の組を Hash で返します。
 
@@ -302,6 +304,8 @@ end
 
 #@include(Data.attention)
 
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+
 --- eql?(other) -> bool
 
 self と other のクラスが同じであり、各メンバが eql? メソッドで比較して等しい場合に

refm/api/src/_builtin/MatchData

@@ -110,6 +110,9 @@ p $~.end(4) # => `end': index 4 out of matches (IndexError)
 @see [[m:MatchData#begin]]
 
 --- captures -> [String]
+#@since 3.2.0
+--- deconstruct -> [String]
+#@end
 
 [[m:$1]], [[m:$2]], ... を格納した配列を返します。
 
@@ -122,7 +125,33 @@ p $~.to_a # => ["foobar", "foo", "bar", nil]
 p $~.captures # => ["foo", "bar", nil]
 #@end
 
+#@since 3.2.0
+@see [[m:MatchData#to_a]], [[m:MatchData#named_captures]], [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@else
 @see [[m:MatchData#to_a]], [[m:MatchData#named_captures]]
+#@end
+
+#@since 3.2.0
+--- deconstruct_keys(array_of_names) -> Hash
+
+引数で指定された名前の名前付きキャプチャを [[c:Hash]] で返します。
+
+[[c:Hash]] のキーは名前付きキャプチャの名前のシンボル、値はキーの名前に対応した名前付きグループのうち最後にマッチした文字列です。
+
+@param array_of_names 名前付きキャプチャの名前の配列を指定します。nil の場合は全ての名前付きキャプチャを意味します。
+
+#@samplecode 例
+m = /(?<hours>\d{2}):(?<minutes>\d{2}):(?<seconds>\d{2})/.match("18:37:22")
+m.deconstruct_keys([:hours, :minutes]) # => {:hours => "18", :minutes => "37"}
+m.deconstruct_keys(nil) # => {:hours => "18", :minutes => "37", :seconds => "22"}
+
+# 名前付きキャプチャが定義されていなかった場合は空のハッシュを返す
+m = /(\d{2}):(\d{2}):(\d{2})/.match("18:37:22")
+m.deconstruct_keys(nil) # => {}
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end
 
 --- length -> Integer
 --- size -> Integer
@@ -400,4 +429,8 @@ m = /(?<a>x)|(?<a>y)/.match("x")
 m.named_captures # => {"a" => "x"}
 #@end
 
+#@since 3.2.0
+@see [[m:MatchData#captures]], [[m:MatchData#deconstruct_keys]]
+#@else
 @see [[m:MatchData#captures]]
+#@end

refm/api/src/_builtin/Struct

@@ -312,6 +312,9 @@ p Foo.new.members # => [:foo, :bar]
 
 --- values -> [object]
 --- to_a -> [object]
+#@since 2.7.0
+--- deconstruct -> [object]
+#@end
 構造体のメンバの値を配列にいれて返します。
 
 #@samplecode 例
@@ -322,6 +325,33 @@ Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345).to_a
 
 #@include(Struct.attention)
 
+#@since 2.7.0
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end
+
+#@since 2.7.0
+--- deconstruct_keys(array_of_names) -> Hash
+
+self のメンバの名前と値の組を [[c:Hash]] で返します。
+
+@param array_of_names 返り値に含めるメンバの名前の配列を指定します。nil の場合は全てのメンバを意味します。
+
+#@samplecode 例
+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"}
+
+# 引数が nil の場合は全てのメンバを返します。
+h = joe.deconstruct_keys(nil)
+h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
+#@end
+
+#@include(Struct.attention)
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end
+
 --- inspect -> String
 --- to_s -> String
 

refm/api/src/_builtin/Time

@@ -1126,3 +1126,51 @@ p t.subsec #=> (3/500000)
 to_f の値と subsec の値の下のほうの桁の値は異なる場合があります。
 というのは IEEE 754 double はそれを表すのに十分な精度を
 持たないからです。subsec で得られる値が正確です。
+
+#@since 3.2.0
+--- deconstruct_keys(array_of_names_or_nil) -> Hash
+
+パターンマッチに使用する名前と値の [[c:Hash]] を返します。
+
+キーに利用できる名前は以下の通りです。
+
+ * :year
+ * :month
+ * :day
+ * :yday
+ * :wday
+ * :hour
+ * :min
+ * :sec
+ * :subsec
+ * :dst
+ * :zone
+
+@param array_of_names_or_nil パターンマッチに使用する名前の配列を指定します。nil の場合は全てをパターンマッチに使用します。
+
+#@samplecode 例
+t = Time.utc(2022, 10, 5, 21, 25, 30)
+
+if t in wday: 3, day: ..7 # deconstruct_keys が使われます
+ puts "first Wednesday of the month"
+end
+#=> "first Wednesday of the month" が出力される
+
+case t
+in year: ...2022
+ puts "too old"
+in month: ..9
+ puts "quarter 1-3"
+in wday: 1..5, month:
+ puts "working day in month #{month}"
+end
+#=> "working day in month 10" が出力される
+
+# クラスのチェックと組み合わせて利用することもできます
+if t in Time(wday: 3, day: ..7)
+ puts "first Wednesday of the month"
+end
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end

refm/api/src/csv/CSV__Row

@@ -420,6 +420,49 @@ row = CSV::Row.new(["header2", "header1", "header2"], [1, 2, 3])
 row.to_hash # => {"header2"=>3, "header1"=>2}
 #@end
 
+#@since 3.1.0
+--- deconstruct -> [object]
+
+パターンマッチに使用する行の値の配列を返します。
+
+#@samplecode 例
+require "csv"
+row = CSV::Row.new(["header1", "header2", "header3"], [1, 2, 3])
+case row
+in [2.., 2.., 2..]
+ puts "all 2 or more"
+in [...2, 2.., 2..]
+ puts "first column is less than 2, and rest columns are 2 or more"
+end
+#=> "first column is less than 2, and rest columns are 2 or more" が出力される
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+
+--- deconstruct_keys(keys) -> Hash
+
+パターンマッチに使用するヘッダの名前と値の [[c:Hash]] を返します。
+
+このメソッドはヘッダ名の型をシンボルに変換しないため、ヘッダ名が文字列かつ Hash パターン でパターンマッチしたい場合はキーをシンボルに変換する必要があります。
+
+@param keys パターンマッチに使用するヘッダの名前の配列を指定します。nil の場合は全てをパターンマッチに使用します。
+
+#@samplecode 例
+require "csv"
+
+row = CSV::Row.new([:header1, :header2, :header3], [1, 2, 3])
+case row
+in { header1: 2.., header2: 2.., header3: 2.. }
+ puts "all 2 or more"
+in { header1: ...2, header2: 2.., header3: 2.. }
+ puts "first column is less than 2, and rest columns are 2 or more"
+end
+#=> "first column is less than 2, and rest columns are 2 or more" が出力される
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end
+
 == Protected Instance Methods
 
 --- row -> Array

refm/api/src/date/Date

@@ -812,6 +812,48 @@ XML Scheme (date) による書式の文字列を返します。
 --- year -> Integer
 年を返します。
 
+#@since 3.2.0
+--- deconstruct_keys(array_of_names_or_nil) -> Hash
+
+パターンマッチに使用する名前と値の [[c:Hash]] を返します。
+
+キーに利用できる名前は以下の通りです。
+
+ * :year
+ * :month
+ * :day
+ * :yday
+ * :wday
+
+@param array_of_names_or_nil パターンマッチに使用する名前の配列を指定します。nil の場合は全てをパターンマッチに使用します。
+
+#@samplecode 例
+d = Date.new(2022, 10, 5)
+
+if d in wday: 3, day: ..7 # deconstruct_keys が使われます
+ puts "first Wednesday of the month"
+end
+#=> "first Wednesday of the month" が出力される
+
+case d
+in year: ...2022
+ puts "too old"
+in month: ..9
+ puts "quarter 1-3"
+in wday: 1..5, month:
+ puts "working day in month #{month}"
+end
+#=> "working day in month 10" が出力される
+
+# クラスのチェックと組み合わせて利用することもできます
+if d in Date(wday: 3, day: ..7)
+ puts "first Wednesday of the month"
+end
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end
+
 = reopen Time
 
 == Instance Methods
@@ -824,3 +866,4 @@ XML Scheme (date) による書式の文字列を返します。
 
 --- to_time -> Time
 対応する [[c:Time]] オブジェクトを返します。
+

refm/api/src/date/DateTime

@@ -309,3 +309,50 @@ self を複製して、その時差を設定しなおします。
 --- second_fraction -> Rational
 #@end
 秒の小数点以下の部分を表す分数を返します。
+
+#@since 3.2.0
+--- deconstruct_keys(array_of_names_or_nil) -> Hash
+
+パターンマッチに使用する名前と値の [[c:Hash]] を返します。
+
+キーに利用できる名前は以下の通りです。
+
+ * :year
+ * :month
+ * :day
+ * :yday
+ * :wday
+ * :hour
+ * :min
+ * :sec
+ * :sec_fraction
+ * :zone
+
+@param array_of_names_or_nil パターンマッチに使用する名前の配列を指定します。nil の場合は全てをパターンマッチに使用します。
+
+#@samplecode 例
+dt = DateTime.new(2022, 10, 5, 13, 30)
+
+if dt in wday: 1..5, hour: 10..18 # deconstruct_keys が使われます
+ puts "Working time"
+end
+#=> "Working time" が出力される
+
+case dt
+in year: ...2022
+ puts "too old"
+in month: ..9
+ puts "quarter 1-3"
+in wday: 1..5, month:
+ puts "working day in month #{month}"
+end
+#=> "working day in month 10" が出力される
+
+# クラスのチェックと組み合わせて利用することもできます
+if dt in DateTime(wday: 1..5, hour: 10..18, day: ..7)
+ puts "Working time, first week of the month"
+end
+#@end
+
+@see [[ref:d:spec/pattern_matching#matching_non_primitive_objects]]
+#@end