Set

set/subclass_compatible.rb - Provides compatibility for set subclasses

Copyright © 2002-2024 Akinori MUSHA [email protected]

Documentation by Akinori MUSHA and Gavin Sinclair.

All rights reserved. You can redistribute and/or modify it under the same terms as Ruby.

An instance of class Set contains a collection of objects (elements), with no duplicates.

By default:

• Set determines equality via Object#eql? and Object#hash, and assumes that these values do not change for a stored element. If these values do change, the set enters an unreliable state; see reset.

• A String instance added to a set is stored as a frozen copy of the string, unless it is already frozen.

Calling compare_by_identity causes:

• All following determinations of equality to use object identity instead of the methods mentioned above.

• A String added to a set is stored “as is”, whether or not frozen.

Set includes module Enumerable, and is easy to use with other enumerable objects. Many of its methods accept enumerable objects as arguments; any enumerable object may be converted to a set via to_set.

Contact

• Akinori MUSHA <[email protected]> (current maintainer)

Inheriting from Set

Before Ruby 4.0 (released in December, 2025), class Set had a different, less efficient implementation. In Ruby 4.0, the class was reimplemented in C, and the behaviors of some methods were adjusted.

When compatibility with the older implementation is needed, a Set subclass should inherit directly from class Set; this automatically includes module Set::SubclassCompatible, which makes behaviors closer to those in the older implementation.

A difference may be seen as follows:

Set[[1, 2, 3]]       # => Set[[1, 2, 3]]
class MySet < Set; end
MySet[[1, 2, 3]]     # => #<MySet: {[1, 2, 3]}>  # Same as in Ruby 3.4.

When backward compatibility is not needed, a Set subclass should inherit from Set::CoreSet, which avoids including the compatibility layer:

class MyCoreSet < Set::CoreSet; end
MyCoreSet[[1, 2, 3]] # => MyCoreSet[[1, 2, 3]]

What’s Here

First, what’s elsewhere. Class Set:

• Inherits from class Object.

• Includes module Enumerable, 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

• Set Operations

• Comparing

• Querying

• Assigning

• Deleting

• Converting

• And more.…

Methods for Creating a Set

• ::[]: Returns a new set populated with the given objects.

• ::new: Returns a new set based on the given object (if no block given), or on the return values from the called block (if a block given).

Methods for Set Operations

• & (aliased as intersection): Returns a new set containing the intersection of self and the given enumerable.

• - (aliased as difference): Returns a new set containing the difference of self and the given enumerable.

• ^: Returns a new set containing the exclusive OR of self and the given enumerable.

• | (aliased as union and +): Returns a new set containing the union of self and the given enumerable.

Methods for Comparing

• <=>: Returns -1, 0, or 1 as self is less than, equal to, or greater than a given object.

• ==: Returns whether self and a given enumerable are equal, as determined by Object#eql?.

• compare_by_identity?: Returns whether self considers only identity when comparing elements.

• proper_subset? (aliased as <): Returns whether the given enumerable is a proper subset of self.

• proper_superset? (aliased as >): Returns whether the given enumerable is a proper superset of self.

• subset? (aliased as <=): Returns whether the given object is a subset of self.

• superset? (aliased as >=): Returns whether the given enumerable is a superset of self.

Methods for Querying

• disjoint?: Returns whether no element of the given enumerable is present in self.

• empty?: Returns whether self contains no elements.

• include? (aliased as member? and ===): Returns whether the given object is an element of self.

• intersect?: Returns whether self and the given enumerable have any elements in common.

• size (aliased as length): Returns the number of elements in self.

Methods for Assigning

• add (aliased as <<): Adds the given object to self; returns self.

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

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

• replace: Replaces the contents of self with the contents of the given enumerable; returns self.

Methods for Deleting

• clear: Removes all elements from self; returns self.

• delete: Removes the given object from self if self includes the object; returns self.

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

• delete_if: Calls the block with each element in self; removes the element if the block returns a truthy value.

• keep_if: Calls the block with each element in self, deleting the element if the block returns false or nil; returns self.

• reject! Like delete_if, but returns nil if no changes were made.

• select! (aliased as filter!): Like keep_if, but returns nil if no changes were made.

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

Methods for Converting

• classify: Returns a hash that partitions the elements, as determined by the given block.

• collect! (aliased as map!): Replaces each element with a block return-value.

• divide: Returns a set of sets that partition the elements, as determined by the given block.

• flatten: Returns a new set that is a recursive flattening of self.

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

• inspect (aliased as to_s): Returns a string representation of self.

• join: Returns the string formed by joining the string-converted elements of self with the given separator.

• to_a: Returns an array containing the elements of self.

• to_set: 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.

Other Methods

• compare_by_identity: Sets self to compare by object identity (rather than by object content).

• each: Calls the block with each successive element of self; returns self.

• reset: Resets the internal state of self; returns self. Useful if an element has been modified while an element in the set.