* string.c (scan_once): wrong condition to use mbclen2().

  [ruby-dev:27535]

* time.c (time_sunday): added predicate methods for the days of the
  week.  [ruby-list:41340]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@9472 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

5 files changed, 445 insertions, 74 deletions

diff --git a/lib/.document b/lib/.document
index 8abcd21d93..98dadba57f 100644
--- a/lib/.document
+++ b/lib/.document
@@ -26,6 +26,8 @@ net
 observer.rb
 optionparser.rb
 pathname.rb
+pstore.rb
+rational.rb
 resolv.rb
 set.rb
 shellwords.rb
diff --git a/lib/irb.rb b/lib/irb.rb
index 5cacbf859e..1fb4397e68 100644
--- a/lib/irb.rb
+++ b/lib/irb.rb
@@ -119,7 +119,7 @@ module IRB
 	end
 	if @context.auto_indent_mode
 	  unless ltype
-	    ind = prompt(@context.prompt_i, ltype, indent, line_no).size + 
+            ind = prompt(@context.prompt_i, ltype, indent, line_no)[/.*\z/].size +
 	      indent * 2 - p.size
 	    ind += 2 if continue
 	    @context.io.prompt = p + " " * ind if ind > 0
diff --git a/lib/matrix.rb b/lib/matrix.rb
index c62acdf9aa..8058addb91 100644
--- a/lib/matrix.rb
+++ b/lib/matrix.rb
@@ -246,7 +246,7 @@ class Matrix
   # use to general users.
   #
   def initialize(init_method, *argv)
-    self.send(init_method, *argv)
+    self.funcall(init_method, *argv)
   end
   
   def init_rows(rows, copy)
diff --git a/lib/pstore.rb b/lib/pstore.rb
index 51cef6e134..3f60b593f4 100644
--- a/lib/pstore.rb
+++ b/lib/pstore.rb
@@ -1,24 +1,91 @@
+# = PStore -- Transactional File Storage for Ruby Objects
 #
-# How to use:
+# pstore.rb -
+#   by unknown
+#   documentation by Kev Jackson and James Edward Gray II
 #
-# db = PStore.new("/tmp/foo")
-# db.transaction do
-#   p db.roots
-#   ary = db["root"] = [1,2,3,4]
-#   ary[0] = [1,1.5]
-# end
+# See PStore for documentation.
 
-# db.transaction do
-#   p db["root"]
-# end
 
 require "fileutils"
 require "digest/md5"
 
+#
+# PStore implements a file based persistance mechanism based on a Hash.  User
+# code can store hierarchies of Ruby objects (values) into the data store file
+# by name (keys).  An object hierarchy may be just a single object.  User code 
+# may later read values back from the data store or even update data, as needed.
+# 
+# The transactional behavior ensures that any changes succeed or fail together.
+# This can be used to ensure that the data store is not left in a transitory
+# state, where some values were upated but others were not.
+# 
+# Behind the scenes, Ruby objects are stored to the data store file with 
+# Marshal.  That carries the usual limitations.  Proc objects cannot be 
+# marshalled, for example.
+#
+# == Usage example:
+# 
+#  require "pstore"
+#  
+#  # a mock wiki object...
+#  class WikiPage
+#    def initialize( page_name, author, contents )
+#      @page_name = page_name
+#      @revisions = Array.new
+#      
+#      add_revision(author, contents)
+#    end
+#    
+#    attr_reader :page_name
+#    
+#    def add_revision( author, contents )
+#      @revisions << { :created  => Time.now,
+#                      :author   => author,
+#                      :contents => contents }
+#    end
+#    
+#    def wiki_page_references
+#      [@page_name] + @revisions.last[:contents].scan(/\b(?:[A-Z]+[a-z]+){2,}/)
+#    end
+#    
+#    # ...
+#  end
+#  
+#  # create a new page...
+#  home_page = WikiPage.new( "HomePage", "James Edward Gray II",
+#                            "A page about the JoysOfDocumentation..." )
+#  
+#  # then we want to update page data and the index together, or not at all...
+#  wiki = PStore.new("wiki_pages.pstore")
+#  wiki.transaction do  # begin transaction; do all of this or none of it
+#    # store page...
+#    wiki[home_page.page_name] = home_page
+#    # ensure that an index has been created...
+#    wiki[:wiki_index] ||= Array.new
+#    # update wiki index...
+#    wiki[:wiki_index].push(*home_page.wiki_page_references)
+#  end                   # commit changes to wiki data store file
+#  
+#  ### Some time later... ###
+#  
+#  # read wiki data...
+#  wiki.transaction(true) do  # begin read-only transaction, no changes allowed
+#    wiki.roots.each do |data_root_name|
+#      p data_root_name
+#      p wiki[data_root_name]
+#    end
+#  end
+#
 class PStore
