rbs 2.0.0 → 2.1.0

data/core/struct.rbs

@@ -1,40 +1,295 @@
-# A [Struct](Struct) is a convenient way to bundle a
-# number of attributes together, using accessor methods, without having to
-# write an explicit class.
-#
-# The [Struct](Struct) class generates new subclasses
-# that hold a set of members and their values. For each member a reader
-# and writer method is created similar to
-# [Module\#attr\_accessor](https://ruby-doc.org/core-2.6.3/Module.html#method-i-attr_accessor)
-# .
-#
-# ```ruby
-# Customer = Struct.new(:name, :address) do
-#   def greeting
-#     "Hello #{name}!"
-#   end
-# end
-#
-# dave = Customer.new("Dave", "123 Main")
-# dave.name     #=> "Dave"
-# dave.greeting #=> "Hello Dave!"
-# ```
-#
-# See [::new](Struct#method-c-new) for further
-# examples of creating struct subclasses and instances.
-#
-# In the method descriptions that follow, a "member" parameter refers to a
-# struct member which is either a quoted string ( `"name"` ) or a
-# [Symbol](https://ruby-doc.org/core-2.6.3/Symbol.html) ( `:name` ).
+# <!-- rdoc-file=struct.c -->
+# Class Struct provides a convenient way to create a simple class that can store
+# and fetch values.
+#
+# This example creates a subclass of `Struct`, `Struct::Customer`; the first
+# argument, a string, is the name of the subclass; the other arguments, symbols,
+# determine the *members* of the new subclass.
+#
+#     Customer = Struct.new('Customer', :name, :address, :zip)
+#     Customer.name       # => "Struct::Customer"
+#     Customer.class      # => Class
+#     Customer.superclass # => Struct
+#
+# Corresponding to each member are two methods, a writer and a reader, that
+# store and fetch values:
+#
+#     methods = Customer.instance_methods false
+#     methods # => [:zip, :address=, :zip=, :address, :name, :name=]
+#
+# An instance of the subclass may be created, and its members assigned values,
+# via method `::new`:
+#
+#     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+#     joe # => #<struct Struct::Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=12345>
+#
+# The member values may be managed thus:
+#
+#     joe.name    # => "Joe Smith"
+#     joe.name = 'Joseph Smith'
+#     joe.name    # => "Joseph Smith"
+#
+# And thus; note that member name may be expressed as either a string or a
+# symbol:
+#
+#     joe[:name]  # => "Joseph Smith"
+#     joe[:name] = 'Joseph Smith, Jr.'
+#     joe['name'] # => "Joseph Smith, Jr."
+#
+# See Struct::new.
+#
+# ## What's Here
+#
+# First, what's elsewhere. Class Struct:
+#
+# *   Inherits from [class
+#     Object](Object.html#class-Object-label-What-27s+Here).
+# *   Includes [module
+#     Enumerable](Enumerable.html#module-Enumerable-label-What-27s+Here), which
+#     provides dozens of additional methods.
+#
+#
+# Here, class Struct provides methods that are useful for:
+#
+# *   [Creating a Struct
+#     Subclass](#class-Struct-label-Methods+for+Creating+a+Struct+Subclass)
+# *   [Querying](#class-Struct-label-Methods+for+Querying)
+# *   [Comparing](#class-Struct-label-Methods+for+Comparing)
+# *   [Fetching](#class-Struct-label-Methods+for+Fetching)
+# *   [Assigning](#class-Struct-label-Methods+for+Assigning)
+# *   [Iterating](#class-Struct-label-Methods+for+Iterating)
+# *   [Converting](#class-Struct-label-Methods+for+Converting)
+#
+#
+# ### Methods for Creating a Struct Subclass
+#
+# ::new
+# :   Returns a new subclass of Struct.
+#
+#
+# ### Methods for Querying
+#
+# #hash
+# :   Returns the integer hash code.
+# #length, #size
+# :   Returns the number of members.
+#
+#
+# ### Methods for Comparing
+#
+# [#==](#method-i-3D-3D)
+# :   Returns whether a given object is equal to `self`, using `==` to compare
+#     member values.
+# #eql?
+# :   Returns whether a given object is equal to `self`, using `eql?` to compare
+#     member values.
+#
+#
+# ### Methods for Fetching
+#
+# #[]
+# :   Returns the value associated with a given member name.
+# #to_a, #values, #deconstruct
+# :   Returns the member values in `self` as an array.
+# #deconstruct_keys
+# :   Returns a hash of the name/value pairs for given member names.
+# #dig
+# :   Returns the object in nested objects that is specified by a given member
+#     name and additional arguments.
+# #members
+# :   Returns an array of the member names.
+# #select, #filter
+# :   Returns an array of member values from `self`, as selected by the given
+#     block.
+# #values_at
+# :   Returns an array containing values for given member names.
+#
+#
+# ### Methods for Assigning
+#
+# #[]=
+# :   Assigns a given value to a given member name.
+#
+#
+# ### Methods for Iterating
+#
+# #each
+# :   Calls a given block with each member name.
+# #each_pair
+# :   Calls a given block with each member name/value pair.
+#
+#
+# ### Methods for Converting
+#
+# #inspect, #to_s
+# :   Returns a string representation of `self`.
+# #to_h
+# :   Returns a hash of the member name/value pairs in `self`.
+#
 class Struct[Elem] < Object
   include Enumerable[Elem?]
 
   type attribute_name = Symbol | String
 
