rbs 3.10.0.pre.2 → 3.10.0

data/core/set.rbs

@@ -1,16 +1,9 @@
 # <!-- rdoc-file=set.c -->
-# Copyright (c) 2002-2024 Akinori MUSHA <knu@iDaemons.org>
-#
-# Documentation by Akinori MUSHA and Gavin Sinclair.
-#
-# All rights reserved.  You can redistribute and/or modify it under the same
-# terms as Ruby.
-#
 # The Set class implements a collection of unordered values with no duplicates.
 # It is a hybrid of Array's intuitive inter-operation facilities and Hash's fast
 # lookup.
 #
-# Set is easy to use with Enumerable objects (implementing `each`). Most of the
+# Set is easy to use with Enumerable objects (implementing #each). Most of the
 # initializer methods and binary operators accept generic Enumerable objects
 # besides sets and arrays.  An Enumerable object can be converted to Set using
 # the `to_set` method.
@@ -36,11 +29,11 @@
 #
 # ## Example
 #
-#     s1 = Set[1, 2]                        #=> #<Set: {1, 2}>
-#     s2 = [1, 2].to_set                    #=> #<Set: {1, 2}>
+#     s1 = Set[1, 2]                        #=> Set[1, 2]
+#     s2 = [1, 2].to_set                    #=> Set[1, 2]
 #     s1 == s2                              #=> true
-#     s1.add("foo")                         #=> #<Set: {1, 2, "foo"}>
-#     s1.merge([2, 6])                      #=> #<Set: {1, 2, "foo", 6}>
+#     s1.add("foo")                         #=> Set[1, 2, "foo"]
+#     s1.merge([2, 6])                      #=> Set[1, 2, "foo", 6]
 #     s1.subset?(s2)                        #=> false
 #     s2.subset?(s1)                        #=> true
 #
@@ -48,9 +41,39 @@
 #
 # *   Akinori MUSHA <knu@iDaemons.org> (current maintainer)
 #
-# ## What's Here
+# ## Inheriting from Set
+#
+# Before Ruby 4.0 (released December 2025), Set had a different, less efficient
+# implementation. It was reimplemented in C, and the behavior of some of the
+# core methods were adjusted.
+#
+# To keep backward compatibility, when a class is inherited from Set, additional
+# module `Set::SubclassCompatible` is included, which makes the inherited class
+# behavior, as well as internal method names, closer to what it was before Ruby
+# 4.0.
+#
+# It can be easily seen, for example, in the #inspect method behavior:
+#
+#     p Set[1, 2, 3]
+#     # prints "Set[1, 2, 3]"
+#
+#     class MySet < Set
+#     end
+#     p MySet[1, 2, 3]
+#     # prints "#<MySet: {1, 2, 3}>", like it was in Ruby 3.4
+#
+# For new code, if backward compatibility is not necessary, it is recommended to
+# instead inherit from `Set::CoreSet`, which avoids including the
+# "compatibility" layer:
+#
+#     class MyCoreSet < Set::CoreSet
+#     end
+#     p MyCoreSet[1, 2, 3]
+#     # prints "MyCoreSet[1, 2, 3]"
+#
+# ## Set's methods
 #
-#     First, what's elsewhere. \Class \Set:
+# First, what's elsewhere. Class Set:
 #
 # *   Inherits from [class Object](rdoc-ref:Object@What-27s+Here).
 # *   Includes [module Enumerable](rdoc-ref:Enumerable@What-27s+Here), which
@@ -61,16 +84,15 @@
 #
 # Here, class Set provides methods that are useful for:
 #
-# *   [Creating an Array](rdoc-ref:Array@Methods+for+Creating+an+Array)
 # *   [Creating a Set](rdoc-ref:Set@Methods+for+Creating+a+Set)
 # *   [Set Operations](rdoc-ref:Set@Methods+for+Set+Operations)
