kotovalexarian-likes-github/ruby--ruby
1
0
Fork 0
mirror of https://github.com/ruby/ruby.git synced 2022-11-09 12:17:21 -05:00
Code Releases Activity

RDoc Struct and random

Browse source 
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@5340 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
dave 2003-12-28 20:47:56 +00:00
parent f42c729a2e
commit 8d32798543
5 changed files with 282 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

4
ChangeLog
View file

@ -1,3 +1,7 @@
Mon Dec 29 05:05:51 2003 Dave Thomas <dave@wireless_3.local.thomases.com>
* struct.c, random: Add RDoc comments
Mon Dec 29 02:25:00 2003 Gavin Sinclair <gsinclair@soyabean.com.au>
* lib/optparse.rb: Improved documentation.

4
lib/rdoc/parsers/parse_c.rb
View file

@ -262,7 +262,9 @@ module RDoc
|type, var_name, meth_name, meth_body, param_count, source_file|
#"
next if meth_name == "initialize_copy"
next if var_name == "ruby_top_self"
# Ignore top-object and weird struct.c dynamic stuff
next if var_name == "ruby_top_self" || var_name == "nstr"
var_name = "rb_cObject" if var_name == "rb_mKernel"
handle_method(type, var_name, meth_name,

2
object.c
View file

@ -729,7 +729,7 @@ rb_obj_frozen_p(obj)
/*
* Document-class: NillClass
* Document-class: NilClass
*
* The class of the singleton object <code>nil</code>.
*/

34
random.c
View file

@ -172,6 +172,20 @@ random_seed()
return tv.tv_sec ^ tv.tv_usec ^ getpid() ^ n++;
}
/*
* call-seq:
* srand(number=0) => old_seed
*
* Seeds the pseudorandom number generator to the value of
* <i>number</i>.<code>to_i.abs</code>. If <i>number</i> is omitted
* or zero, seeds the generator using a combination of the time, the
* process id, and a sequence number. (This is also the behavior if
* <code>Kernel::rand</code> is called without previously calling
* <code>srand</code>, but without the sequence.) By setting the seed
* to a known value, scripts can be made deterministic during testing.
* The previous seed value is returned. Also see <code>Kernel::rand</code>.
*/
static VALUE
rb_f_srand(argc, argv, obj)
int argc;
@ -193,6 +207,26 @@ rb_f_srand(argc, argv, obj)
return ULONG2NUM(old);
}
/*
* call-seq:
* rand(max=0) => number
*
* Converts <i>max</i> to an integer using max1 =
* max<code>.to_i.abs</code>. If the result is zero, returns a
* pseudorandom floating point number greater than or equal to 0.0 and
* less than 1.0. Otherwise, returns a pseudorandom integer greater
* than or equal to zero and less than max1. <code>Kernel::srand</code>
* may be used to ensure repeatable sequences of random numbers between
* different runs of the program. Ruby currently uses a modified
* Mersenne Twister with a period of 219937-1.
*
* srand 1234 #=> 0
* [ rand, rand ] #=> [0.191519450163469, 0.49766366626136]
* [ rand(10), rand(1000) ] #=> [6, 817]
* srand 1234 #=> 1234
* [ rand, rand ] #=> [0.191519450163469, 0.49766366626136]
*/
static VALUE
rb_f_rand(argc, argv, obj)
int argc;

240
struct.c
View file

