ruby-changes:68118
From: Burdette <ko1@a...>
Date: Sat, 25 Sep 2021 00:35:41 +0900 (JST)
Subject: [ruby-changes:68118] bbdfce96a2 (master): Enhanced RDoc for Struct (#4890)
https://git.ruby-lang.org/ruby.git/commit/?id=bbdfce96a2 From bbdfce96a29e30680b8038d1902ef6b9116d0f08 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Fri, 24 Sep 2021 10:35:19 -0500 Subject: Enhanced RDoc for Struct (#4890) Treated: #each #each_pair #inspect #to_a #to_h #[] #[]= --- struct.c | 170 ++++++++++++++++++++++++++++++++++++++++----------------------- 1 file changed, 107 insertions(+), 63 deletions(-) diff --git a/struct.c b/struct.c index a040af2..8bd59be 100644 --- a/struct.c +++ b/struct.c @@ -206,6 +206,8 @@ rb_struct_s_members_m(VALUE klass) https://github.com/ruby/ruby/blob/trunk/struct.c#L206 * * Customer = Struct.new(:name, :address, :zip) * Customer.new.members # => [:name, :address, :zip] + * + * Related: #to_a. */ static VALUE @@ -868,21 +870,24 @@ struct_enum_size(VALUE s, VALUE args, VALUE eobj) https://github.com/ruby/ruby/blob/trunk/struct.c#L870 /* * call-seq: - * struct.each {|obj| block } -> struct - * struct.each -> enumerator + * each {|value| ... } -> self + * each -> enumerator * - * Yields the value of each struct member in order. If no block is given an - * enumerator is returned. + * 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 {|x| puts(x) } + * 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 * - * Produces: + * Returns an Enumerator if no block is given. * - * Joe Smith - * 123 Maple, Anytown NC - * 12345 + * Related: #each_pair. */ static VALUE @@ -899,21 +904,25 @@ rb_struct_each(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L904 /* * call-seq: - * struct.each_pair {|sym, obj| block } -> struct - * struct.each_pair -> enumerator + * each_pair {|(name, value)| ... } -> self + * each_pair -> enumerator * - * Yields the name and value of each struct member in order. If no block is - * given an enumerator is returned. + * Calls the given block with each member name/value pair; returns +self+: * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.each_pair {|name, value| puts("#{name} => #{value}") } + * Customer = Struct.new(:name, :address, :zip) # => Customer + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.each_pair {|(name, value)| p "#{name} => #{value}" } + * + * Output: + * + * "name => Joe Smith" + * "address => 123 Maple, Anytown NC" + * "zip => 12345" + * + * Returns an Enumerator if no block is given. * - * Produces: + * Related: #each. * - * name => Joe Smith - * address => 123 Maple, Anytown NC - * zip => 12345 */ static VALUE @@ -986,11 +995,17 @@ inspect_struct(VALUE s, VALUE dummy, int recur) https://github.com/ruby/ruby/blob/trunk/struct.c#L995 } /* - * call-seq: - * struct.to_s -> string - * struct.inspect -> string + * call-seq: + * inspect -> string + * + * Returns a string representation of +self+: + * + * Customer = Struct.new(:name, :address, :zip) # => Customer + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.inspect # => "#<struct Customer name=\"Joe Smith\", address=\"123 Maple, Anytown NC\", zip=12345>" + * + * Struct#to_s is an alias for Struct#inspect. * - * Returns a description of this struct as a string. */ static VALUE @@ -1001,14 +1016,17 @@ rb_struct_inspect(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L1016 /* * call-seq: - * struct.to_a -> array - * struct.values -> array + * to_a -> array * - * Returns the values for this struct as an Array. + * Returns the values in +self+ as an array: * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.to_a[1] #=> "123 Maple, Anytown NC" + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.to_a # => ["Joe Smith", "123 Maple, Anytown NC", 12345] + * + * Struct#values and Struct#deconstruct are aliases for Struct#to_a. + * + * Related: #members. */ static VALUE @@ -1019,19 +1037,25 @@ rb_struct_to_a(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L1037 /* * call-seq: - * struct.to_h -> hash - * struct.to_h {|name, value| block } -> hash + * to_h -> hash + * to_h {|name, value| ... } -> hash * - * Returns a Hash containing the names and values for the struct's members. + * Returns a hash containing the name and value for each member: * - * If a block is given, the results of the block on each pair of the receiver - * will be used as pairs. + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * h = joe.to_h + * h # => {:name=>"Joe Smith", :address=>"123 Maple, Anytown NC", :zip=>12345} + * + * If a block is given, it is called with each name/value pair; + * the block should return a 2-element array whose elements will become + * a key/value pair in the returned hash: + * + * h = joe.to_h{|name, value| [name.upcase, value.to_s.upcase]} + * h # => {:NAME=>"JOE SMITH", :ADDRESS=>"123 MAPLE, ANYTOWN NC", :ZIP=>"12345"} + * + * Raises ArgumentError if the block returns an inappropriate value. * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) - * joe.to_h[:address] #=> "123 Maple, Anytown NC" - * joe.to_h{|name, value| [name.upcase, value.to_s.upcase]}[:ADDRESS] - * #=> "123 MAPLE, ANYTOWN NC" */ static VALUE @@ -1154,19 +1178,28 @@ invalid_struct_pos(VALUE s, VALUE idx) https://github.com/ruby/ruby/blob/trunk/struct.c#L1178 /* * call-seq: - * struct[member] -> object - * struct[index] -> object + * struct[name] -> object + * struct[n] -> object * - * Attribute Reference---Returns the value of the given struct +member+ or - * the member at the given +index+. Raises NameError if the +member+ does - * not exist and IndexError if the +index+ is out of range. + * Returns a value from +self+. * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * With symbol or string argument +name+ given, returns the value for the named member: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[:zip] # => 12345 + * + * Raises NameError if +name+ is not the name of a member. + * + * With integer argument +n+ given, returns <tt>self.values[n]</tt> + * if +n+ is in range; + * see {Array Indexes}[Array.html#class-Array-label-Array+Indexes]: + * + * joe[2] # => 12345 + * joe[-2] # => "123 Maple, Anytown NC" + * + * Raises IndexError if +n+ is out of range. * - * joe["name"] #=> "Joe Smith" - * joe[:name] #=> "Joe Smith" - * joe[0] #=> "Joe Smith" */ VALUE @@ -1179,21 +1212,32 @@ rb_struct_aref(VALUE s, VALUE idx) https://github.com/ruby/ruby/blob/trunk/struct.c#L1212 /* * call-seq: - * struct[member] = obj -> obj - * struct[index] = obj -> obj + * struct[name] = value -> value + * struct[n] = value -> value * - * Attribute Assignment---Sets the value of the given struct +member+ or - * the member at the given +index+. Raises NameError if the +member+ does not - * exist and IndexError if the +index+ is out of range. + * Assigns a value to a member. * - * Customer = Struct.new(:name, :address, :zip) - * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * With symbol or string argument +name+ given, assigns the given +value+ + * to the named member; returns +value+: + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[:zip] = 54321 # => 54321 + * joe # => #<struct Customer name="Joe Smith", address="123 Maple, Anytown NC", zip=54321> + * + * Raises NameError if +name+ is not the name of a member. + * + * With integer argument +n+ given, assigns the given +value+ + * to the +n+th member if +n+ is in range; + * see {Array Indexes}[Array.html#class-Array-label-Array+Indexes]: + * + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe[2] = 54321 # => 54321 + * joe[-3] = 'Joseph Smith' # => "Joseph Smith" + * joe # => #<struct Customer name="Joseph Smith", address="123 Maple, Anytown NC", zip=54321> * - * joe["name"] = "Luke" - * joe[:zip] = "90210" + * Raises IndexError if +n+ is out of range. * - * joe.name #=> "Luke" - * joe.zip #=> "90210" */ VALUE -- cgit v1.1 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/