зеркало из https://github.com/github/ruby.git
Enhanced RDoc for Struct (#4895)
Revises introductory material. Adds section "What's Here". Adds previously missing documentation for method #deconstruct_keys.
This commit is contained in:
Родитель
1147136b8a
Коммит
2cf1014362
129
struct.c
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)
|
||||
|
|
Загрузка…
Ссылка в новой задаче