summaryrefslogtreecommitdiff
path: root/struct.c
diff options
context:
space:
mode:
authordave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 20:47:56 +0000
committerdave <dave@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2003-12-28 20:47:56 +0000
commit6cd63a70f6ecf416485261ee93c25c5f98879566 (patch)
treeeec9f1fc88d2ac95e3e40b9f3d10d0cc786d990c /struct.c
parent9f5554aa5c341c259920afd01f745406af8ab270 (diff)
RDoc Struct and random
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_1_8@5340 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'struct.c')
-rw-r--r--struct.c240
1 files changed, 240 insertions, 0 deletions
diff --git a/struct.c b/struct.c
index 73a7f5aeea..9ad30460ff 100644
--- a/struct.c
+++ b/struct.c
@@ -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()
{