update doc.

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

1 files changed, 68 insertions, 28 deletions

diff --git a/time.c b/time.c
index 6fe4f85dad..a448a20e26 100644
--- a/time.c
+++ b/time.c
@@ -4303,17 +4303,24 @@ strftimev(const char *fmt, VALUE time)
  *  output string.
  *
  *  The directive consists of a percent (%) character,
- *  zero or more flags, optional precision and a conversion specifier.
+ *  zero or more flags, optional minimum field width,
+ *  optional modifier and a conversion specifier
+ *  as follows.
+ *
+ *    %<flags><width><modifier><conversion>
  *
  *  Flags:
- *    -  don't pad a numeric result string.
+ *    -  don't pad a numerical output.
  *    _  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.
+ *  The minimum field width specifies the minimum width.
+ *
+ *  The modifier is "E" and "O".
+ *  It is ignored.
  *
  *  Format directives:
  *
@@ -4322,7 +4329,7 @@ strftimev(const char *fmt, VALUE time)
  *      %C - Century (20 in 2009)
  *      %y - Year without a century (00..99)
  *      
- *      %m - Month of the year (01..12)
+ *      %m - Month of the year, zero-padded (01..12)
  *              %_m  blank-padded ( 1..12)
  *              %-m  no-padded (1..12)
  *      %B - The full month name (``January'')
@@ -4341,7 +4348,7 @@ strftimev(const char *fmt, VALUE time)
  *      %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)
+ *      %l - Hour of the day, 12-hour clock, blank-padded ( 1..12)
  *      %P - Meridian indicator, lowercase (``am'' or ``pm'')
  *      %p - Meridian indicator, uppercase (``AM'' or ``PM'')
  *      
@@ -4359,7 +4366,7 @@ strftimev(const char *fmt, VALUE time)
  *      %z - Time zone as hour and minute offset from UTC (e.g. +0900)
  *              %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
  *              %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
- *      %Z - Time zone name
+ *      %Z - Time zone abbreviation name
  *      
  *    Weekday:
  *      %A - The full weekday name (``Sunday'')
@@ -4367,38 +4374,48 @@ strftimev(const char *fmt, VALUE time)
  *      %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:
+ *    ISO 8601 week-based year and week number:
+ *    The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
+ *    The days in the year before the first week are in the last week of
+ *    the previous year.
  *      %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)
+ *    The week 1 of YYYY starts with a Sunday or Monday (according to %U
+ *    or %W).  The days in the year before the first week are in week 0.
+ *      %U - Week number of the year.  The week starts with Sunday.  (00..53)
+ *      %W - Week number of the year.  The week starts with Monday.  (00..53)
  *      
  *    Seconds since the Epoch:
  *      %s - Number of seconds since 1970-01-01 00:00:00 UTC.
  *      
  *    Literal string:
- *      %n - Newline (\n)
+ *      %n - Newline character (\n)
  *      %t - Tab character (\t)
  *      %% - Literal ``%'' character
  *      
  *    Combination:
- *      %c - The preferred local date and time representation (%a %b %e %H:%M:%S %Y)
+ *      %c - date and time (%a %b %e %T %Y)
  *      %D - Date (%m/%d/%y)
  *      %F - The ISO 8601 date format (%Y-%m-%d)
  *      %v - VMS date (%e-%b-%Y)
- *      %x - Preferred representation for the date alone, no time (%m/%d/%y)
- *      %X - Preferred representation for the time alone, no date (%H:%M:%S)
+ *      %x - Same as %D
+ *      %X - Same as %T
  *      %r - 12-hour time (%I:%M:%S %p)
  *      %R - 24-hour time (%H:%M)
  *      %T - 24-hour time (%H:%M:%S)
  *
+ *  This method is similar to strftime() function defined in ISO C and POSIX.
+ *  Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z)
+ *  are locale dependent in the function.
+ *  However this method is locale independent since Ruby 1.9.
+ *  So, the result may differ even if a same format string is used in other
+ *  systems such as C.
+ *  It is good practice to avoid %x and %X c because there are corresponding
+ *  locale independent representations, %D and %T.
+ *
  *  Examples:
  *
  *    t = Time.new(2007,11,19,8,37,48,"-06:00") #=> 2007-11-19 08:37:48 -0600