-# *   [Comparing](rdoc-ref:Array@Methods+for+Comparing)
-# *   [Querying](rdoc-ref:Array@Methods+for+Querying)
-# *   [Assigning](rdoc-ref:Array@Methods+for+Assigning)
-# *   [Deleting](rdoc-ref:Array@Methods+for+Deleting)
-# *   [Converting](rdoc-ref:Array@Methods+for+Converting)
-# *   [Iterating](rdoc-ref:Array@Methods+for+Iterating)
-# *   [And more....](rdoc-ref:Array@Other+Methods)
+# *   [Comparing](rdoc-ref:Set@Methods+for+Comparing)
+# *   [Querying](rdoc-ref:Set@Methods+for+Querying)
+# *   [Assigning](rdoc-ref:Set@Methods+for+Assigning)
+# *   [Deleting](rdoc-ref:Set@Methods+for+Deleting)
+# *   [Converting](rdoc-ref:Set@Methods+for+Converting)
+# *   [Iterating](rdoc-ref:Set@Methods+for+Iterating)
+# *   [And more....](rdoc-ref:Set@Other+Methods)
 #
 # ### Methods for Creating a Set
 #
@@ -183,11 +205,11 @@ class Set[unchecked out A]
   #
   # If a block is given, the elements of enum are preprocessed by the given block.
   #
-  #     Set.new([1, 2])                       #=> #<Set: {1, 2}>
-  #     Set.new([1, 2, 1])                    #=> #<Set: {1, 2}>
-  #     Set.new([1, 'c', :s])                 #=> #<Set: {1, "c", :s}>
-  #     Set.new(1..5)                         #=> #<Set: {1, 2, 3, 4, 5}>
-  #     Set.new([1, 2, 3]) { |x| x * x }      #=> #<Set: {1, 4, 9}>
+  #     Set.new([1, 2])                       #=> Set[1, 2]
+  #     Set.new([1, 2, 1])                    #=> Set[1, 2]
+  #     Set.new([1, 'c', :s])                 #=> Set[1, "c", :s]
+  #     Set.new(1..5)                         #=> Set[1, 2, 3, 4, 5]
+  #     Set.new([1, 2, 3]) { |x| x * x }      #=> Set[1, 4, 9]
   #
   def initialize: (_Each[A]) -> untyped
                 | [X] (_Each[X]) { (X) -> A } -> untyped
@@ -208,8 +230,8 @@ class Set[unchecked out A]
   # Returns a new set containing elements common to the set and the given
   # enumerable object.
   #
-  #     Set[1, 3, 5] & Set[3, 2, 1]             #=> #<Set: {3, 1}>
-  #     Set['a', 'b', 'z'] & ['a', 'b', 'c']    #=> #<Set: {"a", "b"}>
+  #     Set[1, 3, 5] & Set[3, 2, 1]             #=> Set[3, 1]
+  #     Set['a', 'b', 'z'] & ['a', 'b', 'c']    #=> Set["a", "b"]
   #
   def &: (_Each[A]) -> self
 
@@ -217,8 +239,8 @@ class Set[unchecked out A]
   # Returns a new set containing elements common to the set and the given
   # enumerable object.
   #
-  #     Set[1, 3, 5] & Set[3, 2, 1]             #=> #<Set: {3, 1}>
-  #     Set['a', 'b', 'z'] & ['a', 'b', 'c']    #=> #<Set: {"a", "b"}>
+  #     Set[1, 3, 5] & Set[3, 2, 1]             #=> Set[3, 1]
+  #     Set['a', 'b', 'z'] & ['a', 'b', 'c']    #=> Set["a", "b"]
   #
   alias intersection &
 
@@ -229,8 +251,8 @@ class Set[unchecked out A]
   # Returns a new set built by merging the set and the elements of the given
   # enumerable object.
   #
-  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> #<Set: {1, 2, 3, 4, 5}>
-  #     Set[1, 5, 'z'] | (1..6)             #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
+  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> Set[1, 2, 3, 4, 5]
+  #     Set[1, 5, 'z'] | (1..6)             #=> Set[1, 5, "z", 2, 3, 4, 6]
   #
   def |: (_Each[A]) -> self
 