+  # <!--
+  #   rdoc-file=struct.c
+  #   - Struct.new(*member_names, keyword_init: false){|Struct_subclass| ... } -> Struct_subclass
+  #   - Struct.new(class_name, *member_names, keyword_init: false){|Struct_subclass| ... } -> Struct_subclass
+  #   - Struct_subclass.new(*member_names) -> Struct_subclass_instance
+  #   - Struct_subclass.new(**member_names) -> Struct_subclass_instance
+  # -->
+  # `Struct.new` returns a new subclass of `Struct`.  The new subclass:
+  #
+  # *   May be anonymous, or may have the name given by `class_name`.
+  # *   May have members as given by `member_names`.
+  # *   May have initialization via ordinary arguments (the default) or via
+  #     keyword arguments (if `keyword_init: true` is given).
+  #
+  #
+  # The new subclass has its own method `::new`; thus:
+  #
+  #     Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
+  #     f = Foo.new(0, 1)                   # => #<struct Struct::Foo foo=0, bar=1>
+  #
+  # **\Class Name**
+  #
+  # With string argument `class_name`, returns a new subclass of `Struct` named
+  # `Struct::*class_name`*:
+  #
+  #     Foo = Struct.new('Foo', :foo, :bar) # => Struct::Foo
+  #     Foo.name                            # => "Struct::Foo"
+  #     Foo.superclass                      # => Struct
+  #
+  # Without string argument `class_name`, returns a new anonymous subclass of
+  # `Struct`:
+  #
+  #     Struct.new(:foo, :bar).name # => nil
+  #
+  # **Block**
+  #
+  # With a block given, the created subclass is yielded to the block:
+  #
+  #     Customer = Struct.new('Customer', :name, :address) do |new_class|
+  #       p "The new subclass is #{new_class}"
+  #       def greeting
+  #         "Hello #{name} at #{address}"
+  #       end
+  #     end           # => Struct::Customer
+  #     dave = Customer.new('Dave', '123 Main')
+  #     dave # =>     #<struct Struct::Customer name="Dave", address="123 Main">
+  #     dave.greeting # => "Hello Dave at 123 Main"
+  #
+  # Output, from `Struct.new`:
+  #
+  #     "The new subclass is Struct::Customer"
+  #
+  # **Member Names**
+  #
+  # Symbol arguments `member_names` determines the members of the new subclass:
+  #
+  #     Struct.new(:foo, :bar).members        # => [:foo, :bar]
+  #     Struct.new('Foo', :foo, :bar).members # => [:foo, :bar]
+  #
+  # The new subclass has instance methods corresponding to `member_names`:
+  #
+  #     Foo = Struct.new('Foo', :foo, :bar)
+  #     Foo.instance_methods(false) # => [:foo, :bar, :foo=, :bar=]
+  #     f = Foo.new                 # => #<struct Struct::Foo foo=nil, bar=nil>
+  #     f.foo                       # => nil
+  #     f.foo = 0                   # => 0
+  #     f.bar                       # => nil
+  #     f.bar = 1                   # => 1
+  #     f                           # => #<struct Struct::Foo foo=0, bar=1>
+  #
+  # **Singleton Methods**
+  #
+  # A subclass returned by Struct.new has these singleton methods:
+  #
+  # *   Method `::new ` creates an instance of the subclass:
+  #
+  #         Foo.new          # => #<struct Struct::Foo foo=nil, bar=nil>
+  #         Foo.new(0)       # => #<struct Struct::Foo foo=0, bar=nil>
+  #         Foo.new(0, 1)    # => #<struct Struct::Foo foo=0, bar=1>
+  #         Foo.new(0, 1, 2) # Raises ArgumentError: struct size differs
+  #
+  #     Method `::[]` is an alias for method `::new`.
+  #
+  # *   Method `:inspect` returns a string representation of the subclass:
+  #
+  #         Foo.inspect
+  #         # => "Struct::Foo"
+  #
+  # *   Method `::members` returns an array of the member names:
+  #
+  #         Foo.members # => [:foo, :bar]
+  #
+  #
+  # **Keyword Argument**
+  #
+  # By default, the arguments for initializing an instance of the new subclass are
+  # ordinary arguments (not keyword arguments). With optional keyword argument
+  # `keyword_init: true`, the new subclass is initialized with keyword arguments:
+  #
+  #     # Without keyword_init: true.
+  #     Foo = Struct.new('Foo', :foo, :bar)
+  #     Foo                     # => Struct::Foo
+  #     Foo.new(0, 1)           # => #<struct Struct::Foo foo=0, bar=1>
+  #     # With keyword_init: true.
+  #     Bar = Struct.new(:foo, :bar, keyword_init: true)
+  #     Bar # =>                # => Bar(keyword_init: true)
+  #     Bar.new(bar: 1, foo: 0) # => #<struct Bar foo=0, bar=1>
+  #
   def initialize: (attribute_name, *attribute_name, ?keyword_init: boolish) ?{ () -> void } -> void
 
