Revises introductory material.
    Adds section "What's Here".
    Adds previously missing documentation for method #deconstruct_keys.
This commit is contained in:
Burdette Lamar 2021-09-27 18:17:47 -05:00 коммит произвёл GitHub
Родитель 1147136b8a
Коммит 2cf1014362
Не найден ключ, соответствующий данной подписи
Идентификатор ключа GPG: 4AEE18F83AFDEB23
1 изменённых файлов: 111 добавлений и 18 удалений

129
struct.c
Просмотреть файл

@ -1076,6 +1076,23 @@ rb_struct_to_h(VALUE s)
return h;
}
/*
* call-seq:
* deconstruct_keys(array_of_names) -> hash
*
* Returns a hash of the name/value pairs for the given member names.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* h = joe.deconstruct_keys([:zip, :address])
* h # => {:zip=>12345, :address=>"123 Maple, Anytown NC"}
*
* Returns all names and values if +array_of_names+ is +nil+:
*
* h = joe.deconstruct_keys(nil)
* h # => {:name=>"Joseph Smith, Jr.", :address=>"123 Maple, Anytown NC", :zip=>12345}
*
*/
static VALUE
rb_struct_deconstruct_keys(VALUE s, VALUE keys)
{
@ -1544,29 +1561,105 @@ rb_struct_dig(int argc, VALUE *argv, VALUE self)
/*
* Document-class: Struct
*
* A Struct is a convenient way to bundle a number of attributes together,
* using accessor methods, without having to write an explicit class.
* \Class \Struct provides a convenient way to create a simple class
* that can store and fetch values.
*
* The 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.
* This example creates a subclass of +Struct+, <tt>Struct::Customer</tt>;
* 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(:name, :address) do
* def greeting
* "Hello #{name}!"
* end
* end
* Customer = Struct.new('Customer', :name, :address, :zip)
* Customer.name # => "Struct::Customer"
* Customer.class # => Class
* Customer.superclass # => Struct
*
* dave = Customer.new("Dave", "123 Main")
* dave.name #=> "Dave"
* dave.greeting #=> "Hello Dave!"
* Corresponding to each member are two methods, a writer and a reader,
* that store and fetch values:
*
* See Struct::new for further examples of creating struct subclasses and
* instances.
* 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 <tt>::new</tt>:
*
* 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 <tt>==</tt> to compare member values.
* #eql?:: Returns whether a given object is equal to +self+,
* using <tt>eql?</tt> 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+.
*
* In the method descriptions that follow, a "member" parameter refers to a
* struct member which is either a quoted string (<code>"name"</code>) or a
* Symbol (<code>:name</code>).
*/
void
InitVM_Struct(void)