1berry/ruby
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Enhanced RDoc for Struct (#4890)

Browse Source 
Treated:

    #each
    #each_pair
    #inspect
    #to_a
    #to_h
    #[]
    #[]=
This commit is contained in:
Burdette Lamar 2021-09-24 10:35:19 -05:00 committed by GitHub
parent 7adfb14f60
commit bbdfce96a2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
Notes: git 2021-09-25 00:35:43 +09:00 
Merged-By: BurdetteLamar <BurdetteLamar@Yahoo.com>
1 changed files with 107 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

146
struct.c
View File

@ -206,6 +206,8 @@ rb_struct_s_members_m(VALUE klass)
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip)
* Customer.new.members # => [:name, :address, :zip] * Customer.new.members # => [:name, :address, :zip]
*
* Related: #to_a.
*/ */
static VALUE static VALUE
@ -868,21 +870,24 @@ struct_enum_size(VALUE s, VALUE args, VALUE eobj)
/* /*
* call-seq: * call-seq:
* struct.each {|obj| block } -> struct * each {|value| ... } -> self
* struct.each -> enumerator * each -> enumerator
* *
* Yields the value of each struct member in order. If no block is given an * Calls the given block with the value of each member; returns +self+:
* enumerator is returned.
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.each {|x| puts(x) } * joe.each {|value| p value }
* *
* Produces: * Output:
* *
* Joe Smith * "Joe Smith"
* 123 Maple, Anytown NC * "123 Maple, Anytown NC"
* 12345 * 12345
*
* Returns an Enumerator if no block is given.
*
* Related: #each_pair.
*/ */
static VALUE static VALUE
@ -899,21 +904,25 @@ rb_struct_each(VALUE s)
/* /*
* call-seq: * call-seq:
* struct.each_pair {|sym, obj| block } -> struct * each_pair {|(name, value)| ... } -> self
* struct.each_pair -> enumerator * each_pair -> enumerator
* *
* Yields the name and value of each struct member in order. If no block is * Calls the given block with each member name/value pair; returns +self+:
* given an enumerator is returned.
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip) # => Customer
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.each_pair {|name, value| puts("#{name} => #{value}") } * joe.each_pair {|(name, value)| p "#{name} => #{value}" }
* *
* Produces: * Output:
*
* "name => Joe Smith"
* "address => 123 Maple, Anytown NC"
* "zip => 12345"
*
* Returns an Enumerator if no block is given.
*
* Related: #each.
* *
* name => Joe Smith
* address => 123 Maple, Anytown NC
* zip => 12345
*/ */
static VALUE static VALUE
@ -987,10 +996,16 @@ inspect_struct(VALUE s, VALUE dummy, int recur)
/* /*
* call-seq: * call-seq:
* struct.to_s -> string * inspect -> string
* struct.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 static VALUE
@ -1001,14 +1016,17 @@ rb_struct_inspect(VALUE s)
/* /*
* call-seq: * call-seq:
* struct.to_a -> array * to_a -> array
* struct.values -> array
* *
* Returns the values for this struct as an Array. * Returns the values in +self+ as an array:
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.to_a[1] #=> "123 Maple, Anytown NC" * 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 static VALUE
@ -1019,19 +1037,25 @@ rb_struct_to_a(VALUE s)
/* /*
* call-seq: * call-seq:
* struct.to_h -> hash * to_h -> hash
* struct.to_h {|name, value| block } -> 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) * Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.to_h[:address] #=> "123 Maple, Anytown NC" * h = joe.to_h
* joe.to_h{|name, value| [name.upcase, value.to_s.upcase]}[:ADDRESS] * h # => {:name=>"Joe Smith", :address=>"123 Maple, Anytown NC", :zip=>12345}
* #=> "123 MAPLE, ANYTOWN NC" *
* 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.
*
*/ */
static VALUE static VALUE
@ -1154,19 +1178,28 @@ invalid_struct_pos(VALUE s, VALUE idx)
/* /*
* call-seq: * call-seq:
* struct[member] -> object * struct[name] -> object
* struct[index] -> object * struct[n] -> object
* *
* Attribute Reference---Returns the value of the given struct +member+ or * Returns a value from +self+.
* the member at the given +index+. Raises NameError if the +member+ does *
* not exist and IndexError if the +index+ is out of range. * With symbol or string argument +name+ given, returns the value for the named member:
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * 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 VALUE
@ -1179,21 +1212,32 @@ rb_struct_aref(VALUE s, VALUE idx)
/* /*
* call-seq: * call-seq:
* struct[member] = obj -> obj * struct[name] = value -> value
* struct[index] = obj -> obj * struct[n] = value -> value
* *
* Attribute Assignment---Sets the value of the given struct +member+ or * Assigns a value to a member.
* the member at the given +index+. Raises NameError if the +member+ does not *
* exist and IndexError if the +index+ is out of range. * With symbol or string argument +name+ given, assigns the given +value+
* to the named member; returns +value+:
* *
* Customer = Struct.new(:name, :address, :zip) * Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * 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>
* *
* joe["name"] = "Luke" * Raises NameError if +name+ is not the name of a member.
* joe[:zip] = "90210" *
* 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>
*
* Raises IndexError if +n+ is out of range.
* *
* joe.name #=> "Luke"
* joe.zip #=> "90210"
*/ */
VALUE VALUE