@@ -4406,17 +4423,40 @@ strftimev(const char *fmt, VALUE time)
  *    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)
+ *    t.strftime("%Y%m%d")           #=> "20071119"       # Calendar date (basic format)
+ *    t.strftime("%F")               #=> "2007-11-19"     # Calendar date (extended format)
+ *    t.strftime("%Y-%m")            #=> "2007-11"        # Calendar date, reduced accuracy, specific month
+ *    t.strftime("%Y")               #=> "2007"           # Calendar date, reduced accuracy, specific year
+ *    t.strftime("%C")               #=> "20"             # Calendar date, reduced accuracy, specific century
+ *    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("%GW%V")            #=> "2007W47"        # Week date, reduced accuracy, specific week (basic format)
+ *    t.strftime("%G-W%V")           #=> "2007-W47"       # Week date, reduced accuracy, specific week (extended format)
+ *    t.strftime("%H%M%S")           #=> "083748"         # Local time (basic format)
+ *    t.strftime("%T")               #=> "08:37:48"       # Local time (extended format)
+ *    t.strftime("%H%M")             #=> "0837"           # Local time, reduced accuracy, specific minute (basic format)
+ *    t.strftime("%H:%M")            #=> "08:37"          # Local time, reduced accuracy, specific minute (extended format)
+ *    t.strftime("%H")               #=> "08"             # Local time, reduced accuracy, specific hour
+ *    t.strftime("%H%M%S,%L")        #=> "083748,000"     # Local time with decimal fraction, comma as decimal sign (basic format)
+ *    t.strftime("%T,%L")            #=> "08:37:48,000"   # Local time with decimal fraction, comma as decimal sign (extended format)
+ *    t.strftime("%H%M%S.%L")        #=> "083748.000"     # Local time with decimal fraction, full stop as decimal sign (basic format)
+ *    t.strftime("%T.%L")            #=> "08:37:48.000"   # Local time with decimal fraction, full stop as decimal sign (extended format)
+ *    t.strftime("%H%M%S%z")         #=> "083748-0600"    # Local time and the difference from UTC (basic format)
+ *    t.strftime("%T%:z")            #=> "08:37:48-06:00" # Local time and the difference from UTC (extended format)
+ *    t.strftime("%Y%m%dT%H%M%S%z")  #=> "20071119T083748-0600" # Date and time of day for calendar date (basic format)
+ *    t.strftime("%FT%T%:z")         #=> "2007-11-19T08:37:48-06:00" # Date and time of day for calendar date (extended format)
+ *    t.strftime("%Y%jT%H%M%S%z")    #=> "2007323T083748-0600" # Date and time of day for ordinal date (basic format)
+ *    t.strftime("%Y-%jT%T%:z")      #=> "2007-323T08:37:48-06:00" # Date and time of day for ordinal date (extended format)
+ *    t.strftime("%GW%V%uT%H%M%S%z") #=> "2007W471T083748-0600" # Date and time of day for week date (basic format)
+ *    t.strftime("%G-W%V-%uT%T%:z")  #=> "2007-W47-1T08:37:48-06:00" # Date and time of day for week date (extended format)
+ *    t.strftime("%Y%m%dT%H%M")      #=> "20071119T0837" # Calendar date and local time (basic format)
+ *    t.strftime("%FT%R")            #=> "2007-11-19T08:37" # Calendar date and local time (extended format)
+ *    t.strftime("%Y%jT%H%MZ")       #=> "2007323T0837Z" # Ordinal date and UTC of day (basic format)
+ *    t.strftime("%Y-%jT%RZ")        #=> "2007-323T08:37Z" # Ordinal date and UTC of day (extended format)
+ *    t.strftime("%GW%V%uT%H%M%z")   #=> "2007W471T0837-0600" # Week date and local time and difference from UTC (basic 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)
  *
  */