From 2cf101436202c72278926a9d2593f9c26b8e83ce Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Mon, 27 Sep 2021 18:17:47 -0500 Subject: Enhanced RDoc for Struct (#4895) Revises introductory material. Adds section "What's Here". Adds previously missing documentation for method #deconstruct_keys. --- struct.c | 129 ++++++++++++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 111 insertions(+), 18 deletions(-) (limited to 'struct.c') diff --git a/struct.c b/struct.c index 3bc2671e60..5aa70edf24 100644 --- a/struct.c +++ b/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. + * + * 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 # => # + * + * 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. * - * 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. + * === Methods for Iterating * - * Customer = Struct.new(:name, :address) do - * def greeting - * "Hello #{name}!" - * end - * end + * #each:: Calls a given block with each member name. + * #each_pair:: Calls a given block with each member name/value pair. * - * dave = Customer.new("Dave", "123 Main") - * dave.name #=> "Dave" - * dave.greeting #=> "Hello Dave!" + * === Methods for Converting * - * See Struct::new for further examples of creating struct subclasses and - * instances. + * #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 ("name") or a - * Symbol (:name). */ void InitVM_Struct(void) -- cgit v1.2.3