Class: Set
Relationships & Source Files | |
Extension / Inclusion / Inheritance Descendants | |
Subclasses:
|
|
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
::Enumerable
|
|
Inherits: | Object |
Defined in: | lib/set.rb |
Overview
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. -
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. However, the <=> operator is intentionally left out because not every pair of sets is comparable. (x,y
vs. x,z
for example)
Example
require 'set'
s1 = Set.new [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 <knu@iDaemons.org> (current maintainer)
Class Method Summary
-
.[](*ary)
Creates a new set containing the given objects.
-
.new(enum = nil, &block) ⇒ Set
constructor
Creates a new set containing the elements of the given enumerable object.
Instance Attribute Summary
-
#empty? ⇒ Boolean
readonly
Returns true if the set contains no elements.
Instance Method Summary
-
#&(enum)
(also: #intersection)
Returns a new set containing elements common to the set and the given enumerable object.
-
#+(enum)
Alias for #|.
-
#-(enum)
(also: #difference)
Returns a new set built by duplicating the set, removing every element that appears in the given enumerable object.
-
#<(set)
Alias for #proper_subset?.
-
#<<(o)
Alias for #add.
-
#<=(set)
Alias for #subset?.
-
#==(other)
Returns true if two sets are equal.
-
#>(set)
Alias for #proper_superset?.
-
#>=(set)
Alias for #superset?.
-
#^(enum)
Returns a new set containing elements exclusive between the set and the given enumerable object.
-
#add(o)
(also: #<<)
Adds the given object to the set and returns self.
-
#add?(o) ⇒ Boolean
Adds the given object to the set and returns self.
-
#classify
Classifies the set by the return value of the given block and returns a hash of
=> set of elements
pairs. -
#clear
Removes all elements and returns self.
-
#collect!
(also: #map!)
Replaces the elements with ones returned by collect().
-
#delete(o)
Deletes the given object from the set and returns self.
-
#delete?(o) ⇒ Boolean
Deletes the given object from the set and returns self.
-
#delete_if
Deletes every element of the set for which block evaluates to true, and returns self.
-
#difference(enum)
Alias for #-.
-
#disjoint?(set) ⇒ Boolean
Returns true if the set and the given set have no element in common.
-
#divide(&func)
Divides the set into a set of subsets according to the commonality defined by the given block.
-
#each(&block)
Calls the given block once for each element in the set, passing the element as parameter.
-
#flatten
Returns a new set that is a copy of the set, flattening each containing set recursively.
-
#flatten!
Equivalent to #flatten, but replaces the receiver with the result in place.
-
#include?(o) ⇒ Boolean
(also: #member?)
Returns true if the set contains the given object.
-
#initialize_clone(orig)
Clone internal hash.
-
#initialize_dup(orig)
Dup internal hash.
-
#inspect
Returns a string containing a human-readable representation of the set.
-
#intersect?(set) ⇒ Boolean
Returns true if the set and the given set have at least one element in common.
-
#intersection(enum)
Alias for #&.
-
#keep_if
Deletes every element of the set for which block evaluates to false, and returns self.
-
#length
Alias for #size.
-
#map!
Alias for #collect!.
-
#member?(o)
Alias for #include?.
-
#merge(enum)
Merges the elements of the given enumerable object to the set and returns self.
-
#proper_subset?(set) ⇒ Boolean
(also: #<)
Returns true if the set is a proper subset of the given set.
-
#proper_superset?(set) ⇒ Boolean
(also: #>)
Returns true if the set is a proper superset of the given set.
-
#reject!(&block)
Equivalent to #delete_if, but returns nil if no changes were made.
-
#replace(enum)
Replaces the contents of the set with the contents of the given enumerable object and returns self.
-
#select!(&block)
Equivalent to #keep_if, but returns nil if no changes were made.
-
#size
(also: #length)
Returns the number of elements.
-
#subset?(set) ⇒ Boolean
(also: #<=)
Returns true if the set is a subset of the given set.
-
#subtract(enum)
Deletes every element that appears in the given enumerable object and returns self.
-
#superset?(set) ⇒ Boolean
(also: #>=)
Returns true if the set is a superset of the given set.
-
#to_a
Converts the set to an array.
-
#to_set(klass = Set, *args, &block)
Returns self if no arguments are given.
-
#union(enum)
Alias for #|.
-
#|(enum)
(also: #+, #union)
Returns a new set built by merging the set and the elements of the given enumerable object.
::Enumerable - Included
#to_set | Makes a set from the enumerable object with given arguments. |
Constructor Details
.new(enum = nil, &block) ⇒ Set
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.
# File 'lib/set.rb', line 82
def initialize(enum = nil, &block) # :yields: o @hash ||= Hash.new(false) enum.nil? and return if block do_with_enum(enum) { |o| add(block[o]) } else merge(enum) end end
Class Method Details
.[](*ary)
Creates a new set containing the given objects.
# File 'lib/set.rb', line 73
def self.[](*ary) new(ary) end
Instance Attribute Details
#empty? ⇒ Boolean
(readonly)
Returns true if the set contains no elements.
# File 'lib/set.rb', line 139
def empty? @hash.empty? end
Instance Method Details
#&(enum) Also known as: #intersection
Returns a new set containing elements common to the set and the given enumerable object.
# File 'lib/set.rb', line 418
def &(enum) n = self.class.new do_with_enum(enum) { |o| n.add(o) if include?(o) } n end
#+(enum)
Alias for #|.
# File 'lib/set.rb', line 406
alias + | ##
#-(enum) Also known as: #difference
Returns a new set built by duplicating the set, removing every element that appears in the given enumerable object.
# File 'lib/set.rb', line 411
def -(enum) dup.subtract(enum) end
#<(set)
Alias for #proper_subset?.
# File 'lib/set.rb', line 269
alias < proper_subset?
#<<(o)
Alias for #add.
# File 'lib/set.rb', line 316
alias << add
#<=(set)
Alias for #subset?.
# File 'lib/set.rb', line 256
alias <= subset?
#==(other)
Returns true if two sets are equal. The equality of each couple of elements is defined according to Object#eql?
.
#>(set)
Alias for #proper_superset?.
# File 'lib/set.rb', line 243
alias > proper_superset?
#>=(set)
Alias for #superset?.
# File 'lib/set.rb', line 230
alias >= superset?
#^(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)).
#add(o) Also known as: #<<
Adds the given object to the set and returns self. Use #merge to add many elements at once.
# File 'lib/set.rb', line 312
def add(o) @hash[o] = true self end
#add?(o) ⇒ Boolean
Adds the given object to the set and returns self. If the object is already in the set, returns nil.
#classify
Classifies the set by the return value of the given block and returns a hash of => set of elements
pairs. The block is called once for each element of the set, passing the element as parameter.
e.g.:
require 'set'
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"}>}
#clear
Removes all elements and returns self.
# File 'lib/set.rb', line 144
def clear @hash.clear self end
#collect! Also known as: #map!
Replaces the elements with ones returned by collect().
#delete(o)
Deletes the given object from the set and returns self. Use #subtract to delete many items at once.
# File 'lib/set.rb', line 326
def delete(o) @hash.delete(o) self end
#delete?(o) ⇒ Boolean
Deletes the given object from the set and returns self. If the object is not in the set, returns nil.
#delete_if
Deletes every element of the set for which block evaluates to true, and returns self.
#difference(enum)
Alias for #-.
# File 'lib/set.rb', line 414
alias difference - ##
#disjoint?(set) ⇒ Boolean
Returns true if the set and the given set have no element in common. This method is the opposite of #intersect?.
e.g.:
require 'set'
Set[1, 2, 3].disjoint? Set[3, 4] # => false
Set[1, 2, 3].disjoint? Set[4, 5] # => true
# File 'lib/set.rb', line 297
def disjoint?(set) !intersect?(set) end
#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).
e.g.:
require 'set'
numbers = Set[1, 3, 4, 6, 9, 10, 11]
set = numbers.divide { |i,j| (i - j).abs == 1 }
p set # => #<Set: {#<Set: {1}>,
# #<Set: {11, 9, 10}>,
# #<Set: {3, 4}>,
# #<Set: {6}>}>
# File 'lib/set.rb', line 498
def divide(&func) func or return enum_for(__method__) if func.arity == 2 require 'tsort' class << dig = {} # :nodoc: include TSort alias tsort_each_node each_key def tsort_each_child(node, &block) fetch(node).each(&block) end end each { |u| dig[u] = a = [] each{ |v| func.call(u, v) and a << v } } set = Set.new() dig.each_strongly_connected_component { |css| set.add(self.class.new(css)) } set else Set.new(classify(&func).values) end end
#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.
# File 'lib/set.rb', line 304
def each(&block) block or return enum_for(__method__) { size } @hash.each_key(&block) self end
#flatten
Returns a new set that is a copy of the set, flattening each containing set recursively.
# File 'lib/set.rb', line 198
def flatten self.class.new.flatten_merge(self) end
#flatten!
Equivalent to #flatten, but replaces the receiver with the result in place. Returns nil if no modifications were made.
#include?(o) ⇒ Boolean
Also known as: #member?
# File 'lib/set.rb', line 214
def include?(o) @hash[o] end
#initialize_clone(orig)
Clone internal hash.
# File 'lib/set.rb', line 112
def initialize_clone(orig) super @hash = orig.instance_variable_get(:@hash).clone end
#initialize_dup(orig)
Dup internal hash.
# File 'lib/set.rb', line 106
def initialize_dup(orig) super @hash = orig.instance_variable_get(:@hash).dup end
#inspect
Returns a string containing a human-readable representation of the set. (“#<Set: element2, …
>”)
# File 'lib/set.rb', line 532
def inspect ids = (Thread.current[InspectKey] ||= []) if ids.include?(object_id) return sprintf('#<%s: {...}>', self.class.name) end ids << object_id begin return sprintf('#<%s: {%s}>', self.class, to_a.inspect[1..-2]) ensure ids.pop end end
#intersect?(set) ⇒ Boolean
Returns true if the set and the given set have at least one element in common.
e.g.:
require 'set'
Set[1, 2, 3].intersect? Set[4, 5] # => false
Set[1, 2, 3].intersect? Set[3, 4] # => true
#intersection(enum)
Alias for #&.
# File 'lib/set.rb', line 423
alias intersection & ##
#keep_if
Deletes every element of the set for which block evaluates to false, and returns self.
#length
Alias for #size.
# File 'lib/set.rb', line 136
alias length size
#map!
Alias for #collect!.
# File 'lib/set.rb', line 362
alias map! collect!
#member?(o)
Alias for #include?.
# File 'lib/set.rb', line 217
alias member? include?
#merge(enum)
Merges the elements of the given enumerable object to the set and returns self.
# File 'lib/set.rb', line 384
def merge(enum) if enum.instance_of?(self.class) @hash.update(enum.instance_variable_get(:@hash)) else do_with_enum(enum) { |o| add(o) } end self end
#proper_subset?(set) ⇒ Boolean
Also known as: #<
Returns true if the set is a proper subset of the given set.
#proper_superset?(set) ⇒ Boolean
Also known as: #>
Returns true if the set is a proper superset of the given set.
#reject!(&block)
Equivalent to #delete_if, but returns nil if no changes were made.
#replace(enum)
Replaces the contents of the set with the contents of the given enumerable object and returns self.
# File 'lib/set.rb', line 151
def replace(enum) if enum.instance_of?(self.class) @hash.replace(enum.instance_variable_get(:@hash)) self else do_with_enum(enum) # make sure enum is enumerable before calling clear clear merge(enum) end end
#select!(&block)
Equivalent to #keep_if, but returns nil if no changes were made.
#size Also known as: #length
Returns the number of elements.
# File 'lib/set.rb', line 133
def size @hash.size end
#subset?(set) ⇒ Boolean
Also known as: #<=
Returns true if the set is a subset of the given set.
#subtract(enum)
Deletes every element that appears in the given enumerable object and returns self.
# File 'lib/set.rb', line 396
def subtract(enum) do_with_enum(enum) { |o| delete(o) } self end
#superset?(set) ⇒ Boolean
Also known as: #>=
Returns true if the set is a superset of the given set.
#to_a
Converts the set to an array. The order of elements is uncertain.
# File 'lib/set.rb', line 163
def to_a @hash.keys end
#to_set(klass = Set, *args, &block)
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 overridden.
#union(enum)
Alias for #|.
# File 'lib/set.rb', line 407
alias union | ##
#|(enum) Also known as: #+, #union
Returns a new set built by merging the set and the elements of the given enumerable object.
# File 'lib/set.rb', line 403
def |(enum) dup.merge(enum) end