+  # The error type thrown by all PStore methods.
   class Error < StandardError
   end
 
+  # 
+  # To construct a PStore object, pass in the _file_ path where you would like 
+  # the data to be stored.
+  # 
   def initialize(file)
     dir = File::dirname(file)
     unless File::directory? dir
@@ -32,19 +99,41 @@ class PStore
     @abort = false
   end
 
+  # Raises PStore::Error if the calling code is not in a PStore#transaction.
   def in_transaction
     raise PStore::Error, "not in transaction" unless @transaction
   end
+  # 
+  # Raises PStore::Error if the calling code is not in a PStore#transaction or
+  # if the code is in a read-only PStore#transaction.
+  # 
   def in_transaction_wr()
     in_transaction()
     raise PStore::Error, "in read-only transaction" if @rdonly
   end
   private :in_transaction, :in_transaction_wr
 
+  #
+  # Retrieves a value from the PStore file data, by _name_.  The hierarchy of 
+  # Ruby objects stored under that root _name_ will be returned.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def [](name)
     in_transaction
     @table[name]
   end
+  #
+  # This method is just like PStore#[], save that you may also provide a 
+  # _default_ value for the object.  In the event the specified _name_ is not 
+  # found in the data store, your _default_ will be returned instead.  If you do 
+  # not specify a default, PStore::Error will be raised if the object is not 
+  # found.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def fetch(name, default=PStore::Error)
     unless @table.key? name
       if default==PStore::Error
@@ -55,39 +144,138 @@ class PStore
     end
     self[name]
   end
+  #
+  # Stores an individual Ruby object or a hierarchy of Ruby objects in the data
+  # store file under the root _name_.  Assigning to a _name_ already in the data
+  # store clobbers the old data.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #  
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    # load some data into the store...
+  #    store[:single_object] = "My data..."
+  #    store[:obj_heirarchy] = { "Kev Jackson" => ["rational.rb", "pstore.rb"],
+  #                              "James Gray"  => ["erb.rb", "pstore.rb"] }
+  #  end                   # commit changes to data store file
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction and it cannot
+  # be read-only.  It will raise PStore::Error if called at any other time.
+  #
   def []=(name, value)
     in_transaction_wr()
     @table[name] = value
   end
+  #
+  # Removes an object hierarchy from the data store, by _name_.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction and it cannot
+  # be read-only.  It will raise PStore::Error if called at any other time.
+  #
   def delete(name)
     in_transaction_wr()
     @table.delete name
   end
 
+  #
+  # Returns the names of all object hierarchies currently in the store.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def roots
     in_transaction
     @table.keys
   end
+  #
+  # Returns true if the supplied _name_ is currently in the data store.
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def root?(name)
     in_transaction
     @table.key? name
   end
+  # Returns the path to the data store file.
   def path
     @filename
   end
 
+  #
+  # Ends the current PStore#transaction, committing any changes to the data
+  # store immediately.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #   
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    # load some data into the store...
+  #    store[:one] = 1
+  #    store[:two] = 2
+  #  
+  #    store.commit        # end transaction here, committing changes
+  #  
+  #    store[:three] = 3   # this change is never reached
+  #  end
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def commit
     in_transaction
     @abort = false
     throw :pstore_abort_transaction
   end
