# frozen_string_literal: true
# set.rb - defines the Set class
# Copyright (c) 2002-2020 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
# 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
# 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.
# 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).
# s1 = Set[1, 2] #=> #<Set: {1, 2}>
# s2 = [1, 2].to_set #=> #<Set: {1, 2}>
# s1.add("foo") #=> #<Set: {1, 2, "foo"}>
# s1.merge([2, 6]) #=> #<Set: {1, 2, "foo", 6}>
# s1.subset?(s2) #=> false
# s2.subset?(s1) #=> true
# - Akinori MUSHA <<knu@iDaemons.org>> (current maintainer)
# 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 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.
# Returns a new set containing either the given objects
# (if no block given) or the return values from the called block
# ### 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.
# 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.
# 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.
# Returns +true+ if the set and a given enumerable
# have no common elements, +false+ otherwise.
# 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+.
# If the given object is not an element in the set,
# adds it and returns +self+; otherwise, returns +nil+.
# Adds each given object to the set; returns +self+.
# Replaces the contents of the set with the contents
# ### Methods for Deleting
# Removes all elements in the set; returns +self+.
# Removes a given object from the set; returns +self+.
# If the given object is an element in the set,
# removes it and returns +self+; otherwise, returns +nil+.
# 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.
# Removes elements not specified by a given block.
# Removes elements specified by a given block.
# ### Methods for Converting
# 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.
# 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.
# Returns a new set that is a recursive flattening of +self+.
# Replaces each nested set in +self+ with the elements from that set.
# - \#inspect (aliased as #to_s):
# Returns a string displaying the elements.
# Returns a string containing all elements, converted to strings
# as needed, and joined by the given record separator.
# Returns an array containing all set elements.
# Returns +self+ if given no arguments and no block;
# with a block given, returns a new set consisting of block
# ### Methods for Iterating
# Calls the block with each successive element; returns +self+.
# Resets the internal state; useful if an object
# has been modified while an element in the set.
# 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}>
# Creates a new set containing the elements of the given enumerable
# If a block is given, the elements of enum are preprocessed by the
# 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(enum = nil, &block) # :yields: o
@hash ||= Hash.new(false)
do_with_enum(enum) { |o| add(block[o]) }
# Makes the set compare its elements by their identity and returns
# self. This method may not be supported by all subclasses of Set.
if @hash.respond_to?(:compare_by_identity)
@hash.compare_by_identity
raise NotImplementedError, "#{self.class.name}\##{__method__} is not implemented"
# Returns true if the set will compare its elements by their
# identity. Also see Set#compare_by_identity.
@hash.respond_to?(:compare_by_identity?) && @hash.compare_by_identity?
def do_with_enum(enum, &block) # :nodoc:
if enum.respond_to?(:each_entry)
enum.each_entry(&block) if block
elsif enum.respond_to?(:each)
enum.each(&block) if block
raise ArgumentError, "value must be enumerable"
@hash = orig.instance_variable_get(:@hash).dup
if Kernel.instance_method(:initialize_clone).arity != 1
def initialize_clone(orig, **options)
@hash = orig.instance_variable_get(:@hash).clone(**options)
def initialize_clone(orig)
@hash = orig.instance_variable_get(:@hash).clone
# Returns the number of elements.
# Returns true if the set contains no elements.
# Removes all elements and returns self.
# set = Set[1, 'c', :s] #=> #<Set: {1, "c", :s}>
# set.clear #=> #<Set: {}>
# 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}>
if enum.instance_of?(self.class)
@hash.replace(enum.instance_variable_get(:@hash))
do_with_enum(enum) # make sure enum is enumerable before calling clear
# 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]
# Returns self if no arguments are given. Otherwise, converts the
# set to another with `klass.new(self, *args, &block)`.
# In subclasses, returns `klass.new(self, *args, &block)` unless
def to_set(klass = Set, *args, &block)
return self if instance_of?(Set) && klass == Set && block.nil? && args.empty?
klass.new(self, *args, &block)
def flatten_merge(set, seen = Set.new) # :nodoc:
if seen.include?(e_id = e.object_id)
raise ArgumentError, "tried to flatten recursive Set"
# Returns a new set that is a copy of the set, flattening each
# containing set recursively.
self.class.new.flatten_merge(self)
# Equivalent to Set#flatten, but replaces the receiver with the
# result in place. Returns nil if no modifications were made.
replace(flatten()) if any? { |e| e.is_a?(Set) }
# Returns true if the set contains the given object.
# Note that <code>include?</code> and <code>member?</code> do not test member
# equality using <code>==</code> as do other Enumerables.
# See also Enumerable#include?
# Returns true if the set is a superset of the given set.
when set.instance_of?(self.class) && @hash.respond_to?(:>=)
@hash >= set.instance_variable_get(:@hash)
size >= set.size && set.all? { |o| include?(o) }
raise ArgumentError, "value must be a set"
# Returns true if the set is a proper superset of the given set.
def proper_superset?(set)
when set.instance_of?(self.class) && @hash.respond_to?(:>)
@hash > set.instance_variable_get(:@hash)
size > set.size && set.all? { |o| include?(o) }
raise ArgumentError, "value must be a set"
# Returns true if the set is a subset of the given set.
when set.instance_of?(self.class) && @hash.respond_to?(:<=)
@hash <= set.instance_variable_get(:@hash)
size <= set.size && all? { |o| set.include?(o) }
raise ArgumentError, "value must be a set"
# Returns true if the set is a proper subset of the given set.
when set.instance_of?(self.class) && @hash.respond_to?(:<)
@hash < set.instance_variable_get(:@hash)
size < set.size && all? { |o| set.include?(o) }
raise ArgumentError, "value must be a set"
# Returns 0 if the set are equal,
# -1 / +1 if the set is a proper subset / superset of the given set,
# or nil if they both have unique elements.
return unless set.is_a?(Set)
when -1 then -1 if proper_subset?(set)
when +1 then +1 if proper_superset?(set)
# Returns true if the set and the given enumerable have at least one
# 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
any? { |o| set.include?(o) }
set.any? { |o| include?(o) }
set.any? { |o| include?(o) }
raise ArgumentError, "value must be enumerable"
# 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
It is recommended that you Edit text format, this type of Fix handles quite a lot in one request
