ObjectSpace::WeakKeyMap を追加 (Ruby 3.3)

キーへの弱参照を持つマップのクラス。7 つのインスタンスメソッド
([] []= getkey key? delete clear inspect) を収録した。

実機で確認したところ 3.1 / 3.2 では未定義で、3.3 から追加されている。
3.3 / 3.4 / 4.0 でメソッド構成も挙動も同一なので、版の出し分けは
front matter の since: "3.3" だけで行い、本文に #%since は使っていない。

ObjectSpace::WeakMap との違い (値への参照が強参照、キーは同一性ではなく
等値性で比較、GC の対象になるオブジェクトだけをキーにできる) を冒頭に
整理した。

[]= には、GC の対象にならないオブジェクト (Integer や Symbol など) を
キーにすると ArgumentError ("WeakKeyMap keys must be garbage collectable")
になることを - **raise** に書いた。ri には記載が無いが、実用上ひっかかる制約。

あわせて ObjectSpace::WeakMap から姉妹クラスへの導線を追加した。WeakMap は
2.0 からあるため、#%since 3.3 で囲まないと 3.0〜3.2 でリンク切れになる。

記載した例はすべて 3.3 / 3.4 / 4.0 で実行して出力が一致することを確認した。
rake check_links はいずれの版も master と同数で、増えていない。

  3.0 : 258 -> 258
  3.2 : 296 -> 296
  3.3 : 295 -> 295
  4.0 : 297 -> 297

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Watson1978

manual/api/_builtin/ObjectSpace__WeakKeyMap.md

@@ -0,0 +1,176 @@
+---
+library: _builtin
+since: "3.3"
+---
+# class ObjectSpace::WeakKeyMap < Object
+
+キーへの弱参照を持つ、キーと値の組を保持するクラスです。
+
+キーは他から参照されなくなると GC の対象になり、そのときキーと値の組は
+map から取り除かれます。値への参照は強参照なので、map に入っている間は
+GC されません。
+
+[c:ObjectSpace::WeakMap] との違いは以下の 3 点です。
+
+  - 値への参照が強参照です。map に入っている間は GC されません。
+  - キーの比較が同一性([m:Object#equal?])ではなく等値性([m:Object#eql?])で
+    行われます。
+  - GC の対象になるオブジェクトだけをキーにできます。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+# キーは等値性で比較されるので、別のオブジェクトでも引ける
+p map["name"] # => 1
+
+key = nil
+GC.start
+# キーへの参照が無くなったので、キーと値の組が取り除かれる
+p map["name"] # => nil
+```
+
+上の例の [m:GC.start] は説明のために書いたもので、いつでもこのとおりに
+GC されるとは限りません。
+
+同じ値を表すオブジェクトを 1 つだけ保持しておきたい場合、たとえば
+軽量な値オブジェクトのキャッシュを実装する用途に向いています。
+[m:ObjectSpace::WeakKeyMap#getkey] を参照してください。
+
+## Instance Methods
+
+### def [](key) -> object | nil
+
+key に対応する値を返します。
+
+key に対応する組が無い場合は nil を返します。
+
+- **param** `key` -- 探すキーを指定します。等値性([m:Object#eql?])で比較されます。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+p map["name"] # => 1
+p map["zzz"]  # => nil
+```
+
+- **SEE** [m:ObjectSpace::WeakKeyMap#\[\]=], [m:ObjectSpace::WeakKeyMap#getkey]
+
+### def []=(key, value)
+
+key に対応する値として value を登録します。
+
+key への参照は弱参照です。他から key を参照するものが無くなると、
+キーと値の組は GC によって取り除かれます。値そのものへの参照は強参照です。
+
+key に対応する組が既にある場合は、値だけを置き換えます。
+
+- **param** `key` -- キーを指定します。GC の対象になるオブジェクトだけを
+             指定できます。
+
+- **param** `value` -- 値を指定します。
+
+- **raise** `ArgumentError` -- GC の対象にならないオブジェクト([c:Integer] や
+             [c:Symbol] など)をキーに指定した場合に発生します。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+p map["name"] # => 1
+
+map[key] = 2
+p map["name"] # => 2
+
+map[1] = 3 # ~> ArgumentError
+```
+
+- **SEE** [m:ObjectSpace::WeakKeyMap#\[\]]
+
+### def getkey(key) -> object | nil
+
+key と等値なキーが登録されていれば、登録されているほうのオブジェクトを
+返します。無い場合は nil を返します。
+
+同じ値を表すオブジェクトを 1 つにまとめる用途に使えます。
+
+- **param** `key` -- 探すキーを指定します。
+
+```ruby
+value = { amount: 1, currency: "USD" }
+
+cache = ObjectSpace::WeakKeyMap.new
+cache[value] = true
+
+# 等値な別のオブジェクトを渡しても、登録済みのオブジェクトが返る
+copy = cache.getkey({ amount: 1, currency: "USD" })
+p copy.equal?(value) # => true
+```
+
+- **SEE** [m:ObjectSpace::WeakKeyMap#\[\]]
+
+### def key?(key) -> bool
+
+key に対応する組があれば true を、無ければ false を返します。
+
+- **param** `key` -- 探すキーを指定します。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+p map.key?("name") # => true
+p map.key?("zzz")  # => false
+```
+
+### def delete(key) -> object | nil
+### def delete(key) {|key| ... } -> object
+
+key に対応する組を取り除き、その値を返します。
+
+key に対応する組が無い場合、ブロックを指定していなければ nil を返します。
+ブロックを指定していれば、key を引数としてブロックを実行し、その結果を返します。
+key に対応する組がある場合、ブロックは実行されません。
+
+- **param** `key` -- 取り除く組のキーを指定します。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+p map.delete("name") # => 1
+p map["name"]        # => nil
+
+p map.delete("zzz")                   # => nil
+p map.delete("zzz") { |k| "no #{k}" } # => "no zzz"
+```
+
+### def clear -> self
+
+すべての組を取り除きます。`self` を返します。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+map.clear
+p map["name"] # => nil
+```
+
+### def inspect -> String
+
+`self` の情報を含む文字列を返します。
+
+```ruby
+map = ObjectSpace::WeakKeyMap.new
+key = "name"
+map[key] = 1
+
+p map.inspect # => "#<ObjectSpace::WeakKeyMap:0x00007f8f0a0b1234 size=1>"
+```

manual/api/_builtin/ObjectSpace__WeakMap.md

@@ -15,6 +15,12 @@ deprecated になった Ruby 4.0 以降では、オブジェクト ID からオ
 主に [c:WeakRef] クラスの内部で使用されるため、[lib:weakref] ライブラリ
 経由で使用してください。
 #%end
+#%since 3.3
+
+キーだけを弱参照にし、値は強参照で保持するものとして
+[c:ObjectSpace::WeakKeyMap] があります。
+このクラスと違い、キーは同一性ではなく等値性で比較されます。
+#%end
 
 ## Public Instance Methods