+  #
+  # Ends the current PStore#transaction, discarding any changes to the data
+  # store.
+  # 
+  # == Example:
+  # 
+  #  require "pstore"
+  #   
+  #  store = PStore.new("data_file.pstore")
+  #  store.transaction do  # begin transaction
+  #    store[:one] = 1     # this change is not applied, see below...
+  #    store[:two] = 2     # this change is not applied, see below...
+  #  
+  #    store.abort         # end transaction here, discard all changes
+  #  
+  #    store[:three] = 3   # this change is never reached
+  #  end
+  # 
+  # *WARNING*:  This method is only valid in a PStore#transaction.  It will
+  # raise PStore::Error if called at any other time.
+  #
   def abort
     in_transaction
     @abort = true
     throw :pstore_abort_transaction
   end
 
-  def transaction(read_only=false)
+  #
+  # Opens a new transaction for the data store.  Code executed inside a block
+  # passed to this method may read and write data to and from the data store 
+  # file.
+  # 
+  # At the end of the block, changes are committed to the data store
+  # automatically.  You may exit the transaction early with a call to either 
+  # PStore#commit or PStore#abort.  See those methods for details about how
+  # changes are handled.  Raising an uncaught Exception in the block is 
+  # equivalent to calling PStore#abort.
+  # 
+  # If _read_only_ is set to +true+, you will only be allowed to read from the
+  # data store during the transaction and any attempts to change the data will
+  # raise a PStore::Error.
+  # 
+  # Note that PStore does not support nested transactions.
+  #
+  def transaction(read_only=false)  # :yields:  pstore
     raise PStore::Error, "nested transaction" if @transaction
     begin
       @rdonly = read_only
@@ -155,19 +343,23 @@ class PStore
     value
   end
 
-  def dump(table)
+  # This method is just a wrapped around Marshal.dump.
+  def dump(table)  # :nodoc:
     Marshal::dump(table)
   end
 
-  def load(content)
+  # This method is just a wrapped around Marshal.load.
+  def load(content)  # :nodoc:
     Marshal::load(content)
   end
 
-  def load_file(file)
+  # This method is just a wrapped around Marshal.load.
+  def load_file(file)  # :nodoc:
     Marshal::load(file)
   end
 
   private
+  # Commits changes to the data store file.
   def commit_new(f)
     f.truncate(0)
     f.rewind
@@ -180,6 +372,8 @@ class PStore
   end
 end
 
+# :enddoc:
+
 if __FILE__ == $0
   db = PStore.new("/tmp/foo")
   db.transaction do
diff --git a/lib/rational.rb b/lib/rational.rb
index 2241004852..fd5bc95a34 100644
--- a/lib/rational.rb
+++ b/lib/rational.rb
@@ -1,41 +1,32 @@
 #
-#   rational.rb - 
-#   	$Release Version: 0.5 $
-#   	$Revision: 1.7 $
-#   	$Date: 1999/08/24 12:49:28 $
-#   	by Keiju ISHITSUKA(SHL Japan Inc.)
+#   rational.rb -
+#       $Release Version: 0.5 $
+#       $Revision: 1.7 $
+#       $Date: 1999/08/24 12:49:28 $
+#       by Keiju ISHITSUKA(SHL Japan Inc.)
 #
-# --
-#   Usage:
-#   class Rational < Numeric
-#      (include Comparable)
+# Documentation by Kevin Jackson and Gavin Sinclair.
+# 
+# When you <tt>require 'rational'</tt>, all interactions between numbers
+# potentially return a rational result.  For example:
 #
-#   Rational(a, b) --> a/b
+#   1.quo(2)              # -> 0.5
+#   require 'rational'
+#   1.quo(2)              # -> Rational(1,2)
+# 
+# See Rational for full documentation.
 #
-#   Rational::+
-#   Rational::-
-#   Rational::*
-#   Rational::/
-#   Rational::**
-#   Rational::%
-#   Rational::divmod
-#   Rational::abs
-#   Rational::<=>
-#   Rational::to_i
-#   Rational::to_f
-#   Rational::to_s
+
 #
