rbs 3.3.2 → 3.4.0

data/core/object_space/weak_key_map.rbs

@@ -0,0 +1,102 @@
+%a{annotate:rdoc:skip}
+module ObjectSpace
+  # <!-- rdoc-file=weakmap.c -->
+  # An ObjectSpace::WeakKeyMap object holds references to any objects, but objects
+  # uses as keys can be garbage collected.
+  #
+  # Objects used as values can't be garbage collected until the key is.
+  #
+  class WeakKeyMap[Key, Value]
+    public
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] -> value
+    # -->
+    # Returns the value associated with the given `key` if found.
+    #
+    # If `key` is not found, returns `nil`.
+    #
+    def []: (Key) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map[key] = value -> value
+    # -->
+    # Associates the given `value` with the given `key`; returns `value`.
+    #
+    # The reference to `key` is weak, so when there is no other reference to `key`
+    # it may be garbage collected.
+    #
+    # If the given `key` exists, replaces its value with the given `value`; the
+    # ordering is not affected
+    #
+    def []=: (Key, Value?) -> Value?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.clear -> self
+    # -->
+    # Removes all map entries; returns `self`.
+    #
+    def clear: () -> self
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.delete(key) -> value or nil
+    #   - map.delete(key) {|key| ... } -> object
+    # -->
+    # Deletes the entry for the given `key` and returns its associated value.
+    #
+    # If no block is given and `key` is found, deletes the entry and returns the
+    # associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m["foo"] = 1
+    #     m.delete("foo") # => 1
+    #     m["foo"] # => nil
+    #
+    # If no block given and `key` is not found, returns `nil`.
+    #
+    # If a block is given and `key` is found, ignores the block, deletes the entry,
+    # and returns the associated value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m["foo"] = 2
+    #     h.delete("foo") { |key| raise 'Will never happen'} # => 2
+    #
+    # If a block is given and `key` is not found, calls the block and returns the
+    # block's return value:
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     h.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"
+    #
+    def delete: (Key) -> Value?
+              | [T] (Key) { (Key) -> T } -> (Value | T)
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.getkey(key) -> existing_key or nil
+    # -->
+    # Returns the existing equal key if it exists, otherwise returns `nil`.
+    #
+    def getkey: (untyped) -> Key?
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - map.inspect -> new_string
+    # -->
+    # Returns a new String containing informations about the map:
+    #
+    #     m = ObjectSpace::WeakKeyMap.new
+    #     m[key] = value
+    #     m.inspect # => "#<ObjectSpace::WeakKeyMap:0x00000001028dcba8 size=1>"
+    #
+    def inspect: () -> String
+
+    # <!--
+    #   rdoc-file=weakmap.c
+    #   - hash.key?(key) -> true or false
+    # -->
+    # Returns `true` if `key` is a key in `self`, otherwise `false`.
+    #
+    def key?: (Key) -> bool
+  end
+end