@@ -238,8 +260,8 @@ class Set[unchecked out A]
   # Returns a new set built by merging the set and the elements of the given
   # enumerable object.
   #
-  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> #<Set: {1, 2, 3, 4, 5}>
-  #     Set[1, 5, 'z'] | (1..6)             #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
+  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> Set[1, 2, 3, 4, 5]
+  #     Set[1, 5, 'z'] | (1..6)             #=> Set[1, 5, "z", 2, 3, 4, 6]
   #
   alias union |
 
@@ -247,8 +269,8 @@ class Set[unchecked out A]
   # Returns a new set built by merging the set and the elements of the given
   # enumerable object.
   #
-  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> #<Set: {1, 2, 3, 4, 5}>
-  #     Set[1, 5, 'z'] | (1..6)             #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
+  #     Set[1, 2, 3] | Set[2, 4, 5]         #=> Set[1, 2, 3, 4, 5]
+  #     Set[1, 5, 'z'] | (1..6)             #=> Set[1, 5, "z", 2, 3, 4, 6]
   #
   alias + |
 
@@ -259,8 +281,8 @@ class Set[unchecked out A]
   # Returns a new set built by duplicating the set, removing every element that
   # appears in the given enumerable object.
   #
-  #     Set[1, 3, 5] - Set[1, 5]                #=> #<Set: {3}>
-  #     Set['a', 'b', 'z'] - ['a', 'c']         #=> #<Set: {"b", "z"}>
+  #     Set[1, 3, 5] - Set[1, 5]                #=> Set[3]
+  #     Set['a', 'b', 'z'] - ['a', 'c']         #=> Set["b", "z"]
   #
   def -: (_Each[A]) -> self
 
@@ -268,8 +290,8 @@ class Set[unchecked out A]
   # Returns a new set built by duplicating the set, removing every element that
   # appears in the given enumerable object.
   #
-  #     Set[1, 3, 5] - Set[1, 5]                #=> #<Set: {3}>
-  #     Set['a', 'b', 'z'] - ['a', 'c']         #=> #<Set: {"b", "z"}>
+  #     Set[1, 3, 5] - Set[1, 5]                #=> Set[3]
+  #     Set['a', 'b', 'z'] - ['a', 'c']         #=> Set["b", "z"]
   #
   alias difference -
 
@@ -280,9 +302,9 @@ class Set[unchecked out A]
   # Adds the given object to the set and returns self.  Use `merge` to add many
   # elements at once.
   #
-  #     Set[1, 2].add(3)                    #=> #<Set: {1, 2, 3}>
-  #     Set[1, 2].add([3, 4])               #=> #<Set: {1, 2, [3, 4]}>
-  #     Set[1, 2].add(2)                    #=> #<Set: {1, 2}>
+  #     Set[1, 2].add(3)                    #=> Set[1, 2, 3]
+  #     Set[1, 2].add([3, 4])               #=> Set[1, 2, [3, 4]]
+  #     Set[1, 2].add(2)                    #=> Set[1, 2]
   #
   def add: (A) -> self
 
@@ -290,9 +312,9 @@ class Set[unchecked out A]
   # Adds the given object to the set and returns self.  Use `merge` to add many
   # elements at once.
   #
-  #     Set[1, 2].add(3)                    #=> #<Set: {1, 2, 3}>
-  #     Set[1, 2].add([3, 4])               #=> #<Set: {1, 2, [3, 4]}>
-  #     Set[1, 2].add(2)                    #=> #<Set: {1, 2}>
+  #     Set[1, 2].add(3)                    #=> Set[1, 2, 3]
+  #     Set[1, 2].add([3, 4])               #=> Set[1, 2, [3, 4]]
+  #     Set[1, 2].add(2)                    #=> Set[1, 2]
   #
   alias << add
 