-#   Integer::gcd
-#   Integer::lcm
-#   Integer::gcdlcm
-#   Integer::to_r
+# Creates a Rational number (i.e. a fraction).  +a+ and +b+ should be Integers:
+# 
+#   Rational(1,3)           # -> 1/3
 #
-#   Fixnum::**
-#   Fixnum::quo
-#   Bignum::**
-#   Bignum::quo
+# Note: trying to construct a Rational with floating point or real values
+# produces errors:
+#
+#   Rational(1.1, 2.3)      # -> NoMethodError
 #
-
 def Rational(a, b = 1)
   if a.kind_of?(Rational) && b == 1
     a
@@ -43,10 +34,39 @@ def Rational(a, b = 1)
     Rational.reduce(a, b)
   end
 end
-  
+
+#
+# Rational implements a rational class for numbers.
+#
+# <em>A rational number is a number that can be expressed as a fraction p/q
+# where p and q are integers and q != 0.  A rational number p/q is said to have
+# numerator p and denominator q.  Numbers that are not rational are called
+# irrational numbers.</em> (http://mathworld.wolfram.com/RationalNumber.html)
+#
+# To create a Rational Number:
+#   Rational(a,b)             # -> a/b
+#   Rational.new!(a,b)        # -> a/b
+#
+# Examples:
+#   Rational(5,6)             # -> 5/6
+#   Rational(5)               # -> 5/1
+# 
+# Rational numbers are reduced to their lowest terms:
+#   Rational(6,10)            # -> 3/5
+#
+# But not if you use the unusual method "new!":
+#   Rational.new!(6,10)       # -> 6/10
+#
+# Division by zero is obviously not allowed:
+#   Rational(3,0)             # -> ZeroDivisionError
+#
 class Rational < Numeric
   @RCS_ID='-$Id: rational.rb,v 1.7 1999/08/24 12:49:28 keiju Exp keiju $-'
 
+  #
+  # Reduces the given numerator and denominator to their lowest terms.  Use
+  # Rational() instead.
+  #
   def Rational.reduce(num, den = 1)
     raise ZeroDivisionError, "denominator is zero" if den == 0
 
@@ -63,13 +83,21 @@ class Rational < Numeric
       new!(num, den)
     end
   end
-  
+
+  #
+  # Implements the constructor.  This method does not reduce to lowest terms or
+  # check for division by zero.  Therefore #Rational() should be preferred in
+  # normal use.
+  #
   def Rational.new!(num, den = 1)
     new(num, den)
   end
 
   private_class_method :new
 
+  #
+  # This method is actually private.
+  #
   def initialize(num, den)
     if den < 0
       num = -num
@@ -83,7 +111,15 @@ class Rational < Numeric
       @denominator = den.to_i
     end
   end
-  
+
+  #
+  # Returns the addition of this value and +a+.
+  #
+  # Examples:
+  #   r = Rational(3,4)      # -> Rational(3,4)
+  #   r + 1                  # -> Rational(7,4)
+  #   r + 0.5                # -> 1.25
+  #
   def + (a)
     if a.kind_of?(Rational)
       num = @numerator * a.denominator
@@ -98,7 +134,16 @@ class Rational < Numeric
       x + y
     end
   end
-  
+
+  #
+  # Returns the difference of this value and +a+.
+  # subtracted.
+  #
+  # Examples:
+  #   r = Rational(3,4)    # -> Rational(3,4)
+  #   r - 1                # -> Rational(-1,4)
+  #   r - 0.5              # -> 0.25
+  #
   def - (a)
     if a.kind_of?(Rational)
       num = @numerator * a.denominator
@@ -113,7 +158,17 @@ class Rational < Numeric
       x - y
     end
   end
-  
+
+  #
+  # Returns the product of this value and +a+.
+  #
+  # Examples:
+  #   r = Rational(3,4)    # -> Rational(3,4)
+  #   r * 2                # -> Rational(3,2)
+  #   r * 4                # -> Rational(3,1)
+  #   r * 0.5              # -> 0.375
+  #   r * Rational(1,2)    # -> Rational(3,8)
+  #
   def * (a)
     if a.kind_of?(Rational)
       num = @numerator * a.numerator
