class Set

Returns a new set populated with the given objects:

Set[1, 'one', :one, 1.0, %w[a b c], {foo: 0, bar: 1}]
# => Set[1, "one", :one, 1.0, ["a", "b", "c"], {foo: 0, bar: 1}]
Set[Set[0, 1, 2], Set[%w[a b c]]]
# => Set[Set[0, 1, 2], Set[["a", "b", "c"]]]
Set[] # => Set[]

Related: see Methods for Creating a Set.

See as_json.

Returns a new set based on the given object, which must be an Enumerable or nil.

With argument object given as nil, returns a new empty set:

Set.new                          # => Set[]
Set.new { fail 'Cannot happen' } # => Set[]  # Block not called.

With no block given and enumerable argument object given, populates the new set with the elements of object:

Set.new(%w[ a b c ])      # => Set["a", "b", "c"]
Set.new({foo: 0, bar: 1}) # => Set[[:foo, 0], [:bar, 1]]
Set.new(4..10)            # => Set[4, 5, 6, 7, 8, 9, 10]
Set.new(Dir.new('lib')).take(5)
# => [".", "..", "bundled_gems.rb", "bundler", "bundler.rb"]
Set.new(File.new('doc/NEWS/NEWS-4.0.0.md')).take(3)
# => ["# NEWS for Ruby 4.0.0\n", "\n", "This document is a list of user-visible feature changes\n"]

With a block given and enumerable argument object given, calls the block with each element of object; adds the block’s return value to the new set:

Set.new(4..10) {|i| i * 2 } # => Set[8, 10, 12, 14, 16, 18, 20]

Related: see Methods for Creating a Set.

Returns a new set containing the intersection of self and enumerable; that is, containing all elements common to both, with no duplicates. Argument enumerable must be an Enumerable object:

set = Set[*(0..6), *%w[ a b c]] # => Set[0, 1, 2, 3, 4, 5, 6, "a", "b", "c"]
set & ['c', 6, 8, 4]            # => Set["c", 6, 4]
set & [:foo, :bar]              # => Set[]  # No elements in common.

Related: see Methods for Set Operations.

Returns a new set containing the difference of self and argument enumerable; that is, containing all elements in self that are not in enumerable.

set = Set[*(0..6), *%w[ a b c]] # => Set[0, 1, 2, 3, 4, 5, 6, "a", "b", "c"]
set - ['b', 6, 4, 1]            # => Set[0, 2, 3, 5, "a", "c"]
set - ['d', 7, 9]               # => Set[0, 1, 2, 3, 4, 5, 6, "a", "b", "c"]

Related: see Methods for Set Operations.

Compares self and object.

If object is another set, returns:

• -1, if self is a proper subset of object.

• 0, if self and object have the same elements.

• 1, if self is a proper superset of object.

• nil, if none of the above; that is, if self and object each have one or more elements not included in the other.

Examples:

set = Set[0, 1, 2]
set <=> Set[3, 2, 1, 0] # => -1
set <=> Set[2, 1, 0]    # => 0
set <=> Set[1, 0]       # => 1
set <=> Set[1, 0, 3]    # => nil

Returns nil if object is not a set:

set <=> [2, 1, 0] # => nil  # Array, not Set.

Related: see Methods for Comparing.

Returns whether object is a set, and has the same elements as self:

set = Set[0, 1, 2]
set == Set[1, 2, 0]   # => true
set == [1, 2, 3]      # => false
set == Set[1, 2, '3'] # => false

Related: see Methods for Comparing.

Returns a new set containing the exclusive OR of self and the given enumerable; that is, containing each element that is in either self or enumerable, but not in both:

set = Set[0, 1, 2]
set ^ Set[1, 2, 3]        # => Set[0, 3]
set ^ Set[2, 1]           # => Set[0]
set ^ Set[2, *('a'..'c')] # => Set[0, 1, "a", "b", "c"]
set ^ Set[2, 1, 0]        # => Set[]

For Set set and Enumerable enumerable, these expressions are equivalent:

set ^ enumerable
((set | enumerable) - (set & enumerable))

Related: see Methods for Set Operations.

Returns a new set containing the union of self and the given enumerable; that is, containing the elements of both self and enumerable.