@ -54,6 +54,18 @@ rb_struct_s_members(obj)
return ary;
}
/*
* call-seq:
* struct.members => array
*
* Returns an array of strings representing the names of the instance
* variables.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.members #=> ["name", "address", "zip"]
*/
static VALUE
rb_struct_members(obj)
VALUE obj;
@ -223,6 +235,40 @@ rb_struct_define(name, va_alist)
return make_struct(nm, ary, rb_cStruct);
}
/*
* call-seq:
* Struct.new( [aString] [, aSym]+> ) => 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.
*
* <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 \nil{}. Passing too many
* parameters will raise an \E{ArgumentError}.
*
* 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::Customer name="Dave", address="123 Main">
*
* # Create a structure named by its constant
* Customer = Struct.new(:name, :address) #=> Customer
* Customer.new("Dave", "123 Main") #=> #<Customer name="Dave", address="123 Main">
*/
static VALUE
rb_struct_s_def(argc, argv, klass)
int argc;
@ -249,6 +295,9 @@ rb_struct_s_def(argc, argv, klass)
return st;
}
/*
*/
static VALUE
rb_struct_initialize(self, values)
VALUE self, values;
@ -322,6 +371,24 @@ rb_struct_new(klass, va_alist)
return rb_class_new_instance(size, mem, klass);
}
/*
* call-seq:
* struct.each {|obj| block } => struct
*
* Calls <i>block</i> once for each instance variable, passing the
* value as a parameter.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.each {|x| puts(x) }
*
* <em>produces:</em>
*
* Joe Smith
* 123 Maple, Anytown NC
* 12345
*/
static VALUE
rb_struct_each(s)
VALUE s;
@ -334,6 +401,24 @@ rb_struct_each(s)
return s;
}
/*
* call-seq:
* struct.each_pair {|sym, obj| block } => struct
*
* Calls <i>block</i> once for each instance variable, passing the name
* (as a symbol) and the value as parameters.
*
* 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>
*
* name => Joe Smith
* address => 123 Maple, Anytown NC
* zip => 12345
*/
static VALUE
rb_struct_each_pair(s)
VALUE s;
@ -387,6 +472,14 @@ inspect_struct(s)
return str;
}
/*
* call-seq:
* struct.to_s => string
* struct.inspect => string
*
* Describe the contents of this struct in a string.
*/
static VALUE
rb_struct_inspect(s)
VALUE s;
@ -402,6 +495,18 @@ rb_struct_inspect(s)
return rb_protect_inspect(inspect_struct, s, 0);
}
/*
* call-seq:
* struct.to_a => array
* struct.values => array
*
* Returns the values for this instance as an array.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.to_a[1] #=> "123 Maple, Anytown NC"
*/
static VALUE
rb_struct_to_a(s)
VALUE s;
@ -448,6 +553,25 @@ rb_struct_aref_id(s, id)
return Qnil; /* not reached */
}
/*
* call-seq:
* struct[symbol] => anObject
* struct[fixnum] => 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.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
*
* joe["name"] #=> "Joe Smith"
* joe[:name] #=> "Joe Smith"
* joe[0] #=> "Joe Smith"
*/
VALUE
rb_struct_aref(s, idx)
VALUE s, idx;
@ -493,6 +617,27 @@ rb_struct_aset_id(s, id, val)
rb_name_error(id, "no member '%s' in struct", rb_id2name(id));
}
/*
* call-seq:
* struct[symbol] = obj => obj
* struct[fixnum] = 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.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
*
* joe["name"] = "Luke"
* joe[:zip] = "90210"
*
* joe.name #=> "Luke"
* joe.zip #=> "90210"
*/
VALUE
rb_struct_aset(s, idx, val)
VALUE s, idx, val;
@ -526,6 +671,22 @@ struct_entry(s, n)
return rb_struct_aref(s, LONG2NUM(n));
}
/*
* 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>.
*
* 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
rb_struct_values_at(argc, argv, s)
int argc;
@ -535,6 +696,26 @@ rb_struct_values_at(argc, argv, s)
return rb_values_at(s, RSTRUCT(s)->len, argc, argv, struct_entry);
}
/*
* call-seq:
* struct.select(fixnum, ... ) => array
* struct.select {|i| block } => array
*
* The first form returns an array containing the elements in
* <i>struct</i> corresponding to the given indices. The second
* form 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>).
*
* Lots = Struct.new(:a, :b, :c, :d, :e, :f)
* l = Lots.new(11, 22, 33, 44, 55, 66)
* l.select(1, 3, 5) #=> [22, 44, 66]
* l.select(0, 2, 4) #=> [11, 33, 55]
* l.select(-1, -3, -5) #=> [66, 44, 22]
* l.select {|v| (v % 2).zero? } #=> [22, 44, 66]
*/
static VALUE
rb_struct_select(argc, argv, s)
int argc;
@ -557,6 +738,23 @@ rb_struct_select(argc, argv, s)
return result;
}
/*
* call-seq:
* struct == other_struct => 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>).
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joejr = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* jane = Customer.new("Jane Doe", "456 Elm, Anytown NC", 12345)
* joe == joejr #=> true
* joe == jane #=> false
*/
static VALUE
rb_struct_equal(s, s2)
VALUE s, s2;
@ -576,6 +774,13 @@ rb_struct_equal(s, s2)
return Qtrue;
}
/*
* call-seq:
* struct.hash => fixnum
*
* Return a hash value based on this struct's contents.
*/
static VALUE
rb_struct_hash(s)
VALUE s;
@ -592,6 +797,14 @@ rb_struct_hash(s)
return LONG2FIX(h);
}
/*
* code-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>).
*/
static VALUE
rb_struct_eql(s, s2)
VALUE s, s2;
@ -611,6 +824,18 @@ rb_struct_eql(s, s2)
return Qtrue;
}
/*
* call-seq:
* struct.length => fixnum
* struct.size => fixnum
*
* Returns the number of instance variables.
*
* Customer = Struct.new(:name, :address, :zip)
* joe = Customer.new("Joe Smith", "123 Maple, Anytown NC", 12345)
* joe.length #=> 3
*/
static VALUE
rb_struct_size(s)
VALUE s;
@ -618,6 +843,21 @@ rb_struct_size(s)
return LONG2FIX(RSTRUCT(s)->len);
}
/*
* 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>).
*/
void
Init_Struct()
{