@@ -128,7 +183,14 @@ class Rational < Numeric
       x * y
     end
   end
-  
+
+  #
+  # Returns the quotient of this value and +a+.
+  #   r = Rational(3,4)    # -> Rational(3,4)
+  #   r / 2                # -> Rational(3,8)
+  #   r / 2.0              # -> 0.375
+  #   r / Rational(1,2)    # -> Rational(3,2)
+  #
   def / (a)
     if a.kind_of?(Rational)
       num = @numerator * a.denominator
@@ -144,7 +206,16 @@ class Rational < Numeric
       x / y
     end
   end
-  
+
+  #
+  # Returns this value raised to the given power.
+  #
+  # Examples:
+  #   r = Rational(3,4)    # -> Rational(3,4)
+  #   r ** 2               # -> Rational(9,16)
+  #   r ** 2.0             # -> 0.5625
+  #   r ** Rational(1,2)   # -> 0.866025403784439
+  #
   def ** (other)
     if other.kind_of?(Rational)
       Float(self) ** other
@@ -167,17 +238,37 @@ class Rational < Numeric
       x ** y
     end
   end
-  
+
+  #
+  # Returns the remainder when this value is divided by +other+.
+  #
+  # Examples:
+  #   r = Rational(7,4)    # -> Rational(7,4)
+  #   r % Rational(1,2)    # -> Rational(1,4)
+  #   r % 1                # -> Rational(3,4)
+  #   r % Rational(1,7)    # -> Rational(1,28)
+  #   r % 0.26             # -> 0.19
+  #
   def % (other)
     value = (self / other).to_i
     return self - other * value
   end
-  
+
+  #
+  # Returns the quotient _and_ remainder.
+  #
+  # Examples:
+  #   r = Rational(7,4)        # -> Rational(7,4)
+  #   r.divmod Rational(1,2)   # -> [3, Rational(1,4)]
+  #
   def divmod(other)
     value = (self / other).to_i
     return value, self - other * value
   end
-  
+
+  #
+  # Returns the absolute value.
+  #
   def abs
     if @numerator > 0
       Rational.new!(@numerator, @denominator)
@@ -186,6 +277,15 @@ class Rational < Numeric
     end
   end
 
+  #
+  # Returns +true+ iff this value is numerically equal to +other+.
+  #
+  # But beware:
+  #   Rational(1,2) == Rational(4,8)          # -> true
+  #   Rational(1,2) == Rational.new!(4,8)     # -> false
+  #
+  # Don't use Rational.new!
+  #
   def == (other)
     if other.kind_of?(Rational)
       @numerator == other.numerator and @denominator == other.denominator
@@ -198,6 +298,9 @@ class Rational < Numeric
     end
   end
 
+  #
+  # Standard comparison operator.
+  #
   def <=> (other)
     if other.kind_of?(Rational)
       num = @numerator * other.denominator
@@ -232,14 +335,35 @@ class Rational < Numeric
     end
   end
 
+  #
+  # Converts the rational to an Integer.  Not the _nearest_ integer, the
+  # truncated integer.  Study the following example carefully:
+  #   Rational(+7,4).to_i             # -> 1
+  #   Rational(-7,4).to_i             # -> -2
+  #   (-1.75).to_i                    # -> -1
+  #
+  # In other words:
+  #   Rational(-7,4) == -1.75                 # -> true
+  #   Rational(-7,4).to_i == (-1.75).to_i     # false
+  #
   def to_i
     Integer(@numerator.div(@denominator))
   end
-  
+
+  #
+  # Converts the rational to a Float.
+  #
   def to_f
     @numerator.to_f/@denominator.to_f
   end
-  
+
+  #
+  # Returns a string representation of the rational number.
+  #
+  # Example:
+  #   Rational(3,4).to_s          #  "3/4"
+  #   Rational(8).to_s            #  "8"
+  #
   def to_s
     if @denominator == 1
       @numerator.to_s
