summaryrefslogtreecommitdiff
path: root/lib/set.rb
diff options
context:
space:
mode:
authorstomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-11-22 20:58:24 +0000
committerstomar <stomar@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2017-11-22 20:58:24 +0000
commit62191f1cc5676c20f89d821944bab8b78d78cde1 (patch)
tree36db9708f2129c7fa5b931131a03ff70399f5e5d /lib/set.rb
parent9a2ea1039e73108f4a2b60db872405777eb03124 (diff)
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
Diffstat (limited to 'lib/set.rb')
-rw-r--r--lib/set.rb61
1 files changed, 28 insertions, 33 deletions
diff --git a/lib/set.rb b/lib/set.rb
index 78aff5c..566b1c0 100644
--- a/lib/set.rb
+++ b/lib/set.rb
@@ -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] ||= [])