set = Set[0, 1, 2]
set | Set[2, 1, 'a'] # => Set[0, 1, 2, "a"]
set | set            # => Set[0, 1, 2]

Related: see Methods for Set Operations.

Adds the given object to self; returns self:

set = Set[0, 1, 2]
set.add(%w[a b c]) # => Set[0, 1, 2, ["a", "b", "c"]]
set.add(0)         # => Set[0, 1, 2, ["a", "b", "c"]]

Related: see Methods for Assigning.

Like add, but returns nil if the given object is already in self:

set = Set[0, 1, 2]
set.add?(:foo)   # => Set[0, 1, 2, :foo]
set.add?(0..9) # => Set[0, 1, 2, :foo, 0..9]
set.add?(2) # => nil

Related: see Methods for Assigning.

Methods Set#as_json and Set.json_create may be used to serialize and deserialize a Set object; see Marshal.

Method Set#as_json serializes self, returning a 2-element hash representing self:

require 'json/add/set'
x = Set.new(%w/foo bar baz/).as_json
# => {"json_class"=>"Set", "a"=>["foo", "bar", "baz"]}

Method JSON.create deserializes such a hash, returning a Set object:

Set.json_create(x) # => #<Set: {"foo", "bar", "baz"}>

With a block given, calls the block with each element of self; returns a hash whose keys are the block’s return values. The value for each key is a set containing the elements for which the block returned that key.

This example classifies elements by their classes:

set = Set[*(5..7), *%w[foo bar]] # => Set[5, 6, 7, "foo", "bar"]
set.classify {|element| element.class }
# => {Integer => Set[5, 6, 7], String => Set["foo", "bar"]}

With no block given, returns an Enumerator.

Related: see Methods for Converting.

Returns self with all elements removed:

Set[1, :one, 'one', 1.0].clear # => Set[]

Related: see Methods for Deleting.

With a block given, calls the block with each element in self; replaces the element with the block’s return value:

Set[1, :one, 'one', 1.0].collect! {|element| element.class }
# => Set[Integer, Symbol, String, Float]

With no block given, returns an Enumerator.

Related: see Methods for Converting.

Sets self to compare by object identity (rather than by object content, which is the initial setting); returns self:

set = Set.new
set.compare_by_identity
str = +"foo"
set.add(str)
# =>  Set["foo"]
set.include?(str)
# => true
set.add(str)
# => Set["foo"])
set.include?(+"foo")
# => false
set.add(+"foo")
# => Set["foo", "foo"])

Once set, the compare-by-identity property may not be unset.

Related: compare_by_identity?.

Returns whether self compares elements by object identity (rather than by content):

set = Set[]
set.compare_by_identity? # => false
set.compare_by_identity
set.compare_by_identity? # => true

Related: compare_by_identity; see also Methods for Querying.

Removes the given object from self if self includes the object; returns self:

set = Set[0, 'zero', :zero]
set.delete(0)       # => Set["zero", :zero]
set.delete(:nosuch) # => Set["zero", :zero]

Related: see Methods for Deleting.

Like delete, but returns nil if the object is not in self:

set = Set[0, 'zero', :zero]
set.delete?(0) # => Set["zero", :zero]
set.delete?(0) # => nil

Related: see Methods for Deleting.

With a block given, calls the block with each element in self; removes the element if the block returns a truthy value:

set = Set[*0..9]
# => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.delete_if {|element| element.even? }
# => Set[1, 3, 5, 7, 9]

With no block given, returns an Enumerator.

Related: Methods for Deleting.

Returns whether no element of enumerable is present in self:

set = Set[0, 'zero', :zero]
set.disjoint?([1, 2, 3])    # => true
set.disjoint?([0, 1, 2, 3]) # => false

Related: see Methods for Querying.

With a block given, returns a set of sets.

For a block that accepts one argument, calls the block with each element; creates a set for each distinct block return value:

set = Set[*0..9]
# => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
# Divide into mod 3 sets.
set.divide {|ele| ele % 3 }
# => Set[Set[0, 3, 6, 9], Set[1, 4, 7], Set[2, 5, 8]]
# Divide into mod 5 sets.
set.divide {|ele| ele % 5 }
# => Set[Set[0, 5], Set[1, 6], Set[2, 7], Set[3, 8], Set[4, 9]]

