# set.rb - defines the Set class
# Copyright (c) 2002-2013 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
# $Id: set.rb 47085 2014-08-06 11:28:21Z knu $
# 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. If you
# need to keep values sorted in some order, use the SortedSet class.
# The method +to_set+ is added to Enumerable for convenience.
# See the Set and SortedSet documentation for examples of usage.
# 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
# * 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. However,
# the <=> operator is intentionally left out because not every pair of
# sets is comparable. ({x,y} vs. {x,z} for example)
# s1 = Set.new [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)
# Creates a new set containing the given objects.
# Creates a new set containing the elements of the given enumerable
# If a block is given, the elements of enum are preprocessed by the
def initialize(enum = nil, &block) # :yields: o
do_with_enum(enum) { |o| add(block[o]) }
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
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.
# Replaces the contents of the set with the contents of the given
# enumerable object and returns self.
if enum.instance_of?(self.class)
@hash.replace(enum.instance_variable_get(:@hash))
# Converts the set to an array. The order of elements is uncertain.
# 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.
if detect { |e| e.is_a?(Set) }
# Returns true if the set contains the given object.
# Returns true if the set is a superset of the given set.
set.is_a?(Set) or raise ArgumentError, "value must be a set"
return false if size < set.size
set.all? { |o| include?(o) }
# Returns true if the set is a proper superset of the given set.
def proper_superset?(set)
set.is_a?(Set) or raise ArgumentError, "value must be a set"
return false if size <= set.size
set.all? { |o| include?(o) }
# Returns true if the set is a subset of the given set.
set.is_a?(Set) or raise ArgumentError, "value must be a set"
return false if set.size < size
all? { |o| set.include?(o) }
# Returns true if the set is a proper subset of the given set.
set.is_a?(Set) or raise ArgumentError, "value must be a set"
return false if set.size <= size
all? { |o| set.include?(o) }
# Returns true if the set and the given set have at least one
# Set[1, 2, 3].intersect? Set[4, 5] # => false
# Set[1, 2, 3].intersect? Set[3, 4] # => true
set.is_a?(Set) or raise ArgumentError, "value must be a set"
any? { |o| set.include?(o) }
set.any? { |o| include?(o) }
# Returns true if the set and the given set 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
# Calls the given block once for each element in the set, passing
# the element as parameter. Returns an enumerator if no block is
block or return enum_for(__method__)
# Adds the given object to the set and returns self. Use +merge+ to
# add many elements at once.
# Adds the given object to the set and returns self. If the
# object is already in the set, returns nil.
# Deletes the given object from the set and returns self. Use +subtract+ to
# delete many items at once.
# Deletes the given object from the set and returns self. If the
# object is not in the set, returns nil.
# Deletes every element of the set for which block evaluates to
# true, and returns self.
block_given? or return enum_for(__method__)
# @hash.delete_if should be faster, but using it breaks the order
# of enumeration in subclasses.
select { |o| yield o }.each { |o| @hash.delete(o) }
# Deletes every element of the set for which block evaluates to
# false, and returns self.
block_given? or return enum_for(__method__)
# @hash.keep_if should be faster, but using it breaks the order of
# enumeration in subclasses.
reject { |o| yield o }.each { |o| @hash.delete(o) }
# Replaces the elements with ones returned by collect().
block_given? or return enum_for(__method__)
each { |o| set << yield(o) }
# Equivalent to Set#delete_if, but returns nil if no changes were
block or return enum_for(__method__)
# Equivalent to Set#keep_if, but returns nil if no changes were
block or return enum_for(__method__)
# Merges the elements of the given enumerable object to the set and
if enum.instance_of?(self.class)
@hash.update(enum.instance_variable_get(:@hash))
do_with_enum(enum) { |o| add(o) }
# Deletes every element that appears in the given enumerable object
do_with_enum(enum) { |o| delete(o) }
# Returns a new set built by merging the set and the elements of the
# given enumerable object.
# Returns a new set built by duplicating the set, removing every
# element that appears in the given enumerable object.
# Returns a new set containing elements common to the set and the
# given enumerable object.
do_with_enum(enum) { |o| n.add(o) if include?(o) }
# Returns a new set containing elements exclusive between the set
# and the given enumerable object. (set ^ enum) is equivalent to
# ((set | enum) - (set & enum)).
each { |o| if n.include?(o) then n.delete(o) else n.add(o) end }
# Returns true if two sets are equal. The equality of each couple
# of elements is defined according to Object#eql?.
elsif other.instance_of?(self.class)
@hash == other.instance_variable_get(:@hash)
elsif other.is_a?(Set) && self.size == other.size
other.all? { |o| @hash.include?(o) }
return false unless o.is_a?(Set)
@hash.eql?(o.instance_variable_get(:@hash))
# 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
# files = Set.new(Dir.glob("*.rb"))
# hash = files.classify { |f| File.mtime(f).year }
# p hash # => {2000=>#<Set: {"a.rb", "b.rb"}>,
# # 2001=>#<Set: {"c.rb", "d.rb", "e.rb"}>,
# # 2002=>#<Set: {"f.rb"}>}
def classify # :yields: o
block_given? or return enum_for(__method__)
(h[x] ||= self.class.new).add(i)
# 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).
# numbers = Set[1, 3, 4, 6, 9, 10, 11]
# set = numbers.divide { |i,j| (i - j).abs == 1 }
# p set # => #<Set: {#<Set: {1}>,
func or return enum_for(__method__)
class << dig = {} # :nodoc:
alias tsort_each_node each_key
def tsort_each_child(node, &block)
