update doc.

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

1 files changed, 58 insertions, 22 deletions

diff --git a/time.c b/time.c
index d2a90d4aa2..6fe4f85dad 100644
--- a/time.c
+++ b/time.c
@@ -4297,8 +4297,23 @@ strftimev(const char *fmt, VALUE time)
  *     time.strftime( string ) -> string
  *
  *  Formats <i>time</i> according to the directives in the given format
- *  string. Any text not listed as a directive will be passed through
- *  to the output string.
+ *  string.
+ *  The directives begins with a percent (%) character.
+ *  Any text not listed as a directive will be passed through to the
+ *  output string.
+ *
+ *  The directive consists of a percent (%) character,
+ *  zero or more flags, optional precision and a conversion specifier.
+ *
+ *  Flags:
+ *    -  don't pad a numeric result string.
+ *    _  use spaces for padding.
+ *    0  use zeros for padding.
+ *    ^  upcase the result string.
+ *    #  change case.
+ *    :  use colons for %z.
+ *
+ *  The precision specifies the minimum width.
  *
  *  Format directives:
  *
@@ -4308,22 +4323,27 @@ strftimev(const char *fmt, VALUE time)
  *      %y - Year without a century (00..99)
  *      
  *      %m - Month of the year (01..12)
+ *              %_m  blank-padded ( 1..12)
+ *              %-m  no-padded (1..12)
  *      %B - The full month name (``January'')
+ *              %^B  uppercased (``JANUARY'')
  *      %b - The abbreviated month name (``Jan'')
+ *              %^b  uppercased (``JAN'')
  *      %h - Equivalent to %b
  *      
- *      %d - Day of the month (01..31)
+ *      %d - Day of the month, zero-padded (01..31)
+ *              %-d  no-padded (1..31)
  *      %e - Day of the month, blank-padded ( 1..31)
  *
  *      %j - Day of the year (001..366)
  *      
  *    Time (Hour, Minute, Second, Subsecond):
- *      %H - Hour of the day, 24-hour clock (00..23)
- *      %k - hour, 24-hour clock, blank-padded ( 0..23)
- *      %I - Hour of the day, 12-hour clock (01..12)
- *      %l - hour, 12-hour clock, blank-padded ( 0..12)
- *      %P - Meridian indicator (``am'' or ``pm'')
- *      %p - Meridian indicator (``AM'' or ``PM'')
+ *      %H - Hour of the day, 24-hour clock, zero-padded (00..23)
+ *      %k - Hour of the day, 24-hour clock, blank-padded ( 0..23)
+ *      %I - Hour of the day, 12-hour clock, zero-padded (01..12)
+ *      %l - Hour of the day, 12-hour clock, blank-padded ( 0..12)
+ *      %P - Meridian indicator, lowercase (``am'' or ``pm'')
+ *      %p - Meridian indicator, uppercase (``AM'' or ``PM'')
  *      
  *      %M - Minute of the hour (00..59)
  *      
@@ -4342,23 +4362,23 @@ strftimev(const char *fmt, VALUE time)
  *      %Z - Time zone name
  *      
  *    Weekday:
- *      %a - The abbreviated weekday name (``Sun'')
  *      %A - The full weekday name (``Sunday'')
+ *              %^A  uppercased (``SUNDAY'')
  *      %u - Day of the week (Monday is 1, 1..7)
  *      %w - Day of the week (Sunday is 0, 0..6)
  *      
  *    ISO 8601 week-based year:
- *      %G - The week-based year according to ISO 8601
- *      %g - The last 2 digits of the week-based year according to ISO 8601 (00..99)
- *      %V - Week number of year according to ISO 8601 (01..53)
+ *      %G - The week-based year
+ *      %g - The last 2 digits of the week-based year (00..99)
+ *      %V - Week number of the week-based year (01..53)
  *      
  *    Week number:
- *      %U - Week number of the current year,
- *              starting with the first Sunday as the first
- *              day of the first week (00..53)
- *      %W - Week number of the current year,
- *              starting with the first Monday as the first
- *              day of the first week (00..53)
+ *    %U - Week number of the current year,
+ *            starting with the first Sunday as the first
+ *            day of the first week (00..53)
+ *    %W - Week number of the current year,
+ *            starting with the first Monday as the first
+ *            day of the first week (00..53)
  *      
  *    Seconds since the Epoch:
  *      %s - Number of seconds since 1970-01-01 00:00:00 UTC.
@@ -4379,9 +4399,25 @@ strftimev(const char *fmt, VALUE time)
  *      %R - 24-hour time (%H:%M)
  *      %T - 24-hour time (%H:%M:%S)
  *
- *     t = Time.now                        #=> 2007-11-19 08:37:48 -0600
- *     t.strftime("Printed on %m/%d/%Y")   #=> "Printed on 11/19/2007"
- *     t.strftime("at %I:%M%p")            #=> "at 08:37AM"
+ *  Examples:
+ *
+ *    t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600
+ *    t.strftime("Printed on %m/%d/%Y")   #=> "Printed on 11/19/2007"
+ *    t.strftime("at %I:%M%p")            #=> "at 08:37AM"
+ *    
+ *    # Various ISO 8601 formats:
+ *    t.strftime("%Y%m%s")     #=> "20071119"       # Calendar date (basic format)
+ *    t.strftime("%F")         #=> "2007-11-19"     # Calendar date (extended format)
+ *    t.strftime("%Y%j")       #=> "2007323"        # Ordinal date (basic format)
+ *    t.strftime("%Y-%j")      #=> "2007-323"       # Ordinal date (extended format)
+ *    t.strftime("%GW%V%u")    #=> "2007W471"       # Week date (basic format)
+ *    t.strftime("%G-W%V-%u")  #=> "2007-W47-1"     # Week date (extended format)
+ *    t.strftime("%Y%m%dT%H%M%S%z")   #=> "20071119T083748-0600" # Complete representation (basic format)
+ *    t.strftime("%FT%T%:z")   #=> "2007-11-19T08:37:48-06:00" # Complete representation (extended format)
+ *    t.strftime("%FT%R")      #=> "2007-11-19T08:37" # Calendar date and local time (extended format)
+ *    t.strftime("%Y-%jT%RZ")  #=> "2007-323T08:37Z" # Ordinal date and UTC of day (extended format)
+ *    t.strftime("%G-W%V-%uT%R%:z") #=> "2007-W47-1T08:37-06:00" # Week date and local time and difference from UTC (extended format)
+ *
  */
 
 static VALUE