set.rb: improve docs for Set

* lib/set.rb: [DOC] add examples for Set#replace,
  add examples for creating a set from a hash with duplicates,
  simplify and fix style of some other examples, fix typos.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@60879 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
stomar 2017-11-22 20:58:24 +00:00
parent 9a2ea1039e
commit 62191f1cc5

View File

@ -47,15 +47,15 @@
#
# == Comparison
#
# The comparison operators <, >, <= and >= are implemented as
# 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)
# sets is comparable ({x, y} vs. {x, z} for example).
#
# == Example
#
# require 'set'
# s1 = Set.new([1, 2]) #=> #<Set: {1, 2}>
# s1 = Set[1, 2] #=> #<Set: {1, 2}>
# s2 = [1, 2].to_set #=> #<Set: {1, 2}>
# s1 == s2 #=> true
# s1.add("foo") #=> #<Set: {1, 2, "foo"}>
@ -73,6 +73,7 @@ class 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}>
def self.[](*ary)
new(ary)
@ -85,8 +86,9 @@ class Set
# given block.
#
# 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..10)) #=> #<Set: {1, 2, 3, 4, 5, 6, 7, 8, 9, 10}>
# 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)
@ -178,6 +180,10 @@ class 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}>
# set #=> #<Set: {1, 2}>
def replace(enum)
if enum.instance_of?(self.class)
@hash.replace(enum.instance_variable_get(:@hash))
@ -304,11 +310,8 @@ class Set
# 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
# Set[1, 2, 3].intersect? Set[4, 5] #=> false
# Set[1, 2, 3].intersect? Set[3, 4] #=> true
def intersect?(set)
set.is_a?(Set) or raise ArgumentError, "value must be a set"
if size < set.size
@ -321,12 +324,8 @@ class Set
# 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
# Set[1, 2, 3].disjoint? Set[3, 4] #=> false
# Set[1, 2, 3].disjoint? Set[4, 5] #=> true
def disjoint?(set)
!intersect?(set)
end
@ -344,7 +343,7 @@ class Set
# add many elements at once.
#
# Set[1, 2].add(3) #=> #<Set: {1, 2, 3}>
# Set[1, 2].add([3,4]) #=> #<Set: {1, 2, [3, 4]}>
# Set[1, 2].add([3, 4]) #=> #<Set: {1, 2, [3, 4]}>
# Set[1, 2].add(2) #=> #<Set: {1, 2}>
def add(o)
@hash[o] = true
@ -356,7 +355,7 @@ class Set
# object is already in the set, returns nil.
#
# Set[1, 2].add?(3) #=> #<Set: {1, 2, 3}>
# Set[1, 2].add?([3,4]) #=> #<Set: {1, 2, [3, 4]}>
# Set[1, 2].add?([3, 4]) #=> #<Set: {1, 2, [3, 4]}>
# Set[1, 2].add?(2) #=> nil
def add?(o)
add(o) unless include?(o)
@ -447,7 +446,7 @@ class Set
# Returns a new set built by merging the set and the elements of the
# given enumerable object.
#
# Set[1, 2, 3, 3] | Set[2, 4, 5] #=> #<Set: {1, 2, 3, 4, 5}>
# Set[1, 2, 3] | Set[2, 4, 5] #=> #<Set: {1, 2, 3, 4, 5}>
# Set[1, 5, 'z'] | (1..6) #=> #<Set: {1, 5, "z", 2, 3, 4, 6}>
def |(enum)
dup.merge(enum)
@ -481,7 +480,7 @@ class Set
# and the given enumerable object. (set ^ enum) is equivalent to
# ((set | enum) - (set & enum)).
#
# Set[1, 2] ^ Set[2,3] #=> #<Set: {3, 1}>
# Set[1, 2] ^ Set[2, 3] #=> #<Set: {3, 1}>
# Set[1, 'b', 'c'] ^ ['b', 'd'] #=> #<Set: {"d", 1, "c"}>
def ^(enum)
n = Set.new(enum)
@ -547,8 +546,8 @@ class Set
#
# Or by itself:
#
# Set[1, 2, 3] === 2 # => true
# Set[1, 2, 3] === 4 # => false
# Set[1, 2, 3] === 2 #=> true
# Set[1, 2, 3] === 4 #=> false
#
alias === include?
@ -557,14 +556,12 @@ class Set
# 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"}>}
# hash #=> {2000=>#<Set: {"a.rb", "b.rb"}>,
# # 2001=>#<Set: {"c.rb", "d.rb", "e.rb"}>,
# # 2002=>#<Set: {"f.rb"}>}
#
# Returns an enumerator if no block is given.
def classify # :yields: o
@ -586,15 +583,13 @@ class Set
# 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}>}>
# set #=> #<Set: {#<Set: {1}>,
# # #<Set: {11, 9, 10}>,
# # #<Set: {3, 4}>,
# # #<Set: {6}>}>
#
# Returns an enumerator if no block is given.
def divide(&func)
@ -630,7 +625,7 @@ class Set
InspectKey = :__inspect_key__ # :nodoc:
# Returns a string containing a human-readable representation of the
# set. ("#<Set: {element1, element2, ...}>")
# set ("#<Set: {element1, element2, ...}>").
def inspect
ids = (Thread.current[InspectKey] ||= [])