JezK
Edit File: set.rbs
# <!-- rdoc-file=lib/set.rb --> # This library provides the Set class, which deals with a collection # of unordered values with no duplicates. It is a hybrid of Array's # intuitive inter-operation facilities and Hash's fast lookup. # The method `to_set` is added to Enumerable for convenience. # Set implements a collection of unordered values with no duplicates. # This is a hybrid of Array's intuitive inter-operation facilities and # Hash's fast lookup. # Set is easy to use with Enumerable objects (implementing `each`). # Most of the initializer methods and binary operators accept generic # Enumerable objects besides sets and arrays. An Enumerable object # can be converted to Set using the `to_set` method. # Set uses Hash as storage, so you must note the following points: # * Equality of elements is determined according to Object#eql? and # Object#hash. Use Set#compare_by_identity to make a set compare # its elements by their identity. # * Set assumes that the identity of each element does not change # while it is stored. Modifying an element of a set will render the # set to an unreliable state. # * When a string is to be stored, a frozen copy of the string is # stored instead unless the original string is already frozen. # # ## Comparison # The comparison operators `<`, `>`, `<=`, and `>=` are implemented as # shorthand for the {proper_,}{subset?,superset?} methods. The `<=>` # operator reflects this order, or return `nil` for sets that both # have distinct elements (`{x, y}` vs. `{x, z}` for example). # ## Example # require 'set' # 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"}> # s1.merge([2, 6]) #=> #<Set: {1, 2, "foo", 6}> # s1.subset?(s2) #=> false # s2.subset?(s1) #=> true # # ## Contact # * Akinori MUSHA <mailto:knu@iDaemons.org> (current maintainer) # # ## What's Here # First, what's elsewhere. Class Set: # * Inherits from [class # Object](https://docs.ruby-lang.org/en/master/Object.html#class-Object-labe # l-What-27s+Here). # * Includes [module # which provides dozens of additional # g/en/master/Enumerable.html#module-Enumerable-label-What-27s+Here), # 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](#class-Set-label-Methods+for+Creating+a+Set) # * [Set Operations](#class-Set-label-Methods+for+Set+Operations) # * [Comparing](#class-Set-label-Methods+for+Comparing) # * [Querying](#class-Set-label-Methods+for+Querying) # * [Assigning](#class-Set-label-Methods+for+Assigning) # * [Deleting](#class-Set-label-Methods+for+Deleting) # * [Converting](#class-Set-label-Methods+for+Converting) # * [Iterating](#class-Set-label-Methods+for+Iterating) # * [And more....](#class-Set-label-Other+Methods) # # ### Methods for Creating a Set # * ::[] - # Returns a new set containing the given objects. # * ::new - # Returns a new set containing either the given objects # (if no block given) or the return values from the called block # (if a block given). # # ### Methods for Set Operations # * [|](#method-i-7C) (aliased as #union and #+) - # Returns a new set containing all elements from `self` # and all elements from a given enumerable (no duplicates). # * [&](#method-i-26) (aliased as #intersection) - # Returns a new set containing all elements common to `self` # and a given enumerable. # * [-](#method-i-2D) (aliased as #difference) - # Returns a copy of `self` with all elements # in a given enumerable removed. # * [\^](#method-i-5E) - # Returns a new set containing all elements from `self` # and a given enumerable except those common to both. # # ### Methods for Comparing # * [<=>](#method-i-3C-3D-3E) - # Returns -1, 0, or 1 as `self` is less than, equal to, # or greater than a given object. # * [==](#method-i-3D-3D) - # Returns whether `self` and a given enumerable are equal, # as determined by Object#eql?. # * #compare_by_identity? - # Returns whether the set considers only identity # when comparing elements. # # ### Methods for Querying # * #length (aliased as #size) - # Returns the count of elements. # * #empty? - # Returns whether the set has no elements. # * #include? (aliased as #member? and #===) - # Returns whether a given object is an element in the set. # * #subset? (aliased as [<=](#method-i-3C-3D)) - # Returns whether a given object is a subset of the set. # * #proper_subset? (aliased as [<](#method-i-3C)) - # Returns whether a given enumerable is a proper subset of the set. # * #superset? (aliased as [<=](#method-i-3E-3D)]) - # Returns whether a given enumerable is a superset of the set. # * #proper_superset? (aliased as [>](#method-i-3E)) - # Returns whether a given enumerable is a proper superset of the set. # * #disjoint? - # Returns `true` if the set and a given enumerable # have no common elements, `false` otherwise. # * #intersect? - # Returns `true` if the set and a given enumerable - # have any common elements, `false` otherwise. # * #compare_by_identity? - # Returns whether the set considers only identity # when comparing elements. # # ### Methods for Assigning # * #add (aliased as #<<) - # Adds a given object to the set; returns `self`. # * #add? - # If the given object is not an element in the set, # adds it and returns `self`; otherwise, returns `nil`. # * #merge - # Adds each given object to the set; returns `self`. # * #replace - # Replaces the contents of the set with the contents # of a given enumerable. # # ### Methods for Deleting # * #clear - # Removes all elements in the set; returns `self`. # * #delete - # Removes a given object from the set; returns `self`. # * #delete? - # If the given object is an element in the set, # removes it and returns `self`; otherwise, returns `nil`. # * #subtract - # Removes each given object from the set; returns `self`. # * #delete_if - Removes elements specified by a given block. # * #select! (aliased as #filter!) - # Removes elements not specified by a given block. # * #keep_if - # Removes elements not specified by a given block. # * #reject! # Removes elements specified by a given block. # # ### Methods for Converting # * #classify - # Returns a hash that classifies the elements, # as determined by the given block. # * #collect! (aliased as #map!) - # Replaces each element with a block return-value. # * #divide - # Returns a hash that classifies the elements, # as determined by the given block; # differs from #classify in that the block may accept # either one or two arguments. # * #flatten - # Returns a new set that is a recursive flattening of `self`. # #flatten! - # Replaces each nested set in `self` with the elements from that set. # * #inspect (aliased as #to_s) - # Returns a string displaying the elements. # * #join - # Returns a string containing all elements, converted to strings # as needed, and joined by the given record separator. # * #to_a - # Returns an array containing all set elements. # * #to_set - # Returns `self` if given no arguments and no block; # with a block given, returns a new set consisting of block # return values. # # ### Methods for Iterating # * #each - # Calls the block with each successive element; returns `self`. # # ### Other Methods # * #reset - # Resets the internal state; useful if an object # has been modified while an element in the set. # class Set[A] # <!-- # rdoc-file=lib/set.rb # - new(enum = nil) { |o| ... } # --> # Creates a new set containing the elements of the given enumerable # object. # If a block is given, the elements of enum are preprocessed by the # 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..5) #=> #<Set: {1, 2, 3, 4, 5}> # Set.new([1, 2, 3]) { |x| x * x } #=> #<Set: {1, 4, 9}> # def initialize: (_Each[A]) -> untyped | [X] (_Each[X]) { (X) -> A } -> untyped | (?nil) -> untyped # <!-- # rdoc-file=lib/set.rb # - [](*ary) # --> # 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.[]: [X] (*X) -> Set[X] # <!-- # rdoc-file=lib/set.rb # - &(enum) # --> # Returns a new set containing elements common to the set and the # given enumerable object. # Set[1, 3, 5] & Set[3, 2, 1] #=> #<Set: {3, 1}> # Set['a', 'b', 'z'] & ['a', 'b', 'c'] #=> #<Set: {"a", "b"}> # def &: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - intersection(enum) # --> # alias intersection & # <!-- # rdoc-file=lib/set.rb # - |(enum) # --> # Returns a new set built by merging the set and the elements of the # given enumerable object. # 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 |: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - union(enum) # --> # alias union | # <!-- # rdoc-file=lib/set.rb # - +(enum) # --> # alias + | # <!-- # rdoc-file=lib/set.rb # - -(enum) # --> # Returns a new set built by duplicating the set, removing every # element that appears in the given enumerable object. # Set[1, 3, 5] - Set[1, 5] #=> #<Set: {3}> # Set['a', 'b', 'z'] - ['a', 'c'] #=> #<Set: {"b", "z"}> # def -: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - difference(enum) # --> # alias difference - # <!-- # rdoc-file=lib/set.rb # - add(o) # --> # Adds the given object to the set and returns self. Use `merge` to # 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(2) #=> #<Set: {1, 2}> # def add: (A) -> self # <!-- # rdoc-file=lib/set.rb # - <<(o) # --> # alias << add # <!-- # rdoc-file=lib/set.rb # - add?(o) # --> # Adds the given object to the set and returns self. If the # 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?(2) #=> nil # def add?: (A) -> self? # <!-- # rdoc-file=lib/set.rb # - include?(o) # --> # Returns true if the set contains the given object. # Note that `include?` and `member?` do not test member # equality using `==` as do other Enumerables. # See also Enumerable#include? # def include?: (A) -> bool # <!-- # rdoc-file=lib/set.rb # - member?(o) # --> # alias member? include? # <!-- # rdoc-file=lib/set.rb # - ^(enum) # --> # 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[1, 2] ^ Set[2, 3] #=> #<Set: {3, 1}> # Set[1, 'b', 'c'] ^ ['b', 'd'] #=> #<Set: {"d", 1, "c"}> # def ^: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - classify() { |o| ... } # --> # Classifies the set by the return value of the given block and # returns a hash of {value => set of elements} pairs. The block is # called once for each element of the set, passing the element as # parameter. # require 'set' # files = Set.new(Dir.glob("*.rb")) # hash = files.classify { |f| File.mtime(f).year } # 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: [X] () { (A) -> X } -> Hash[X, self] # <!-- # rdoc-file=lib/set.rb # - clear() # --> # Removes all elements and returns self. # set = Set[1, 'c', :s] #=> #<Set: {1, "c", :s}> # set.clear #=> #<Set: {}> # set #=> #<Set: {}> # def clear: () -> self # <!-- # rdoc-file=lib/set.rb # - collect!() { |o| ... } # --> # Replaces the elements with ones returned by `collect()`. # Returns an enumerator if no block is given. # def collect!: () { (A) -> A } -> self # <!-- # rdoc-file=lib/set.rb # - map!() # --> # alias map! collect! # <!-- # rdoc-file=lib/set.rb # - delete(o) # --> # Deletes the given object from the set and returns self. Use # `subtract` to delete many items at once. # def delete: (A) -> self # <!-- # rdoc-file=lib/set.rb # - delete?(o) # --> # Deletes the given object from the set and returns self. If the # object is not in the set, returns nil. # def delete?: (A) -> self? # <!-- # rdoc-file=lib/set.rb # - delete_if() { |o| ... } # --> # Deletes every element of the set for which block evaluates to # true, and returns self. Returns an enumerator if no block is # given. # def delete_if: () { (A) -> untyped } -> self # <!-- # rdoc-file=lib/set.rb # - reject!(&block) # --> # Equivalent to Set#delete_if, but returns nil if no changes were # made. Returns an enumerator if no block is given. # def reject!: () { (A) -> untyped } -> self # <!-- # rdoc-file=lib/set.rb # - disjoint?(set) # --> # Returns true if the set and the given enumerable have # no element in common. This method is the opposite of `intersect?`. # Set[1, 2, 3].disjoint? Set[3, 4] #=> false # Set[1, 2, 3].disjoint? Set[4, 5] #=> true # Set[1, 2, 3].disjoint? [3, 4] #=> false # Set[1, 2, 3].disjoint? 4..5 #=> true # def disjoint?: (self) -> bool # <!-- # rdoc-file=lib/set.rb # - divide(&func) # --> # Divides the set into a set of subsets according to the commonality # defined by the given block. # If the arity of the block is 2, elements o1 and o2 are in common # if block.call(o1, o2) is true. Otherwise, elements o1 and o2 are # in common if block.call(o1) == block.call(o2). # require 'set' # numbers = Set[1, 3, 4, 6, 9, 10, 11] # set = numbers.divide { |i,j| (i - j).abs == 1 } # set #=> #<Set: {#<Set: {1}>, # # #<Set: {11, 9, 10}>, # # #<Set: {3, 4}>, # # #<Set: {6}>}> # # Returns an enumerator if no block is given. # def divide: () { (A, A) -> untyped } -> Set[self] | () { (A) -> untyped } -> Set[self] # <!-- # rdoc-file=lib/set.rb # - each(&block) # --> # Calls the given block once for each element in the set, passing # the element as parameter. Returns an enumerator if no block is # given. # def each: () { (A) -> void } -> self # <!-- # rdoc-file=lib/set.rb # - empty?() # --> # Returns true if the set contains no elements. # def empty?: () -> bool # <!-- # rdoc-file=lib/set.rb # - flatten() # --> # Returns a new set that is a copy of the set, flattening each # containing set recursively. # def flatten: () -> Set[untyped] # <!-- # rdoc-file=lib/set.rb # - intersect?(set) # --> # Returns true if the set and the given enumerable have at least one # element in common. # Set[1, 2, 3].intersect? Set[4, 5] #=> false # Set[1, 2, 3].intersect? Set[3, 4] #=> true # Set[1, 2, 3].intersect? 4..5 #=> false # Set[1, 2, 3].intersect? [3, 4] #=> true # def intersect?: (self) -> bool # <!-- # rdoc-file=lib/set.rb # - keep_if() { |o| ... } # --> # Deletes every element of the set for which block evaluates to # false, and returns self. Returns an enumerator if no block is # given. # def keep_if: () { (A) -> untyped } -> self # <!-- # rdoc-file=lib/set.rb # - size() # --> # Returns the number of elements. # def size: () -> Integer # <!-- # rdoc-file=lib/set.rb # - length() # --> # alias length size # <!-- # rdoc-file=lib/set.rb # - merge(enum) # --> # Merges the elements of the given enumerable object to the set and # returns self. # def merge: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - subset?(set) # --> # Returns true if the set is a subset of the given set. # def subset?: (self) -> bool def proper_subst?: (self) -> bool # <!-- # rdoc-file=lib/set.rb # - superset?(set) # --> # Returns true if the set is a superset of the given set. # def superset?: (self) -> bool # <!-- # rdoc-file=lib/set.rb # - proper_superset?(set) # --> # Returns true if the set is a proper superset of the given set. # def proper_superset?: (self) -> bool # <!-- # rdoc-file=lib/set.rb # - replace(enum) # --> # 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: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - reset() # --> # Resets the internal state after modification to existing elements # and returns self. # Elements will be reindexed and deduplicated. # def reset: () -> self # <!-- # rdoc-file=lib/set.rb # - select!(&block) # --> # Equivalent to Set#keep_if, but returns nil if no changes were # made. Returns an enumerator if no block is given. # def select!: () { (A) -> untyped } -> self? # <!-- # rdoc-file=lib/set.rb # - subtract(enum) # --> # Deletes every element that appears in the given enumerable object # and returns self. # def subtract: (_Each[A]) -> self # <!-- # rdoc-file=lib/set.rb # - to_a() # --> # Converts the set to an array. The order of elements is uncertain. # Set[1, 2].to_a #=> [1, 2] # Set[1, 'c', :s].to_a #=> [1, "c", :s] # def to_a: () -> Array[A] include Enumerable[A] end %a{annotate:rdoc:skip} module Enumerable[unchecked out Elem] # <!-- # rdoc-file=lib/set.rb # - to_set(klass = Set, *args, &block) # --> # Makes a set from the enumerable object with given arguments. # Needs to `require "set"` to use this method. # def to_set: () -> Set[Elem] end