mirror of
https://github.com/mruby/mruby
synced 2026-06-08 16:11:16 +00:00
mruby-set: add comprehensive call-seq documentation for all Ruby methods
Added complete call-seq documentation for all 17 Ruby methods in mrblib/set.rb: - initialize: Added examples showing set creation with and without blocks - merge: Added examples showing element merging and self-modification - replace: Added examples showing complete set replacement - subtract: Added examples showing element removal from enumerable - intersection (&): Added examples showing common elements between sets - union (|, +): Added examples showing set combination operations - difference (-): Added examples showing set subtraction operations - ^ (exclusive or): Added examples showing symmetric difference - each: Added examples showing iteration with blocks and enumerators - delete_if: Added examples showing conditional element deletion - keep_if: Added examples showing conditional element retention - collect!/map!: Added examples showing in-place element transformation - reject!: Added examples showing conditional deletion with nil return - select!/filter!: Added examples showing conditional retention with nil return - classify: Added examples showing element classification into hash - divide: Added examples showing set division into subsets Co-authored-by: Atlassian Rovo Dev
This commit is contained in:
Yukihiro "Matz" Matsumoto
+164
-49
@@ -1,4 +1,16 @@
|
||||
class Set
|
||||
#
|
||||
# call-seq:
|
||||
# Set.new(enum = nil) -> set
|
||||
# Set.new(enum = nil) { |obj| block } -> set
|
||||
#
|
||||
# Creates a new set containing the elements of the given enumerable object.
|
||||
# If a block is given, the elements are preprocessed by the given block.
|
||||
#
|
||||
# Set.new([1, 2, 3]) #=> #<Set: {1, 2, 3}>
|
||||
# Set.new([1, 2, 2, 3]) #=> #<Set: {1, 2, 3}>
|
||||
# Set.new([1, 2, 3]) { |x| x * 2 } #=> #<Set: {2, 4, 6}>
|
||||
#
|
||||
def initialize(enum = nil, &block)
|
||||
__init
|
||||
return self if enum.nil?
|
||||
@@ -20,41 +32,64 @@ class Set
|
||||
end
|
||||
end
|
||||
|
||||
# Merges the elements of the given enumerable object to the set and returns
|
||||
# self.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to merge elements from
|
||||
# @return [Set] self
|
||||
# call-seq:
|
||||
# set.merge(enum) -> self
|
||||
#
|
||||
# Merges the elements of the given enumerable object to the set and returns self.
|
||||
#
|
||||
# set = Set.new([1, 2])
|
||||
# set.merge([2, 3, 4]) #=> #<Set: {1, 2, 3, 4}>
|
||||
# set #=> #<Set: {1, 2, 3, 4}>
|
||||
#
|
||||
def merge(enum)
|
||||
__merge(enum) || __do_with_enum(enum) { |o| add(o) }
|
||||
self
|
||||
end
|
||||
|
||||
#
|
||||
# call-seq:
|
||||
# set.replace(enum) -> self
|
||||
#
|
||||
# Replaces the contents of the set with the contents of the given enumerable
|
||||
# object and returns self.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to replace with
|
||||
# @return [Set] self
|
||||
# set = Set.new([1, 2, 3])
|
||||
# set.replace([4, 5, 6]) #=> #<Set: {4, 5, 6}>
|
||||
# set #=> #<Set: {4, 5, 6}>
|
||||
#
|
||||
def replace(enum)
|
||||
clear
|
||||
merge(enum)
|
||||
end
|
||||
|
||||
#
|
||||
# call-seq:
|
||||
# set.subtract(enum) -> self
|
||||
#
|
||||
# Deletes every element that appears in the given enumerable object and
|
||||
# returns self.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object containing elements to remove
|
||||
# @return [Set] self
|
||||
# set = Set.new([1, 2, 3, 4])
|
||||
# set.subtract([2, 4]) #=> #<Set: {1, 3}>
|
||||
# set #=> #<Set: {1, 3}>
|
||||
#
|
||||
def subtract(enum)
|
||||
__subtract(enum) || __do_with_enum(enum) { |o| delete(o) }
|
||||
self
|
||||
end
|
||||
|
||||
#
|
||||
# call-seq:
|
||||
# set.intersection(enum) -> new_set
|
||||
# set & enum -> new_set
|
||||
#
|
||||
# Returns a new set containing elements common to the set and the given
|
||||
# enumerable object.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to find common elements with
|
||||
# @return [Set] A new set containing elements common to both
|
||||
# Set.new([1, 2, 3]).intersection([2, 3, 4]) #=> #<Set: {2, 3}>
|
||||
# Set.new([1, 2, 3]) & [2, 3, 4] #=> #<Set: {2, 3}>
|
||||
#
|
||||
def intersection(enum)
|
||||
__intersection(enum) || begin
|
||||
n = Set.new
|
||||
@@ -66,11 +101,19 @@ class Set
|
||||
# Alias for #intersection
|
||||
alias & intersection
|
||||
|
||||
#
|
||||
# call-seq:
|
||||
# set.union(enum) -> new_set
|
||||
# set | enum -> new_set
|
||||
# set + enum -> new_set
|
||||
#
|
||||
# Returns a new set built by merging the set and the elements of the given
|
||||
# enumerable object.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to merge with
|
||||
# @return [Set] A new set containing all elements from both
|
||||
# Set.new([1, 2]).union([2, 3, 4]) #=> #<Set: {1, 2, 3, 4}>
|
||||
# Set.new([1, 2]) | [2, 3, 4] #=> #<Set: {1, 2, 3, 4}>
|
||||
# Set.new([1, 2]) + [2, 3, 4] #=> #<Set: {1, 2, 3, 4}>
|
||||
#
|
||||
def union(enum)
|
||||
__union(enum) || dup.merge(enum)
|
||||
end
|
||||
@@ -79,11 +122,17 @@ class Set
|
||||
alias | union
|
||||
alias + union
|
||||
|
||||
#
|
||||
# call-seq:
|
||||
# set.difference(enum) -> new_set
|
||||
# set - enum -> new_set
|
||||
#
|
||||
# Returns a new set built by duplicating the set, removing every element that
|
||||
# appears in the given enumerable object.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to find elements to remove
|
||||
# @return [Set] A new set with elements from self that are not in enum
|
||||
# Set.new([1, 2, 3, 4]).difference([2, 4]) #=> #<Set: {1, 3}>
|
||||
# Set.new([1, 2, 3, 4]) - [2, 4] #=> #<Set: {1, 3}>
|
||||
#
|
||||
def difference(enum)
|
||||
__difference(enum) || begin
|
||||
result = dup
|
||||
@@ -95,11 +144,16 @@ class Set
|
||||
# Alias for #difference
|
||||
alias - difference
|
||||
|
||||
# Returns a new set containing elements exclusive between the set and the given
|
||||
# enumerable object.
|
||||
#
|
||||
# @param [Enumerable] enum The enumerable object to find exclusive elements with
|
||||
# @return [Set] A new set containing elements exclusive between both
|
||||
# call-seq:
|
||||
# set ^ enum -> new_set
|
||||
#
|
||||
# Returns a new set containing elements exclusive between the set and the given
|
||||
# enumerable object. (set ^ enum) is equivalent to ((set | enum) - (set & enum)).
|
||||
#
|
||||
# Set.new([1, 2, 3]) ^ [2, 3, 4] #=> #<Set: {1, 4}>
|
||||
# Set.new([1, 2]) ^ [2, 3] #=> #<Set: {1, 3}>
|
||||
#
|
||||
def ^(enum)
|
||||
__xor(enum) || begin
|
||||
s2 = Set.new(enum)
|
||||
@@ -107,10 +161,18 @@ class Set
|
||||
end
|
||||
end
|
||||
|
||||
# Iterates over each element in the set.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @return [Set] self
|
||||
# call-seq:
|
||||
# set.each { |obj| block } -> set
|
||||
# set.each -> enumerator
|
||||
#
|
||||
# Calls the given block once for each element in the set, passing the element
|
||||
# as parameter. Returns an enumerator if no block is given.
|
||||
#
|
||||
# Set.new([1, 2, 3]).each { |x| puts x }
|
||||
# # prints: 1, 2, 3
|
||||
# #=> #<Set: {1, 2, 3}>
|
||||
#
|
||||
def each(&block)
|
||||
return to_enum :each unless block_given?
|
||||
# Use C implementation's to_a method and iterate
|
||||
@@ -118,33 +180,56 @@ class Set
|
||||
self
|
||||
end
|
||||
|
||||
# Deletes every element for which the given block returns true.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Boolean] true if the element should be deleted
|
||||
# @return [Set] self
|
||||
# call-seq:
|
||||
# set.delete_if { |obj| block } -> set
|
||||
# set.delete_if -> enumerator
|
||||
#
|
||||
# Deletes every element of the set for which block evaluates to true, and
|
||||
# returns self. Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5])
|
||||
# set.delete_if { |x| x.even? } #=> #<Set: {1, 3, 5}>
|
||||
# set #=> #<Set: {1, 3, 5}>
|
||||
#
|
||||
def delete_if
|
||||
return to_enum :delete_if unless block_given?
|
||||
select { yield _1 }.each { delete(_1) }
|
||||
self
|
||||
end
|
||||
|
||||
# Deletes every element for which the given block returns false.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Boolean] true if the element should be kept
|
||||
# @return [Set] self
|
||||
# call-seq:
|
||||
# set.keep_if { |obj| block } -> set
|
||||
# set.keep_if -> enumerator
|
||||
#
|
||||
# Deletes every element of the set for which block evaluates to false, and
|
||||
# returns self. Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5])
|
||||
# set.keep_if { |x| x.even? } #=> #<Set: {2, 4}>
|
||||
# set #=> #<Set: {2, 4}>
|
||||
#
|
||||
def keep_if
|
||||
return to_enum :keep_if unless block_given?
|
||||
reject { yield _1 }.each { delete(_1) }
|
||||
self
|
||||
end
|
||||
|
||||
# Replaces each element with the result of the given block.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Object] The new value for the element
|
||||
# @return [Set] self
|
||||
# call-seq:
|
||||
# set.collect! { |obj| block } -> set
|
||||
# set.map! { |obj| block } -> set
|
||||
# set.collect! -> enumerator
|
||||
# set.map! -> enumerator
|
||||
#
|
||||
# Replaces the elements with ones returned by collect().
|
||||
# Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3])
|
||||
# set.collect! { |x| x * 2 } #=> #<Set: {2, 4, 6}>
|
||||
# set #=> #<Set: {2, 4, 6}>
|
||||
#
|
||||
def collect!
|
||||
return to_enum :collect! unless block_given?
|
||||
set = self.class.new
|
||||
@@ -153,11 +238,18 @@ class Set
|
||||
end
|
||||
alias map! collect!
|
||||
|
||||
# Deletes every element for which the given block returns true.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Boolean] true if the element should be deleted
|
||||
# @return [Set] self if any elements were deleted, nil otherwise
|
||||
# call-seq:
|
||||
# set.reject! { |obj| block } -> set or nil
|
||||
# set.reject! -> enumerator
|
||||
#
|
||||
# Equivalent to Set#delete_if, but returns nil if no changes were made.
|
||||
# Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5])
|
||||
# set.reject! { |x| x.even? } #=> #<Set: {1, 3, 5}>
|
||||
# set.reject! { |x| x > 10 } #=> nil
|
||||
#
|
||||
def reject!(&block)
|
||||
return to_enum :reject! unless block_given?
|
||||
n = size
|
||||
@@ -165,11 +257,20 @@ class Set
|
||||
size == n ? nil : self
|
||||
end
|
||||
|
||||
# Deletes every element for which the given block returns false.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Boolean] true if the element should be kept
|
||||
# @return [Set] self if any elements were deleted, nil otherwise
|
||||
# call-seq:
|
||||
# set.select! { |obj| block } -> set or nil
|
||||
# set.filter! { |obj| block } -> set or nil
|
||||
# set.select! -> enumerator
|
||||
# set.filter! -> enumerator
|
||||
#
|
||||
# Equivalent to Set#keep_if, but returns nil if no changes were made.
|
||||
# Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5])
|
||||
# set.select! { |x| x.even? } #=> #<Set: {2, 4}>
|
||||
# set.select! { |x| x.even? } #=> nil
|
||||
#
|
||||
def select!(&block)
|
||||
return to_enum :select! unless block_given?
|
||||
n = size
|
||||
@@ -178,11 +279,18 @@ class Set
|
||||
end
|
||||
alias filter! select!
|
||||
|
||||
# Classifies the elements of the set by the result of the given block.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Object] The classification key
|
||||
# @return [Hash] A hash mapping classification keys to sets of elements
|
||||
# call-seq:
|
||||
# set.classify { |obj| block } -> hash
|
||||
# set.classify -> enumerator
|
||||
#
|
||||
# Classifies the set by the return value of the given block and returns a
|
||||
# hash of {value => set of elements} pairs. Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5, 6])
|
||||
# set.classify { |x| x % 3 }
|
||||
# #=> {1=>#<Set: {1, 4}>, 2=>#<Set: {2, 5}>, 0=>#<Set: {3, 6}>}
|
||||
#
|
||||
def classify
|
||||
return to_enum :classify unless block_given?
|
||||
h = {}
|
||||
@@ -193,11 +301,18 @@ class Set
|
||||
h
|
||||
end
|
||||
|
||||
# Divides the set into subsets based on the result of the given block.
|
||||
#
|
||||
# @yield [Object] Each element in the set
|
||||
# @yieldreturn [Object] The division key
|
||||
# @return [Set] A set containing the divided subsets
|
||||
# call-seq:
|
||||
# set.divide { |obj1, obj2| block } -> set
|
||||
# set.divide -> enumerator
|
||||
#
|
||||
# Divides the set into a set of subsets according to the commonality defined
|
||||
# by the given block. Returns an enumerator if no block is given.
|
||||
#
|
||||
# set = Set.new([1, 2, 3, 4, 5, 6])
|
||||
# set.divide { |x, y| (x % 3) == (y % 3) }
|
||||
# #=> #<Set: {#<Set: {1, 4}>, #<Set: {2, 5}>, #<Set: {3, 6}>}>
|
||||
#
|
||||
def divide(&func)
|
||||
return to_enum :divide unless block_given?
|
||||
|
||||
|
||||
Reference in New Issue
Block a user