diff options
author | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-28 20:47:56 +0000 |
---|---|---|
committer | dave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2003-12-28 20:47:56 +0000 |
commit | 6cd63a70f6ecf416485261ee93c25c5f98879566 (patch) | |
tree | eec9f1fc88d2ac95e3e40b9f3d10d0cc786d990c | |
parent | 9f5554aa5c341c259920afd01f745406af8ab270 (diff) | |
download | ruby-6cd63a70f6ecf416485261ee93c25c5f98879566.tar.gz |
RDoc Struct and random
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5340 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
-rw-r--r-- | ChangeLog | 4 | ||||
-rw-r--r-- | lib/rdoc/parsers/parse_c.rb | 4 | ||||
-rw-r--r-- | object.c | 2 | ||||
-rw-r--r-- | random.c | 34 | ||||
-rw-r--r-- | struct.c | 240 |
5 files changed, 282 insertions, 2 deletions
@@ -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:20:54 2003 Dave Thomas <dave@wireless_3.local.thomases.com> * eval.c: Add RDoc for class Proc, Method, UnboundMethod diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb index b8296f569d..eb1083df24 100644 --- a/lib/rdoc/parsers/parse_c.rb +++ b/lib/rdoc/parsers/parse_c.rb @@ -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, @@ -729,7 +729,7 @@ rb_obj_frozen_p(obj) /* - * Document-class: NillClass + * Document-class: NilClass * * The class of the singleton object <code>nil</code>. */ @@ -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; @@ -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() { |