@@ -247,38 +371,69 @@ class Rational < Numeric
       @numerator.to_s+"/"+@denominator.to_s
     end
   end
-  
+
+  #
+  # Returns +self+.
+  #
   def to_r
     self
   end
-  
+
+  #
+  # Returns a reconstructable string representation:
+  #
+  #   Rational(5,8).inspect     # -> "Rational(5, 8)"
+  #
   def inspect
     sprintf("Rational(%s, %s)", @numerator.inspect, @denominator.inspect)
   end
-  
+
+  #
+  # Returns a hash code for the object.
+  #
   def hash
     @numerator.hash ^ @denominator.hash
   end
-  
+
   attr :numerator
   attr :denominator
-  
+
   private :initialize
 end
 
 class Integer
+  #
+  # In an integer, the value _is_ the numerator of its rational equivalent.
+  # Therefore, this method returns +self+.
+  #
   def numerator
     self
   end
-  
+
+  #
+  # In an integer, the denominator is 1.  Therefore, this method returns 1.
+  #
   def denominator
     1
   end
-  
+
+  #
+  # Returns a Rational representation of this integer.
+  #
   def to_r
     Rational(self, 1)
   end
-  
+
+  #
+  # Returns the <em>greatest common denominator</em> of the two numbers (+self+
+  # and +n+).
+  #
+  # Examples:
+  #   72.gcd 168           # -> 24
+  #   19.gcd 36            # -> 1
+  #
+  # The result is positive, no matter the sign of the arguments.
+  #
   def gcd(n)
     m = self.abs
     n = n.abs
@@ -298,13 +453,13 @@ class Integer
     end
     m << b
   end
-  
+
   def gcd2(int)
     a = self.abs
     b = int.abs
-  
+
     a, b = b, a if a < b
-  
+
     while b != 0
       void, a = a.divmod(b)
       a, b = b, a
@@ -312,6 +467,14 @@ class Integer
     return a
   end
 
+  #
+  # Returns the <em>lowest common multiple</em> (LCM) of the two arguments
+  # (+self+ and +other+).
+  #
+  # Examples:
+  #   6.lcm 7        # -> 42
+  #   6.lcm 9        # -> 18
+  #
   def lcm(other)
     if self.zero? or other.zero?
       0
@@ -320,6 +483,14 @@ class Integer
     end
   end
   
+  #
+  # Returns the GCD _and_ the LCM (see #gcd and #lcm) of the two arguments
+  # (+self+ and +other+).  This is more efficient than calculating them
+  # separately.
+  #
+  # Example:
+  #   6.gcdlcm 9     # -> [3, 18]
+  #
   def gcdlcm(other)
     gcd = self.gcd(other)
     if self.zero? or other.zero?
@@ -332,11 +503,13 @@ end
 
 class Fixnum
   undef quo
+  # If Rational is defined, returns a Rational number instead of a Fixnum.
   def quo(other)
     Rational.new!(self,1) / other
   end
   alias rdiv quo
-  
+
+  # Returns a Rational number if the result is in fact rational (i.e. +other+ < 0).
   def rpower (other)
     if other >= 0
       self.power!(other)
@@ -346,7 +519,7 @@ class Fixnum
   end
 
   unless defined? 1.power!
-    alias power! ** 
+    alias power! **
     alias ** rpower
   end
 end
@@ -357,11 +530,13 @@ class Bignum
   end
 
   undef quo
+  # If Rational is defined, returns a Rational number instead of a Bignum.
   def quo(other)
     Rational.new!(self,1) / other
   end
   alias rdiv quo
-  
+
+  # Returns a Rational number if the result is in fact rational (i.e. +other+ < 0).
   def rpower (other)
     if other >= 0
       self.power!(other)
@@ -369,7 +544,7 @@ class Bignum
       Rational.new!(self, 1)**other
     end
   end
-  
+
   unless defined? Complex
     alias ** rpower
   end