Set[0].divide {|ele| anything } # => Set[Set[0]]
Set[].divide {|ele| not called } # => Set[]

For a block that accepts two arguments, divides self into connected components based on the binary relation defined by the block, calling the block with each 2-element permutation of the elements of self:

set = Set[*0..9]
# => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
# Divide into mod 2 sets.
set.divide {|i, j| (i - j) % 2 == 0 }
# => Set[Set[0, 2, 4, 6, 8], Set[1, 3, 5, 7, 9]]
# Divide into mod 3 sets.
set.divide {|i, j| (i - j) % 3 == 0 }
# => Set[Set[0, 3, 6, 9], Set[1, 4, 7], Set[2, 5, 8]]

Set[0].divide {|i, j| not called } # => Set[Set[0]]
Set[].divide {|i, j| not called } # => Set[]

With no block given, returns an Enumerator.

Related: see Methods for Converting.

With a block given, calls the block once for each element in the set, passing the element as a parameter; returns self:

sum = 0
Set[1, 2, 3].each {|i| sum += i }
sum # => 6

With no block given, returns an Enumerator.

Returns whether self contains no elements:

Set[].empty?  # => true
Set[0].empty? # => false

Related: see Methods for Querying.

Returns a new set that is a copy of self, but with self and its nested sets flattened; that is, their elements become elements of self:

Set[Set[0, 1], Set[2, 3]].flatten
# => Set[0, 1, 2, 3]
Set[Set[0, 1], Set[Set[2, 3], Set[3, 4]]].flatten
# => Set[0, 1, 2, 3, 4]

Does not flatten nested arrays or hashes:

Set[%w[foo bar]].flatten      # => Set[["foo", "bar"]]
Set[{foo: 0, bar: 1}].flatten # => Set[{foo: 0, bar: 1}]

Related: see Methods for Converting.

Like flatten, but if any changes were made replaces self with the result and returns self:

Set[Set[0, 1], Set[2, 3]].flatten!
# => Set[0, 1, 2, 3]
Set[Set[0, 1], Set[Set[2, 3], Set[3, 4]]].flatten!
# => Set[0, 1, 2, 3, 4]

Returns nil if no changes were made:

Set[0, 1, 2].flatten! # => nil

Related: see Methods for Assigning.

Returns the integer hash value for self.

Two sets with the same content have the same hash value.

Set[0, 1].hash == Set[1, 0].hash # => true
Set[0, 1].hash == Set[0].hash    # => false

Returns whether the given object is an element of self:

set = Set[0, :zero, '0']
set.include?('0')    # => true
set.include?('zero') # => false

Tests equality using hash and eql?.

Aliased as ===, which means that sets may be used in case expressions:

case :apple
when Set[:potato, :carrot]
  'vegetable'
when Set[:apple, :banana]
  'fruit'
else
  'unknown'
end
# => "fruit"

Related: see Methods for Querying.

Returns a string representation of self:

Set[*%w[foo bar], {foo: 0, bar: 1}].inspect
# => "Set[\"foo\", \"bar\", {foo: 0, bar: 1}]"

Related: see Methods for Converting.

Returns whether self and enumerable have any elements in common:

set = Set[0, 'zero', :zero]
set.intersect?([0, 1, 2])        # => true
set.intersect?(%w[zero one two]) # => true
set.intersect?(Set[3])           # => false

Related: see Methods for Querying.

Returns the string formed by joining the string-converted elements of self with the given separator (defaults to $,):

$, # => nil
Set[*%w[foo bar baz]].join
# => "foobarbaz"
Set[*%w[foo bar baz]].join(', ')
# => "foo, bar, baz"

Flattens nested arrays:

Set[[:foo, [:bar, [:baz, :bat]]]].join
# => "foobarbazbat"

Does not flatten nested sets:

Set[Set[:foo, Set[:bar, Set[:baz, :bat]]]].join
# => "Set[:foo, Set[:bar, Set[:baz, :bat]]]"

Related: see Methods for Converting.

With a block given, calls the block with each element in self, deleting the element if the block returns false or nil; returns self:

set = Set[*0..9]           # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.keep_if {|i| i.even? } # => Set[0, 2, 4, 6, 8]
set.keep_if {|i| i.odd? }  # => Set[]

With no block given, returns an Enumerator.