@@ -303,8 +325,8 @@ class Set[unchecked out A]
   # Adds the given object to the set and returns self. If the object is already in
   # the set, returns nil.
   #
-  #     Set[1, 2].add?(3)                    #=> #<Set: {1, 2, 3}>
-  #     Set[1, 2].add?([3, 4])               #=> #<Set: {1, 2, [3, 4]}>
+  #     Set[1, 2].add?(3)                    #=> Set[1, 2, 3]
+  #     Set[1, 2].add?([3, 4])               #=> Set[1, 2, [3, 4]]
   #     Set[1, 2].add?(2)                    #=> nil
   #
   def add?: (A) -> self?
@@ -366,8 +388,8 @@ class Set[unchecked out A]
   # enumerable object.  `(set ^ enum)` is equivalent to `((set | enum) - (set &
   # enum))`.
   #
-  #     Set[1, 2] ^ Set[2, 3]                   #=> #<Set: {3, 1}>
-  #     Set[1, 'b', 'c'] ^ ['b', 'd']           #=> #<Set: {"d", 1, "c"}>
+  #     Set[1, 2] ^ Set[2, 3]                   #=> Set[3, 1]
+  #     Set[1, 'b', 'c'] ^ ['b', 'd']           #=> Set["d", 1, "c"]
   #
   def ^: (_Each[A]) -> self
 
@@ -382,9 +404,9 @@ class Set[unchecked out A]
   #
   #     files = Set.new(Dir.glob("*.rb"))
   #     hash = files.classify { |f| File.mtime(f).year }
-  #     hash       #=> {2000 => #<Set: {"a.rb", "b.rb"}>,
-  #                #    2001 => #<Set: {"c.rb", "d.rb", "e.rb"}>,
-  #                #    2002 => #<Set: {"f.rb"}>}
+  #     hash       #=> {2000 => Set["a.rb", "b.rb"],
+  #                #    2001 => Set["c.rb", "d.rb", "e.rb"],
+  #                #    2002 => Set["f.rb"]}
   #
   # Returns an enumerator if no block is given.
   #
@@ -396,9 +418,9 @@ class Set[unchecked out A]
   # -->
   # Removes all elements and returns self.
   #
-  #     set = Set[1, 'c', :s]             #=> #<Set: {1, "c", :s}>
-  #     set.clear                         #=> #<Set: {}>
-  #     set                               #=> #<Set: {}>
+  #     set = Set[1, 'c', :s]             #=> Set[1, "c", :s]
+  #     set.clear                         #=> Set[]
+  #     set                               #=> Set[]
   #
   def clear: () -> self
 
@@ -502,10 +524,10 @@ class Set[unchecked out A]
   #
   #     numbers = Set[1, 3, 4, 6, 9, 10, 11]
   #     set = numbers.divide { |i,j| (i - j).abs == 1 }
-  #     set        #=> #<Set: {#<Set: {1}>,
-  #                #           #<Set: {3, 4}>,
-  #                #           #<Set: {6}>}>
-  #                #           #<Set: {9, 10, 11}>,
+  #     set        #=> Set[Set[1],
+  #                #       Set[3, 4],
+  #                #       Set[6],
+  #                #       Set[9, 10, 11]]
   #
   # Returns an enumerator if no block is given.
   #
@@ -654,9 +676,9 @@ class Set[unchecked out A]
   # Replaces the contents of the set with the contents of the given enumerable
   # object and returns self.
   #
-  #     set = Set[1, 'c', :s]             #=> #<Set: {1, "c", :s}>
-  #     set.replace([1, 2])               #=> #<Set: {1, 2}>
-  #     set                               #=> #<Set: {1, 2}>
+  #     set = Set[1, 'c', :s]             #=> Set[1, "c", :s]
+  #     set.replace([1, 2])               #=> Set[1, 2]
+  #     set                               #=> Set[1, 2]
   #
   def replace: (_Each[A]) -> self