+  # <!--
+  #   rdoc-file=struct.c
+  #   - each {|value| ... } -> self
+  #   - each -> enumerator
+  # -->
+  # Calls the given block with the value of each member; returns `self`:
+  #
+  #     Customer = Struct.new(:name, :address, :zip)
+  #     joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
+  #     joe.each {|value| p value }
+  #
+  # Output:
+  #
+  #     "Joe Smith"
+  #     "123 Maple, Anytown NC"
+  #     12345
+  #
+  # Returns an Enumerator if no block is given.
+  #
+  # Related: #each_pair.
+  #
   def each: () -> ::Enumerator[Elem?, self]
           | () { (Elem? item) -> void } -> self
 
+  # <!--
+  #   rdoc-file=struct.c
+  #   - StructClass::members -> array_of_symbols
+  # -->
+  # Returns the member names of the Struct descendant as an array:
+  #
+  #     Customer = Struct.new(:name, :address, :zip)
+  #     Customer.members # => [:name, :address, :zip]
+  #
   def self.members: () -> ::Array[Symbol]
+
+  # <!--
+  #   rdoc-file=struct.c
+  #   - StructClass::keyword_init? -> true or falsy value
+  # -->
+  # Returns `true` if the class was initialized with `keyword_init: true`.
+  # Otherwise returns `nil` or `false`.
+  #
+  # Examples:
+  #     Foo = Struct.new(:a)
+  #     Foo.keyword_init? # => nil
+  #     Bar = Struct.new(:a, keyword_init: true)
+  #     Bar.keyword_init? # => true
+  #     Baz = Struct.new(:a, keyword_init: false)
+  #     Baz.keyword_init? # => false
+  #
+  def self.keyword_init?: () -> (true | false | nil)
 end