Related: see Methods for Deleting.

Adds each element of each of the given enumerables to self; returns self:

set = Set[*0..2]                 # => Set[0, 1, 2]
set.merge('a'..'c', %w[foo bar]) # => Set[0, 1, 2, "a", "b", "c", "foo", "bar"]
set.merge('a'..'c', %w[foo bar]) # => Set[0, 1, 2, "a", "b", "c", "foo", "bar"]

Related: see Methods for Assigning.

Returns whether self is a proper subset of the given other_set:

set = Set[*'b'..'e']
set.proper_subset?(set)            # => false
set.proper_subset?(Set[*'a'..'f']) # => true

Related: Methods for Querying.

Returns whether self is a proper superset of the given other_set:

set = Set[*'a'..'f']
set.proper_superset?(set)            # => false
set.proper_superset?(Set[*'b'..'e']) # => true

Related: Methods for Querying.

With a block given, like delete_if, but returns nil if no changes were made:

set = Set[*0..9]                       # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.reject! {|element| element.even? } # => Set[1, 3, 5, 7, 9]
set.reject! {|element| element.even? } # => nil
set.reject! {|element| element.odd? }  # => Set[]

With no block given, returns an Enumerator.

Related: see Methods for Deleting.

Replaces the contents self with the contents of the given enumerable; returns self:

set = Set[1, 'c', :s] # => Set[1, "c", :s]
set.replace([1, 2])   # => Set[1, 2]

Related: see Methods for Assigning.

Resets the internal state of self; returns self.

A set relies on the hash results of each element being consistent. Modifying an element in a way that changes the results of hash may allow duplicate elements in the set:

array = [1]
set = Set[array]  # => Set[[1]]
array << 2
set.add(array)    # => Set[[1, 2], [1, 2]]

Calling reset will recalculate all of the hash values and remove duplicate elements:

set.reset         # => Set[[1, 2]]

With a block given, like keep_if, but returns nil if no changes were made:

set = Set[*0..9]           # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.select! {|i| i.even? } # => Set[0, 2, 4, 6, 8]
set.select! {|i| i.even? } # => nil
set.select! {|i| i.odd? }  # => Set[]

With no block given, returns an Enumerator.

Related: see Methods for Deleting.

Returns the number of elements in self:

Set[*0..9].size # => 10

Related: see Methods for Querying.

Returns whether self is a subset of the given other_set:

set = Set[*'b'..'e']
set.subset?(set)            # => true
set.subset?(Set[*'a'..'f']) # => true
set.subset?(Set[*'c'..'e']) # => false

Related: Methods for Querying.

Deletes from self every element found in the given enumerable; returns self:

set = Set[*0..9]        # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.subtract(5..14)     # => Set[0, 1, 2, 3, 4]
set.subtract(Set[6, 2]) # => Set[0, 1, 3, 4]

Related: see Methods for Deleting.

Returns whether self is a superset of the given other_set:

set = Set[*'a'..'f']          # => Set["a", "b", "c", "d", "e", "f"]
set.superset?(set)            # => true
set.superset?(Set[*'b'..'e']) # => true
set.superset?(Set[*'b'..'x']) # => false

Related: Methods for Querying.

Returns an array containing the elements of self:

Set[1, 2].to_a       # => [1, 2]
Set[1, 'c', :s].to_a # => [1, "c", :s]

Related: Methods for Converting.

Returns a JSON string representing self:

require 'json/add/set'
puts Set.new(%w/foo bar baz/).to_json

Output:

{"json_class":"Set","a":["foo","bar","baz"]}

With a block given, creates and returns a new set; calls the block with each element of self, and adds the block’s returns value to the new set:

set = Set[*0..9]        # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
set.to_set {|i| i * 2 } # => Set[0, 2, 4, 6, 8, 10, 12, 14, 16, 18]

With no block given, when self is an instance of Set, returns self:

set = Set[*0..9]
set.to_set
set.to_set.equal?(set) # => true

With no block given, when self is an instance of a subclass of Set, returns a set containing the elements of self:

class MySet < Set; end
my_set = MySet[*0..9] # => #<MySet: {0, 1, 2, 3, 4, 5, 6, 7, 8, 9}>
set = my_set.to_set   # => Set[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

Related: see Methods for Converting.