File: //usr/lib/ruby/gems/3.2.0/gems/rbs-2.8.2/stdlib/set/0/set.rbs
# <!-- rdoc-file=lib/set.rb -->
# This library provides the Set class, which deals with a collection
# of unordered values with no duplicates. It is a hybrid of Array's
# intuitive inter-operation facilities and Hash's fast lookup.
# The method `to_set` is added to Enumerable for convenience.
# Set implements a collection of unordered values with no duplicates.
# This 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 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.
# Set uses Hash as storage, so you must note the following points:
# * Equality of elements is determined according to Object#eql? and
# Object#hash. Use Set#compare_by_identity to make a set compare
# its elements by their identity.
# * Set assumes that the identity of each element does not change
# while it is stored. Modifying an element of a set will render the
# set to an unreliable state.
# * When a string is to be stored, a frozen copy of the string is
# stored instead unless the original string is already frozen.
#
# ## Comparison
# The comparison operators `<`, `>`, `<=`, and `>=` are implemented as
# shorthand for the {proper_,}{subset?,superset?} methods. The `<=>`
# operator reflects this order, or return `nil` for sets that both
# have distinct elements (`{x, y}` vs. `{x, z}` for example).
# ## Example
# require 'set'
# 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.subset?(s2) #=> false
# s2.subset?(s1) #=> true
#
# ## Contact
# * Akinori MUSHA <mailto:knu@iDaemons.org> (current maintainer)
#
# ## What's Here
# First, what's elsewhere. Class Set:
# * Inherits from [class
# Object](https://docs.ruby-lang.org/en/master/Object.html#class-Object-labe
# l-What-27s+Here).
# * Includes [module
# which provides dozens of additional
# g/en/master/Enumerable.html#module-Enumerable-label-What-27s+Here),
# which provides dozens of additional methods.
#
# In particular, class Set does not have many methods of its own
# for fetching or for iterating.
# Instead, it relies on those in Enumerable.
# Here, class Set provides methods that are useful for:
# * [Creating a Set](#class-Set-label-Methods+for+Creating+a+Set)
# * [Set Operations](#class-Set-label-Methods+for+Set+Operations)
# * [Comparing](#class-Set-label-Methods+for+Comparing)
# * [Querying](#class-Set-label-Methods+for+Querying)
# * [Assigning](#class-Set-label-Methods+for+Assigning)
# * [Deleting](#class-Set-label-Methods+for+Deleting)
# * [Converting](#class-Set-label-Methods+for+Converting)
# * [Iterating](#class-Set-label-Methods+for+Iterating)
# * [And more....](#class-Set-label-Other+Methods)
#
# ### Methods for Creating a Set
# * ::[] -
# Returns a new set containing the given objects.
# * ::new -
# Returns a new set containing either the given objects
# (if no block given) or the return values from the called block
# (if a block given).
#
# ### Methods for Set Operations
# * [|](#method-i-7C) (aliased as #union and #+) -
# Returns a new set containing all elements from `self`
# and all elements from a given enumerable (no duplicates).
# * [&](#method-i-26) (aliased as #intersection) -
# Returns a new set containing all elements common to `self`
# and a given enumerable.
# * [-](#method-i-2D) (aliased as #difference) -
# Returns a copy of `self` with all elements
# in a given enumerable removed.
# * [\^](#method-i-5E) -
# Returns a new set containing all elements from `self`
# and a given enumerable except those common to both.
#
# ### Methods for Comparing
# * [<=>](#method-i-3C-3D-3E) -
# Returns -1, 0, or 1 as `self` is less than, equal to,
# or greater than a given object.
# * [==](#method-i-3D-3D) -
# Returns whether `self` and a given enumerable are equal,
# as determined by Object#eql?.
# * #compare_by_identity? -
# Returns whether the set considers only identity
# when comparing elements.
#
# ### Methods for Querying
# * #length (aliased as #size) -
# Returns the count of elements.
# * #empty? -
# Returns whether the set has no elements.
# * #include? (aliased as #member? and #===) -
# Returns whether a given object is an element in the set.
# * #subset? (aliased as [<=](#method-i-3C-3D)) -
# Returns whether a given object is a subset of the set.
# * #proper_subset? (aliased as [<](#method-i-3C)) -
# Returns whether a given enumerable is a proper subset of the set.
# * #superset? (aliased as [<=](#method-i-3E-3D)]) -
# Returns whether a given enumerable is a superset of the set.
# * #proper_superset? (aliased as [>](#method-i-3E)) -
# Returns whether a given enumerable is a proper superset of the set.
# * #disjoint? -
# Returns `true` if the set and a given enumerable
# have no common elements, `false` otherwise.
# * #intersect? -
# Returns `true` if the set and a given enumerable -
# have any common elements, `false` otherwise.
# * #compare_by_identity? -
# Returns whether the set considers only identity
# when comparing elements.
#
# ### Methods for Assigning
# * #add (aliased as #<<) -
# Adds a given object to the set; returns `self`.
# * #add? -
# If the given object is not an element in the set,
# adds it and returns `self`; otherwise, returns `nil`.
# * #merge -
# Adds each given object to the set; returns `self`.
# * #replace -
# Replaces the contents of the set with the contents
# of a given enumerable.
#
# ### Methods for Deleting
# * #clear -
# Removes all elements in the set; returns `self`.
# * #delete -
# Removes a given object from the set; returns `self`.
# * #delete? -
# If the given object is an element in the set,
# removes it and returns `self`; otherwise, returns `nil`.
# * #subtract -
# Removes each given object from the set; returns `self`.
# * #delete_if - Removes elements specified by a given block.
# * #select! (aliased as #filter!) -
# Removes elements not specified by a given block.
# * #keep_if -
# Removes elements not specified by a given block.
# * #reject!
# Removes elements specified by a given block.
#
# ### Methods for Converting
# * #classify -
# Returns a hash that classifies the elements,
# as determined by the given block.
# * #collect! (aliased as #map!) -
# Replaces each element with a block return-value.
# * #divide -
# Returns a hash that classifies the elements,
# as determined by the given block;
# differs from #classify in that the block may accept
# either one or two arguments.
# * #flatten -
# Returns a new set that is a recursive flattening of `self`.
# #flatten! -
# Replaces each nested set in `self` with the elements from that set.
# * #inspect (aliased as #to_s) -
# Returns a string displaying the elements.
# * #join -
# Returns a string containing all elements, converted to strings
# as needed, and joined by the given record separator.
# * #to_a -
# Returns an array containing all set elements.
# * #to_set -
# Returns `self` if given no arguments and no block;
# with a block given, returns a new set consisting of block
# return values.
#
# ### Methods for Iterating
# * #each -
# Calls the block with each successive element; returns `self`.
#
# ### Other Methods
# * #reset -
# Resets the internal state; useful if an object
# has been modified while an element in the set.
#
class Set[unchecked out A]
include Enumerable[A]
# <!--
# rdoc-file=lib/set.rb
# - new(enum = nil) { |o| ... }
# -->
# Creates a new set containing the elements of the given enumerable
# object.
# 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}>
#
def initialize: (_Each[A]) -> untyped
| [X] (_Each[X]) { (X) -> A } -> untyped
| (?nil) -> untyped
# <!--
# rdoc-file=lib/set.rb
# - [](*ary)
# -->
# Creates a new set containing the given objects.
# Set[1, 2] # => #<Set: {1, 2}>
# Set[1, 2, 1] # => #<Set: {1, 2}>
# Set[1, 'c', :s] # => #<Set: {1, "c", :s}>
#
def self.[]: [X] (*X) -> Set[X]
# <!--
# rdoc-file=lib/set.rb
# - &(enum)
# -->
# 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"}>
#
def &: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - intersection(enum)
# -->
#
alias intersection &
# <!--
# rdoc-file=lib/set.rb
# - |(enum)
# -->
# 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}>
#
def |: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - union(enum)
# -->
#
alias union |
# <!--
# rdoc-file=lib/set.rb
# - +(enum)
# -->
#
alias + |
# <!--
# rdoc-file=lib/set.rb
# - -(enum)
# -->
# 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"}>
#
def -: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - difference(enum)
# -->
#
alias difference -
# <!--
# rdoc-file=lib/set.rb
# - add(o)
# -->
# 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}>
#
def add: (A) -> self
# <!--
# rdoc-file=lib/set.rb
# - <<(o)
# -->
#
alias << add
# <!--
# rdoc-file=lib/set.rb
# - add?(o)
# -->
# 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?(2) #=> nil
#
def add?: (A) -> self?
# <!--
# rdoc-file=lib/set.rb
# - include?(o)
# -->
# Returns true if the set contains the given object.
# Note that `include?` and `member?` do not test member
# equality using `==` as do other Enumerables.
# See also Enumerable#include?
#
def include?: (A) -> bool
# <!--
# rdoc-file=lib/set.rb
# - member?(o)
# -->
#
alias member? include?
# <!--
# rdoc-file=lib/set.rb
# - ^(enum)
# -->
# Returns a new set containing elements exclusive between the set
# and the given 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"}>
#
def ^: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - classify() { |o| ... }
# -->
# Classifies the set by the return value of the given block and
# returns a hash of {value => set of elements} pairs. The block is
# called once for each element of the set, passing the element as
# parameter.
# require 'set'
# 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"}>}
#
# Returns an enumerator if no block is given.
#
def classify: [X] () { (A) -> X } -> Hash[X, self]
# <!--
# rdoc-file=lib/set.rb
# - clear()
# -->
# Removes all elements and returns self.
# set = Set[1, 'c', :s] #=> #<Set: {1, "c", :s}>
# set.clear #=> #<Set: {}>
# set #=> #<Set: {}>
#
def clear: () -> self
# <!--
# rdoc-file=lib/set.rb
# - collect!() { |o| ... }
# -->
# Replaces the elements with ones returned by `collect()`.
# Returns an enumerator if no block is given.
#
def collect!: () { (A) -> A } -> self
# <!--
# rdoc-file=lib/set.rb
# - map!()
# -->
#
alias map! collect!
# <!--
# rdoc-file=lib/set.rb
# - delete(o)
# -->
# Deletes the given object from the set and returns self. Use
# `subtract` to delete many items at once.
#
def delete: (A) -> self
# <!--
# rdoc-file=lib/set.rb
# - delete?(o)
# -->
# Deletes the given object from the set and returns self. If the
# object is not in the set, returns nil.
#
def delete?: (A) -> self?
# <!--
# rdoc-file=lib/set.rb
# - delete_if() { |o| ... }
# -->
# Deletes every element of the set for which block evaluates to
# true, and returns self. Returns an enumerator if no block is
# given.
#
def delete_if: () { (A) -> untyped } -> self
# <!--
# rdoc-file=lib/set.rb
# - reject!(&block)
# -->
# Equivalent to Set#delete_if, but returns nil if no changes were
# made. Returns an enumerator if no block is given.
#
def reject!: () { (A) -> untyped } -> self
# <!--
# rdoc-file=lib/set.rb
# - compare_by_identity()
# -->
# Makes the set compare its elements by their identity and returns
# self. This method may not be supported by all subclasses of Set.
#
def compare_by_identity: () -> self
# <!--
# rdoc-file=lib/set.rb
# - disjoint?(set)
# -->
# Returns true if the set and the given enumerable have
# no element in common. This method is the opposite of `intersect?`.
# Set[1, 2, 3].disjoint? Set[3, 4] #=> false
# Set[1, 2, 3].disjoint? Set[4, 5] #=> true
# Set[1, 2, 3].disjoint? [3, 4] #=> false
# Set[1, 2, 3].disjoint? 4..5 #=> true
#
def disjoint?: (self) -> bool
# <!--
# rdoc-file=lib/set.rb
# - divide(&func)
# -->
# Divides the set into a set of subsets according to the commonality
# defined by the given block.
# If the arity of the block is 2, elements o1 and o2 are in common
# if block.call(o1, o2) is true. Otherwise, elements o1 and o2 are
# in common if block.call(o1) == block.call(o2).
# require 'set'
# numbers = Set[1, 3, 4, 6, 9, 10, 11]
# set = numbers.divide { |i,j| (i - j).abs == 1 }
# set #=> #<Set: {#<Set: {1}>,
# # #<Set: {11, 9, 10}>,
# # #<Set: {3, 4}>,
# # #<Set: {6}>}>
#
# Returns an enumerator if no block is given.
#
def divide: () { (A, A) -> untyped } -> Set[self]
| () { (A) -> untyped } -> Set[self]
# <!--
# rdoc-file=lib/set.rb
# - each(&block)
# -->
# Calls the given block once for each element in the set, passing
# the element as parameter. Returns an enumerator if no block is
# given.
#
def each: () { (A) -> void } -> self
| () -> Enumerator[A, self]
# <!--
# rdoc-file=lib/set.rb
# - empty?()
# -->
# Returns true if the set contains no elements.
#
def empty?: () -> bool
# <!--
# rdoc-file=lib/set.rb
# - flatten()
# -->
# Returns a new set that is a copy of the set, flattening each
# containing set recursively.
#
def flatten: () -> Set[untyped]
# <!--
# rdoc-file=lib/set.rb
# - intersect?(set)
# -->
# Returns true if the set and the given enumerable have at least one
# element in common.
# Set[1, 2, 3].intersect? Set[4, 5] #=> false
# Set[1, 2, 3].intersect? Set[3, 4] #=> true
# Set[1, 2, 3].intersect? 4..5 #=> false
# Set[1, 2, 3].intersect? [3, 4] #=> true
#
def intersect?: (self) -> bool
# <!--
# rdoc-file=lib/set.rb
# - keep_if() { |o| ... }
# -->
# Deletes every element of the set for which block evaluates to
# false, and returns self. Returns an enumerator if no block is
# given.
#
def keep_if: () { (A) -> untyped } -> self
# <!--
# rdoc-file=lib/set.rb
# - size()
# -->
# Returns the number of elements.
#
def size: () -> Integer
# <!--
# rdoc-file=lib/set.rb
# - length()
# -->
#
alias length size
# <!--
# rdoc-file=lib/set.rb
# - merge(enum)
# -->
# Merges the elements of the given enumerable object to the set and
# returns self.
#
def merge: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - subset?(set)
# -->
# Returns true if the set is a subset of the given set.
#
def subset?: (self) -> bool
def proper_subst?: (self) -> bool
# <!--
# rdoc-file=lib/set.rb
# - superset?(set)
# -->
# Returns true if the set is a superset of the given set.
#
def superset?: (self) -> bool
# <!--
# rdoc-file=lib/set.rb
# - proper_superset?(set)
# -->
# Returns true if the set is a proper superset of the given set.
#
def proper_superset?: (self) -> bool
# <!--
# rdoc-file=lib/set.rb
# - replace(enum)
# -->
# 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}>
#
def replace: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - reset()
# -->
# Resets the internal state after modification to existing elements
# and returns self.
# Elements will be reindexed and deduplicated.
#
def reset: () -> self
# <!--
# rdoc-file=lib/set.rb
# - select!(&block)
# -->
# Equivalent to Set#keep_if, but returns nil if no changes were
# made. Returns an enumerator if no block is given.
#
def select!: () { (A) -> untyped } -> self?
# <!--
# rdoc-file=lib/set.rb
# - subtract(enum)
# -->
# Deletes every element that appears in the given enumerable object
# and returns self.
#
def subtract: (_Each[A]) -> self
# <!--
# rdoc-file=lib/set.rb
# - to_a()
# -->
# Converts the set to an array. The order of elements is uncertain.
# Set[1, 2].to_a #=> [1, 2]
# Set[1, 'c', :s].to_a #=> [1, "c", :s]
#
def to_a: () -> Array[A]
end
%a{annotate:rdoc:skip}
module Enumerable[unchecked out Elem]
# <!--
# rdoc-file=lib/set.rb
# - to_set(klass = Set, *args, &block)
# -->
# Makes a set from the enumerable object with given arguments.
# Needs to `require "set"` to use this method.
#
def to_set: () -> Set[Elem]
end