ruby-changes:29188
From: drbrain <ko1@a...>
Date: Wed, 12 Jun 2013 07:17:22 +0900 (JST)
Subject: [ruby-changes:29188] drbrain:r41240 (trunk): * struct.c: Improve documentation: replace "instance variable" with
drbrain 2013-06-12 07:17:02 +0900 (Wed, 12 Jun 2013) New Revision: 41240 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=41240 Log: * struct.c: Improve documentation: replace "instance variable" with "member", recommend the use of a block to customize structs, note that member accessors are created, general cleanup. Modified files: trunk/ChangeLog trunk/struct.c Index: ChangeLog =================================================================== --- ChangeLog (revision 41239) +++ ChangeLog (revision 41240) @@ -1,3 +1,9 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Wed Jun 12 07:12:54 2013 Eric Hodel <drbrain@s...> + + * struct.c: Improve documentation: replace "instance variable" with + "member", recommend the use of a block to customize structs, note + that member accessors are created, general cleanup. + Wed Jun 12 06:35:01 2013 Tanaka Akira <akr@f...> * internal.h (INTEGER_PACK_NEGATIVE): Defined. Index: struct.c =================================================================== --- struct.c (revision 41239) +++ struct.c (revision 41240) @@ -73,8 +73,7 @@ rb_struct_s_members_m(VALUE klass) https://github.com/ruby/ruby/blob/trunk/struct.c#L73 * call-seq: * struct.members -> array * - * Returns an array of symbols representing the names of the instance - * variables. + * Returns the struct members as an array of symbols: * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -290,22 +289,29 @@ rb_struct_define(const char *name, ...) https://github.com/ruby/ruby/blob/trunk/struct.c#L289 /* * call-seq: - * Struct.new( [aString] [, aSym]+> ) -> StructClass - * Struct.new( [aString] [, aSym]+> ) {|StructClass| block } -> StructClass - * StructClass.new(arg, ...) -> obj - * StructClass[arg, ...] -> obj - * - * Creates a new class, named by <i>aString</i>, containing accessor - * methods for the given symbols. If the name <i>aString</i> is - * omitted, an anonymous structure class will be created. Otherwise, - * the name of this struct will appear as a constant in class - * <code>Struct</code>, so it must be unique for all - * <code>Struct</code>s in the system and should start with a capital - * letter. Assigning a structure class to a constant effectively gives - * the class the name of the constant. + * Struct.new([class_name] [, member_name]+>) -> StructClass + * Struct.new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass + * StructClass.new(value, ...) -> obj + * StructClass[value, ...] -> obj + * + * The first two forms are used to create a new Struct subclass +class_name+ + * that can contain a value for each +member_name+. This subclass can be + * used to create instances of the structure like any other Class. + * + * If the +class_name+ is omitted an anonymous structure class will be + * created. Otherwise, the name of this struct will appear as a constant in + * class Struct, so it must be unique for all Structs in the system and + * must start with a capital letter. Assigning a structure class to a + * constant also gives the class the name of the constant. + * + * # Create a structure with a name under Struct + * Struct.new("Customer", :name, :address) + * #=> Struct::Customer + * Struct::Customer.new("Dave", "123 Main") + * #=> #<struct Struct::Customer name="Dave", address="123 Main"> * - * If a block is given, it will be evaluated in the context of - * <i>StructClass</i>, passing <i>StructClass</i> as a parameter. + * If a block is given it will be evaluated in the context of + * +StructClass+, passing the created class as a parameter: * * Customer = Struct.new(:name, :address) do * def greeting @@ -314,23 +320,19 @@ rb_struct_define(const char *name, ...) https://github.com/ruby/ruby/blob/trunk/struct.c#L320 * end * Customer.new("Dave", "123 Main").greeting # => "Hello Dave!" * - * <code>Struct::new</code> returns a new <code>Class</code> object, - * which can then be used to create specific instances of the new - * structure. The number of actual parameters must be - * less than or equal to the number of attributes defined for this - * class; unset parameters default to <code>nil</code>. Passing too many - * parameters will raise an <code>ArgumentError</code>. - * - * The remaining methods listed in this section (class and instance) - * are defined for this generated class. - * - * # Create a structure with a name in Struct - * Struct.new("Customer", :name, :address) #=> Struct::Customer - * Struct::Customer.new("Dave", "123 Main") #=> #<struct Struct::Customer name="Dave", address="123 Main"> + * This is the recommended way to customize a struct. Subclassing an + * anonymous struct creates an extra anonymous class that will never be used. + * + * The last two forms create a new instance of a struct subclass. The number + * of +value+ parameters must be less than or equal to the number of + * attributes defined for the structure. Unset parameters default to +nil+. + * Passing too many parameters will raise an ArgumentError. * * # Create a structure named by its constant - * Customer = Struct.new(:name, :address) #=> Customer - * Customer.new("Dave", "123 Main") #=> #<struct Customer name="Dave", address="123 Main"> + * Customer = Struct.new(:name, :address) + * #=> Customer + * Customer.new("Dave", "123 Main") + * #=> #<struct Customer name="Dave", address="123 Main"> */ static VALUE @@ -465,16 +467,14 @@ rb_struct_size(VALUE s); https://github.com/ruby/ruby/blob/trunk/struct.c#L467 * struct.each {|obj| block } -> struct * struct.each -> an_enumerator * - * Calls <i>block</i> once for each instance variable, passing the - * value as a parameter. - * - * If no block is given, an enumerator is returned instead. + * Yields the value of each struct member in order. If no block is given an + * enumerator is returned. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe.each {|x| puts(x) } * - * <em>produces:</em> + * Produces: * * Joe Smith * 123 Maple, Anytown NC @@ -498,16 +498,14 @@ rb_struct_each(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L498 * struct.each_pair {|sym, obj| block } -> struct * struct.each_pair -> an_enumerator * - * Calls <i>block</i> once for each instance variable, passing the name - * (as a symbol) and the value as parameters. - * - * If no block is given, an enumerator is returned instead. + * Yields the name and value of each struct member in order. If no block is + * given an enumerator is returned. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) * joe.each_pair {|name, value| puts("#{name} => #{value}") } * - * <em>produces:</em> + * Produces: * * name => Joe Smith * address => 123 Maple, Anytown NC @@ -596,7 +594,7 @@ rb_struct_inspect(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L594 * struct.to_a -> array * struct.values -> array * - * Returns the values for this instance as an array. + * Returns the values for this struct as an Array. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -613,8 +611,7 @@ rb_struct_to_a(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L611 * call-seq: * struct.to_h -> hash * - * Returns the values for this instance as a hash with keys - * corresponding to the instance variable name. + * Returns a Hash containing the names and values for the struct's members. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -669,14 +666,12 @@ rb_struct_aref_id(VALUE s, ID id) https://github.com/ruby/ruby/blob/trunk/struct.c#L666 /* * call-seq: - * struct[symbol] -> anObject - * struct[fixnum] -> anObject + * struct[member] -> anObject + * struct[index] -> anObject * - * Attribute Reference---Returns the value of the instance variable - * named by <i>symbol</i>, or indexed (0..length-1) by - * <i>fixnum</i>. Will raise <code>NameError</code> if the named - * variable does not exist, or <code>IndexError</code> if the index is - * out of range. + * 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. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -742,14 +737,12 @@ rb_struct_aset_id(VALUE s, ID id, VALUE https://github.com/ruby/ruby/blob/trunk/struct.c#L737 /* * call-seq: - * struct[symbol] = obj -> obj - * struct[fixnum] = obj -> obj + * struct[name] = obj -> obj + * struct[index] = obj -> obj * - * Attribute Assignment---Assigns to the instance variable named by - * <i>symbol</i> or <i>fixnum</i> the value <i>obj</i> and - * returns it. Will raise a <code>NameError</code> if the named - * variable does not exist, or an <code>IndexError</code> if the index - * is out of range. + * Attribute Assignment---Sets the value of the given struct +member+ or + * the member at the given +index+. Raises NameError if the +name+ does not + * exist and IndexError if the +index+ is out of range. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -799,19 +792,17 @@ struct_entry(VALUE s, long n) https://github.com/ruby/ruby/blob/trunk/struct.c#L792 } /* - * call-seq: - * struct.values_at(selector,... ) -> an_array + * call-seq: + * struct.values_at(selector, ...) -> an_array + * + * Returns the struct member values for each +selector+ as an Array. A + * +selector+ may be either an Integer offset or a Range of offsets (as in + * Array#values_at). + * + * Customer = Struct.new(:name, :address, :zip) + * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) + * joe.values_at 0, 2 #=> ["Joe Smith", 12345] * - * Returns an array containing the elements in - * +self+ corresponding to the given selector(s). The selectors - * may be either integer indices or ranges. - * See also </code>.select<code>. - * - * a = %w{ a b c d e f } - * a.values_at(1, 3, 5) - * a.values_at(1, 3, 5, 7) - * a.values_at(-1, -3, -5, -7) - * a.values_at(1..3, 2...5) */ static VALUE @@ -825,10 +816,9 @@ rb_struct_values_at(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/struct.c#L816 * struct.select {|i| block } -> array * struct.select -> an_enumerator * - * Invokes the block passing in successive elements from - * <i>struct</i>, returning an array containing those elements - * for which the block returns a true value (equivalent to - * <code>Enumerable#select</code>). + * Yields each member value from the struct to the block and returns an Array + * containing the member values from the +struct+ for which the given block + * returns a true value (equivalent to Enumerable#select). * * Lots = Struct.new(:a, :b, :c, :d, :e, :f) * l = Lots.new(11, 22, 33, 44, 55, 66) @@ -871,12 +861,10 @@ recursive_equal(VALUE s, VALUE s2, int r https://github.com/ruby/ruby/blob/trunk/struct.c#L861 /* * call-seq: - * struct == other_struct -> true or false + * struct == other -> true or false * - * Equality---Returns <code>true</code> if <i>other_struct</i> is - * equal to this one: they must be of the same class as generated by - * <code>Struct::new</code>, and the values of all instance variables - * must be equal (according to <code>Object#==</code>). + * Equality---Returns +true+ if +other+ has the same struct subclass and has + * equal member values (according to Object#==). * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -923,7 +911,7 @@ recursive_hash(VALUE s, VALUE dummy, int https://github.com/ruby/ruby/blob/trunk/struct.c#L911 * call-seq: * struct.hash -> fixnum * - * Return a hash value based on this struct's contents. + * Returns a hash value based on this struct's contents (see Object#hash). */ static VALUE @@ -952,8 +940,9 @@ recursive_eql(VALUE s, VALUE s2, int rec https://github.com/ruby/ruby/blob/trunk/struct.c#L940 * call-seq: * struct.eql?(other) -> true or false * - * Two structures are equal if they are the same object, or if all their - * fields are equal (using <code>eql?</code>). + * Hash equality---+other+ and +struct+ refer to the same hash key if they + * have the same struct subclass and have equal member values (according to + * Object#eql?). */ static VALUE @@ -974,7 +963,7 @@ rb_struct_eql(VALUE s, VALUE s2) https://github.com/ruby/ruby/blob/trunk/struct.c#L963 * struct.length -> fixnum * struct.size -> fixnum * - * Returns the number of instance variables. + * Returns the number of struct members. * * Customer = Struct.new(:name, :address, :zip) * joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345) @@ -988,19 +977,29 @@ rb_struct_size(VALUE s) https://github.com/ruby/ruby/blob/trunk/struct.c#L977 } /* - * A <code>Struct</code> is a convenient way to bundle a number of - * attributes together, using accessor methods, without having to write - * an explicit class. - * - * The <code>Struct</code> class is a generator of specific classes, - * each one of which is defined to hold a set of variables and their - * accessors. In these examples, we'll call the generated class - * ``<i>Customer</i>Class,'' and we'll show an example instance of that - * class as ``<i>Customer</i>Inst.'' - * - * In the descriptions that follow, the parameter <i>symbol</i> refers - * to a symbol, which is either a quoted string or a - * <code>Symbol</code> (such as <code>:name</code>). + * A Struct is a convenient way to bundle a number of attributes together, + * using accessor methods, without having to write an explicit class. + * + * 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. + * + * Customer = Struct.new(:name, :address) do + * def greeting + * "Hello #{name}!" + * end + * end + * + * dave = Customer.new("Dave", "123 Main") + * dave.name #=> "Dave" + * dave.greeting #=> "Hello Dave!" + * + * See Struct::new for further examples of creating struct subclasses and + * instances. + * + * 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 Init_Struct(void) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/