From 479711700eac94d99b91515f6db6c9bc3a2050c9 Mon Sep 17 00:00:00 2001 From: "Yukihiro \"Matz\" Matsumoto" Date: Thu, 17 Jul 2025 14:46:41 +0900 Subject: [PATCH] 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 --- mrbgems/mruby-set/mrblib/set.rb | 213 ++++++++++++++++++++++++-------- 1 file changed, 164 insertions(+), 49 deletions(-) diff --git a/mrbgems/mruby-set/mrblib/set.rb b/mrbgems/mruby-set/mrblib/set.rb index 5015258dc..c739342e8 100644 --- a/mrbgems/mruby-set/mrblib/set.rb +++ b/mrbgems/mruby-set/mrblib/set.rb @@ -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.new([1, 2, 2, 3]) #=> # + # Set.new([1, 2, 3]) { |x| x * 2 } #=> # + # 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 #=> # + # 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 #=> # + # 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 #=> # + # 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.new([1, 2, 3]) & [2, 3, 4] #=> # + # 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.new([1, 2]) | [2, 3, 4] #=> # + # Set.new([1, 2]) + [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.new([1, 2, 3, 4]) - [2, 4] #=> # + # 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.new([1, 2]) ^ [2, 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 + # #=> # + # 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 #=> # + # 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 #=> # + # 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 #=> # + # 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.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.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=>#, 2=>#, 0=>#} + # 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) } + # #=> #, #, #}> + # def divide(&func) return to_enum :divide unless block_given?