зеркало из https://github.com/github/ruby.git
* 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. git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@41240 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
drbrain
Родитель
0c9a719d77
Коммит
28d975a633
|
|
@ -1,3 +1,9 @@
|
|||
Wed Jun 12 07:12:54 2013 Eric Hodel <drbrain@segment7.net>
|
||||
|
||||
* 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@fsij.org>
|
||||
|
||||
* internal.h (INTEGER_PACK_NEGATIVE): Defined.
|
||||
|
|
|
|||
183
struct.c
183
struct.c
|
|
@ -73,8 +73,7 @@ rb_struct_s_members_m(VALUE klass)
|
|||
* 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, ...)
|
|||
|
||||
/*
|
||||
* call-seq:
|
||||
* Struct.new( [aString] [, aSym]+> ) -> StructClass
|
||||
* Struct.new( [aString] [, aSym]+> ) {|StructClass| block } -> StructClass
|
||||
* StructClass.new(arg, ...) -> obj
|
||||
* StructClass[arg, ...] -> obj
|
||||
* Struct.new([class_name] [, member_name]+>) -> StructClass
|
||||
* Struct.new([class_name] [, member_name]+>) {|StructClass| block } -> StructClass
|
||||
* StructClass.new(value, ...) -> obj
|
||||
* StructClass[value, ...] -> 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.
|
||||
* 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 a block is given, it will be evaluated in the context of
|
||||
* <i>StructClass</i>, passing <i>StructClass</i> as a parameter.
|
||||
* 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
|
||||
* +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, ...)
|
|||
* 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>.
|
||||
* This is the recommended way to customize a struct. Subclassing an
|
||||
* anonymous struct creates an extra anonymous class that will never be used.
|
||||
*
|
||||
* 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">
|
||||
* 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);
|
|||
* 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)
|
|||
* 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)
|
|||
* 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)
|
|||
* 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)
|
|||
|
||||
/*
|
||||
* 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 val)
|
|||
|
||||
/*
|
||||
* 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)
|
|||
}
|
||||
|
||||
/*
|
||||
* call-seq:
|
||||
* struct.values_at(selector,... ) -> an_array
|
||||
* call-seq:
|
||||
* struct.values_at(selector, ...) -> an_array
|
||||
*
|
||||
* 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>.
|
||||
* 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]
|
||||
*
|
||||
* 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 *argv, VALUE s)
|
|||
* 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 recur)
|
|||
|
||||
/*
|
||||
* 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 recur)
|
|||
* 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 recur)
|
|||
* 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)
|
|||
* 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)
|
|||
}
|
||||
|
||||
/*
|
||||
* 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.
|
||||
* A Struct 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.''
|
||||
* 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.
|
||||
*
|
||||
* 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>).
|
||||
* 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)
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче