zzak	2015-10-05 15:42:14 +0900 (Mon, 05 Oct 2015)

  New Revision: 52037

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=52037

  Log:
    * numeric.c: [DOC] Overview for Numeric class by Joe Corcoran
      This patch was created at ROSSConf Berlin 2015 [Bug #11555]

  Modified files:
    trunk/ChangeLog
    trunk/numeric.c
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 52036)
+++ ChangeLog	(revision 52037)
@@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Mon Oct  5 15:39:30 2015  Zachary Scott  <zzak@r...>
+
+	* numeric.c: [DOC] Overview for Numeric class by Joe Corcoran
+	  This patch was created at ROSSConf Berlin 2015 [Bug #11555]
+
 Mon Oct  5 15:34:56 2015  Nobuyoshi Nakada  <nobu@r...>
 
 	* proc.c (proc_new): link ep to calling block.
Index: numeric.c
===================================================================
--- numeric.c	(revision 52036)
+++ numeric.c	(revision 52037)
@@ -4071,7 +4071,75 @@ fix_even_p(VALUE num) https://github.com/ruby/ruby/blob/trunk/numeric.c#L4071
  */
 
 /*
- *  The top-level number class.
+ * Document-class: Numeric
+ *
+ * Numeric is the class from which all higher-level numeric classes should inherit.
+ * 
+ * Numeric allows instantiation of heap-allocated objects. Other core numeric classes such as
+ * Integer are implemented as immediates, which means that each Integer is a single immutable
+ * object which is always passed by value.
+ * 
+ *   a = 1
+ *   puts 1.object_id == a.object_id   #=> true
+ * 
+ * There can only ever be one instance of the integer +1+, for example. Ruby ensures this
+ * by preventing instantiation and duplication.
+ * 
+ *   Integer.new(1)   #=> NoMethodError: undefined method `new' for Integer:Class
+ *   1.dup            #=> TypeError: can't dup Fixnum
+ * 
+ * For this reason, Numeric should be used when defining other numeric classes.
+ * 
+ * Classes which inherit from Numeric must implement +coerce+, which returns a two-member
+ * Array containing an object that has been coerced into an instance of the new class
+ * and +self+ (see #coerce).
+ * 
+ * Inheriting classes should also implement arithmetic operator methods (<code>+</code>,
+ * <code>-</code>, <code>*</code> and <code>/</code>) and the <code><=></code> operator (see
+ * Comparable). These methods may rely on +coerce+ to ensure interoperability with
+ * instances of other numeric classes.
+ * 
+ *   class Tally < Numeric
+ *     def initialize(string)
+ *       @string = string
+ *     end
+ * 
+ *     def to_s
+ *       @string
+ *     end
+ * 
+ *     def to_i
+ *       @string.size
+ *     end
+ * 
+ *     def coerce(other)
+ *       [self.class.new('|' * other.to_i), self]
+ *     end
+ * 
+ *     def <=>(other)
+ *       to_i <=> other.to_i
+ *     end
+ * 
+ *     def +(other)
+ *       self.class.new('|' * (to_i + other.to_i))
+ *     end
+ * 
+ *     def -(other)
+ *       self.class.new('|' * (to_i - other.to_i))
+ *     end
+ * 
+ *     def *(other)
+ *       self.class.new('|' * (to_i * other.to_i))
+ *     end
+ * 
+ *     def /(other)
+ *       self.class.new('|' * (to_i / other.to_i))
+ *     end
+ *   end
+ * 
+ *   tally = Tally.new('||')
+ *   puts tally * 2            #=> "||||"
+ *   puts tally > 1            #=> true
  */
 void
 Init_Numeric(void)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/