Project

General

Profile

Bug #7326 ยป time_docs_2.diff

bt (Bernd Homuth), 11/18/2012 08:21 PM

View differences:

time.c
1399 1399
static struct tm *localtime_with_gmtoff_zone(const time_t *t, struct tm *result, long *gmtoff, const char **zone);
1400 1400

  
1401 1401
/*
1402
 * The idea is come from Perl:
1402
 * The idea is borrowed from Perl:
1403 1403
 * http://use.perl.org/articles/08/02/07/197204.shtml
1404 1404
 *
1405
 * compat_common_month_table is generated by following program.
1406
 * This table finds the last month which start the same day of a week.
1407
 * The year 2037 is not used because
1405
 * compat_common_month_table is generated by the following program.
1406
 * This table finds the last month which starts at the same day of a week.
1407
 * The year 2037 is not used because:
1408 1408
 * http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=522949
1409 1409
 *
1410 1410
 *  #!/usr/bin/ruby
......
1502 1502
    VALUE timev;
1503 1503
    int y, wday;
1504 1504

  
1505
    /* The first DST is at 1916 in German.
1506
     * So we don't need to care DST before that. */
1505
    /* Daylight Saving Time was introduced in 1916.
1506
     * So we don't need to care about DST before that. */
1507 1507
    if (lt(vtm_utc->year, INT2FIX(1916))) {
1508 1508
        VALUE off = INT2FIX(0);
1509 1509
        int isdst = 0;
......
1537 1537
        return off;
1538 1538
    }
1539 1539

  
1540
    /* It is difficult to guess future. */
1540
    /* It is difficult to guess the future. */
1541 1541

  
1542 1542
    vtm2 = *vtm_utc;
1543 1543

  
......
1943 1943
/*
1944 1944
 *  Document-method: now
1945 1945
 *
1946
 *  Synonym for <code>Time.new</code>. Returns a +Time+ object
1946
 *  Alias for Time::new. Returns a Time object
1947 1947
 *  initialized to the current system time.
1948 1948
 */
1949 1949

  
......
2220 2220
 *     Time.new -> time
2221 2221
 *     Time.new(year, month=nil, day=nil, hour=nil, min=nil, sec=nil, utc_offset=nil) -> time
2222 2222
 *
2223
 *  Returns a <code>Time</code> object.
2223
 *  Returns a Time object.
2224 2224
 *
2225
 *  It is initialized to the current system time if no argument.
2226
 *  <b>Note:</b> The object created will be created using the
2227
 *  resolution available on your system clock, and so may include
2228
 *  fractional seconds.
2225
 *  It is initialized to the current system time if no argument is given.
2226
 *
2227
 *  *Note:* The new object will use the resolution available on your
2228
 *  system clock, and may include fractional seconds.
2229 2229
 *
2230 2230
 *  If one or more arguments specified, the time is initialized
2231 2231
 *  to the specified time.
2232 2232
 *  _sec_ may have fraction if it is a rational.
2233 2233
 *
2234 2234
 *  _utc_offset_ is the offset from UTC.
2235
 *  It is a string such as "+09:00" or a number of seconds such as 32400.
2235
 *  It can be a string such as "+09:00" or a number of seconds such as 32400.
2236 2236
 *
2237 2237
 *     a = Time.new      #=> 2007-11-19 07:50:02 -0600
2238 2238
 *     b = Time.new      #=> 2007-11-19 07:50:02 -0600
......
2505 2505
 *     Time.at(seconds_with_frac) -> time
2506 2506
 *     Time.at(seconds, microseconds_with_frac) -> time
2507 2507
 *
2508
 *  Creates a new time object with the value given by <i>time</i>,
2509
 *  the given number of <i>seconds_with_frac</i>, or
2510
 *  <i>seconds</i> and <i>microseconds_with_frac</i> from the Epoch.
2511
 *  <i>seconds_with_frac</i> and <i>microseconds_with_frac</i>
2512
 *  can be Integer, Float, Rational, or other Numeric.
2508
 *  Creates a new Time object with the value given by _time_,
2509
 *  the given number of _seconds_with_frac_, or
2510
 *  _seconds_ and _microseconds_with_frac_ since the Epoch.
2511
 *  _seconds_with_frac_ and _microseconds_with_frac_
2512
 *  can be integer, Float, Rational, or other Numeric.
2513 2513
 *  non-portable feature allows the offset to be negative on some systems.
2514 2514
 *
2515 2515
 *  If a numeric argument is given, the result is in local time.
......
3118 3118
 *    Time.gm(year, month, day, hour, min, sec, usec_with_frac) -> time
3119 3119
 *    Time.gm(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
3120 3120
 *
3121
 *  Creates a time based on given values, interpreted as UTC (GMT). The
3121
 *  Creates a Time object based on given values, interpreted as UTC (GMT). The
3122 3122
 *  year must be specified. Other values default to the minimum value
3123
 *  for that field (and may be <code>nil</code> or omitted). Months may
3123
 *  for that field (and may be +nil+ or omitted). Months may
3124 3124
 *  be specified by numbers from 1 to 12, or by the three-letter English
3125 3125
 *  month names. Hours are specified on a 24-hour clock (0..23). Raises
3126
 *  an <code>ArgumentError</code> if any values are out of range. Will
3127
 *  also accept ten arguments in the order output by
3128
 *  <code>Time#to_a</code>.
3129
 *  <i>sec_with_frac</i> and <i>usec_with_frac</i> can have a fractional part.
3126
 *  an ArgumentError if any values are out of range. Will
3127
 *  also accept ten arguments in the order output by Time#to_a.
3128
 *
3129
 *  _sec_with_frac_ and _usec_with_frac_ can have a fractional part.
3130 3130
 *
3131 3131
 *     Time.utc(2000,"jan",1,20,15,1)  #=> 2000-01-01 20:15:01 UTC
3132 3132
 *     Time.gm(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
......
3156 3156
 *   Time.mktime(year, month, day, hour, min, sec, usec_with_frac) -> time
3157 3157
 *   Time.mktime(sec, min, hour, day, month, year, wday, yday, isdst, tz) -> time
3158 3158
 *
3159
 *  Same as <code>Time::gm</code>, but interprets the values in the
3159
 *  Same as Time::gm, but interprets the values in the
3160 3160
 *  local time zone.
3161 3161
 *
3162 3162
 *     Time.local(2000,"jan",1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
......
3173 3173
 *     time.to_i   -> int
3174 3174
 *     time.tv_sec -> int
3175 3175
 *
3176
 *  Returns the value of <i>time</i> as an integer number of seconds
3176
 *  Returns the value of _time_ as an integer number of seconds
3177 3177
 *  since the Epoch.
3178 3178
 *
3179 3179
 *     t = Time.now
......
3194 3194
 *  call-seq:
3195 3195
 *     time.to_f -> float
3196 3196
 *
3197
 *  Returns the value of <i>time</i> as a floating point number of
3197
 *  Returns the value of _time_ as a floating point number of
3198 3198
 *  seconds since the Epoch.
3199 3199
 *
3200 3200
 *     t = Time.now
......
3202 3202
 *     t.to_i              #=> 1270968744
3203 3203
 *
3204 3204
 *  Note that IEEE 754 double is not accurate enough to represent
3205
 *  number of nanoseconds from the Epoch.
3205
 *  the number of nanoseconds since the Epoch.
3206 3206
 */
3207 3207

  
3208 3208
static VALUE
......
3218 3218
 *  call-seq:
3219 3219
 *     time.to_r -> a_rational
3220 3220
 *
3221
 *  Returns the value of <i>time</i> as a rational number of seconds
3221
 *  Returns the value of _time_ as a rational number of seconds
3222 3222
 *  since the Epoch.
3223 3223
 *
3224 3224
 *     t = Time.now
3225 3225
 *     p t.to_r            #=> (1270968792716287611/1000000000)
3226 3226
 *
3227 3227
 *  This methods is intended to be used to get an accurate value
3228
 *  representing nanoseconds from the Epoch.  You can use this
3229
 *  to convert time to another Epoch.
3228
 *  representing the nanoseconds since the Epoch. You can use this method
3229
 *  to convert _time_ to another Epoch.
3230 3230
 */
3231 3231

  
3232 3232
static VALUE
......
3248 3248
 *     time.usec    -> int
3249 3249
 *     time.tv_usec -> int
3250 3250
 *
3251
 *  Returns just the number of microseconds for <i>time</i>.
3251
 *  Returns the number of microseconds for _time_.
3252 3252
 *
3253 3253
 *     t = Time.now        #=> 2007-11-19 08:03:26 -0600
3254 3254
 *     "%10.6f" % t.to_f   #=> "1195481006.775195"
......
3273 3273
 *     time.nsec    -> int
3274 3274
 *     time.tv_nsec -> int
3275 3275
 *
3276
 *  Returns just the number of nanoseconds for <i>time</i>.
3276
 *  Returns the number of nanoseconds for _time_.
3277 3277
 *
3278 3278
 *     t = Time.now        #=> 2007-11-17 15:18:03 +0900
3279 3279
 *     "%10.9f" % t.to_f   #=> "1195280283.536151409"
3280 3280
 *     t.nsec              #=> 536151406
3281 3281
 *
3282
 *  The lowest digit of to_f and nsec is different because
3282
 *  The lowest digits of #to_f and #nsec are different because
3283 3283
 *  IEEE 754 double is not accurate enough to represent
3284
 *  nanoseconds from the Epoch.
3285
 *  The accurate value is returned by nsec.
3284
 *  the exact number of nanoseconds since the Epoch.
3285
 *
3286
 *  The more accurate value is returned by #nsec.
3286 3287
 */
3287 3288

  
3288 3289
static VALUE
......
3298 3299
 *  call-seq:
3299 3300
 *     time.subsec    -> number
3300 3301
 *
3301
 *  Returns just the fraction for <i>time</i>.
3302
 *  Returns the fraction for _time_.
3302 3303
 *
3303
 *  The result is possibly rational.
3304
 *  The return value can be a rational number.
3304 3305
 *
3305 3306
 *     t = Time.now        #=> 2009-03-26 22:33:12 +0900
3306 3307
 *     "%10.9f" % t.to_f   #=> "1238074392.940563917"
3307 3308
 *     t.subsec            #=> (94056401/100000000)
3308 3309
 *
3309
 *  The lowest digit of to_f and subsec is different because
3310
 *  The lowest digits of #to_f and #subsec are different because
3310 3311
 *  IEEE 754 double is not accurate enough to represent
3311
 *  the rational.
3312
 *  The accurate value is returned by subsec.
3312
 *  the rational number.
3313
 *
3314
 *  The more accurate value is returned by #subsec.
3313 3315
 */
3314 3316

  
3315 3317
static VALUE
......
3325 3327
 *  call-seq:
3326 3328
 *     time <=> other_time -> -1, 0, +1 or nil
3327 3329
 *
3328
 *  Comparison---Compares <i>time</i> with <i>other_time</i>.
3330
 *  Comparison---Compares _time_ with _other_time_.
3331
 *  The return value is ++1+ if _time_ is greater than
3332
 *  _other_time_, +0+ if time is equal to _other_time_ and
3333
 *  +-1+ if time is smaller than _other_time_.
3329 3334
 *
3330 3335
 *     t = Time.now       #=> 2007-11-19 08:12:12 -0600
3331 3336
 *     t2 = t + 2592000   #=> 2007-12-19 08:12:12 -0600
......
3369 3374
 * call-seq:
3370 3375
 *  time.eql?(other_time)
3371 3376
 *
3372
 * Return <code>true</code> if <i>time</i> and <i>other_time</i> are
3373
 * both <code>Time</code> objects with the same seconds and fractional
3374
 * seconds.
3377
 * Returns +true+ if _time_ and _other_time_ are
3378
 * both Time objects with the same seconds and fractional seconds.
3375 3379
 */
3376 3380

  
3377 3381
static VALUE
......
3392 3396
 *     time.utc? -> true or false
3393 3397
 *     time.gmt? -> true or false
3394 3398
 *
3395
 *  Returns <code>true</code> if <i>time</i> represents a time in UTC
3396
 *  (GMT).
3399
 *  Returns +true+ if _time_ represents a time in UTC (GMT).
3397 3400
 *
3398 3401
 *     t = Time.now                        #=> 2007-11-19 08:15:23 -0600
3399 3402
 *     t.utc?                              #=> false
......
3420 3423
 * call-seq:
3421 3424
 *   time.hash   -> fixnum
3422 3425
 *
3423
 * Return a hash code for this time object.
3426
 * Returns a hash code for this Time object.
3424 3427
 */
3425 3428

  
3426 3429
static VALUE
......
3483 3486
 *     time.localtime -> time
3484 3487
 *     time.localtime(utc_offset) -> time
3485 3488
 *
3486
 *  Converts <i>time</i> to local time (using the local time zone in
3489
 *  Converts _time_ to local time (using the local time zone in
3487 3490
 *  effect for this process) modifying the receiver.
3488 3491
 *
3489 3492
 *  If _utc_offset_ is given, it is used instead of the local time.
......
3520 3523
 *     time.gmtime    -> time
3521 3524
 *     time.utc       -> time
3522 3525
 *
3523
 *  Converts <i>time</i> to UTC (GMT), modifying the receiver.
3526
 *  Converts _time_ to UTC (GMT), modifying the receiver.
3524 3527
 *
3525 3528
 *     t = Time.now   #=> 2007-11-19 08:18:31 -0600
3526 3529
 *     t.gmt?         #=> false
......
3594 3597
 *     time.getlocal -> new_time
3595 3598
 *     time.getlocal(utc_offset) -> new_time
3596 3599
 *
3597
 *  Returns a new <code>new_time</code> object representing <i>time</i> in
3600
 *  Returns a new Time object representing _time_ in
3598 3601
 *  local time (using the local time zone in effect for this process).
3599 3602
 *
3600 3603
 *  If _utc_offset_ is given, it is used instead of the local time.
......
3634 3637
 *     time.getgm  -> new_time
3635 3638
 *     time.getutc -> new_time
3636 3639
 *
3637
 *  Returns a new <code>new_time</code> object representing <i>time</i> in
3638
 *  UTC.
3640
 *  Returns a new Time object representing _time_ in UTC.
3639 3641
 *
3640 3642
 *     t = Time.local(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
3641 3643
 *     t.gmt?                             #=> false
......
3665 3667
 *     time.asctime -> string
3666 3668
 *     time.ctime   -> string
3667 3669
 *
3668
 *  Returns a canonical string representation of <i>time</i>.
3670
 *  Returns a canonical string representation of _time_.
3669 3671
 *
3670 3672
 *     Time.now.asctime   #=> "Wed Apr  9 08:56:03 2003"
3671 3673
 */
......
3681 3683
 *     time.inspect -> string
3682 3684
 *     time.to_s    -> string
3683 3685
 *
3684
 *  Returns a string representing <i>time</i>. Equivalent to calling
3685
 *  <code>Time#strftime</code> with a format string of
3686
 *  ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>%z</code>''
3687
 *  for a local time and
3688
 *  ``<code>%Y-%m-%d</code> <code>%H:%M:%S</code> <code>UTC</code>''
3689
 *  for a UTC time.
3686
 *  Returns a string representing _time_. Equivalent to calling
3687
 *  +#strftime+ with the appropriate format string. 
3690 3688
 *
3691
 *     Time.now.to_s       #=> "2007-10-05 16:09:51 +0900"
3692
 *     Time.now.utc.to_s   #=> "2007-10-05 07:09:51 UTC"
3689
 *     t = Time.now       
3690
 *     t.to_s                              => "2012-11-10 18:16:12 +0100"
3691
 *     t.strftime "%Y-%m-%d %H:%M:%S %z"   => "2012-11-10 18:16:12 +0100"
3692
 *     
3693
 *     t.utc.to_s                          => "2012-11-10 17:16:12 UTC"
3694
 *     t.strftime "%Y-%m-%d %H:%M:%S UTC"  => "2012-11-10 17:16:12 UTC"
3693 3695
 */
3694 3696

  
3695 3697
static VALUE
......
3730 3732
 *     time + numeric -> time
3731 3733
 *
3732 3734
 *  Addition---Adds some number of seconds (possibly fractional) to
3733
 *  <i>time</i> and returns that value as a new time.
3735
 *  _time_ and returns that value as a new Time object.
3734 3736
 *
3735 3737
 *     t = Time.now         #=> 2007-11-19 08:22:21 -0600
3736 3738
 *     t + (60 * 60 * 24)   #=> 2007-11-20 08:22:21 -0600
......
3753 3755
 *     time - other_time -> float
3754 3756
 *     time - numeric    -> time
3755 3757
 *
3756
 *  Difference---Returns a new time that represents the difference
3757
 *  between two times, or subtracts the given number of seconds in
3758
 *  <i>numeric</i> from <i>time</i>.
3758
 *  Difference---Returns a new Time object that represents the difference
3759
 *  between _time_ and _other_time_, or subtracts the given number
3760
 *  of seconds in _numeric_ from _time_.
3759 3761
 *
3760 3762
 *     t = Time.now       #=> 2007-11-19 08:23:10 -0600
3761 3763
 *     t2 = t + 2592000   #=> 2007-12-19 08:23:10 -0600
......
3782 3784
 * call-seq:
3783 3785
 *   time.succ   -> new_time
3784 3786
 *
3785
 * Return a new time object, one second later than <code>time</code>.
3787
 * Returns a new Time object, one second later than _time_.
3786 3788
 * Time#succ is obsolete since 1.9.2 for time is not a discrete value.
3787 3789
 *
3788 3790
 *     t = Time.now       #=> 2007-11-19 08:23:57 -0600
3789 3791
 *     t.succ             #=> 2007-11-19 08:23:58 -0600
3792
 *
3793
 * Use instead <code>time + 1</code>
3794
 *
3795
 *     t + 1              #=> 2007-11-19 08:23:58 -0600
3790 3796
 */
3791 3797

  
3792 3798
VALUE
......
3810 3816
 *   time.round([ndigits])   -> new_time
3811 3817
 *
3812 3818
 * Rounds sub seconds to a given precision in decimal digits (0 digits by default).
3813
 * It returns a new time object.
3819
 * It returns a new Time object.
3814 3820
 * _ndigits_ should be zero or positive integer.
3815 3821
 *
3816 3822
 *     require 'time'
......
3883 3889
 *  call-seq:
3884 3890
 *     time.sec -> fixnum
3885 3891
 *
3886
 *  Returns the second of the minute (0..60) for <i>time</i>.
3892
 *  Returns the second of the minute (0..60) for _time_.
3887 3893
 *
3888
 *  <em>[Yes, seconds range from zero to 60.  This allows the system to inject
3889
 *  leap seconds.  See http://en.wikipedia.org/wiki/Leap_second for further
3890
 *  details.]</em>
3894
 *  *Note:* Seconds range from zero to 60 to allow the system to inject
3895
 *  leap seconds. See http://en.wikipedia.org/wiki/Leap_second for further
3896
 *  details.
3891 3897
 *
3892 3898
 *     t = Time.now   #=> 2007-11-19 08:25:02 -0600
3893 3899
 *     t.sec          #=> 2
......
3907 3913
 *  call-seq:
3908 3914
 *     time.min -> fixnum
3909 3915
 *
3910
 *  Returns the minute of the hour (0..59) for <i>time</i>.
3916
 *  Returns the minute of the hour (0..59) for _time_.
3911 3917
 *
3912 3918
 *     t = Time.now   #=> 2007-11-19 08:25:51 -0600
3913 3919
 *     t.min          #=> 25
......
3927 3933
 *  call-seq:
3928 3934
 *     time.hour -> fixnum
3929 3935
 *
3930
 *  Returns the hour of the day (0..23) for <i>time</i>.
3936
 *  Returns the hour of the day (0..23) for _time_.
3931 3937
 *
3932 3938
 *     t = Time.now   #=> 2007-11-19 08:26:20 -0600
3933 3939
 *     t.hour         #=> 8
......
3948 3954
 *     time.day  -> fixnum
3949 3955
 *     time.mday -> fixnum
3950 3956
 *
3951
 *  Returns the day of the month (1..n) for <i>time</i>.
3957
 *  Returns the day of the month (1..n) for _time_.
3952 3958
 *
3953 3959
 *     t = Time.now   #=> 2007-11-19 08:27:03 -0600
3954 3960
 *     t.day          #=> 19
......
3970 3976
 *     time.mon   -> fixnum
3971 3977
 *     time.month -> fixnum
3972 3978
 *
3973
 *  Returns the month of the year (1..12) for <i>time</i>.
3979
 *  Returns the month of the year (1..12) for _time_.
3974 3980
 *
3975 3981
 *     t = Time.now   #=> 2007-11-19 08:27:30 -0600
3976 3982
 *     t.mon          #=> 11
......
3991 3997
 *  call-seq:
3992 3998
 *     time.year -> fixnum
3993 3999
 *
3994
 *  Returns the year for <i>time</i> (including the century).
4000
 *  Returns the year for _time_ (including the century).
3995 4001
 *
3996 4002
 *     t = Time.now   #=> 2007-11-19 08:27:51 -0600
3997 4003
 *     t.year         #=> 2007
......
4046 4052
 *  call-seq:
4047 4053
 *     time.sunday? -> true or false
4048 4054
 *
4049
 *  Returns <code>true</code> if <i>time</i> represents Sunday.
4055
 *  Returns +true+ if _time_ represents Sunday.
4050 4056
 *
4051 4057
 *     t = Time.local(1990, 4, 1)       #=> 1990-04-01 00:00:00 -0600
4052 4058
 *     t.sunday?                        #=> true
......
4062 4068
 *  call-seq:
4063 4069
 *     time.monday? -> true or false
4064 4070
 *
4065
 *  Returns <code>true</code> if <i>time</i> represents Monday.
4071
 *  Returns +true+ if _time_ represents Monday.
4066 4072
 *
4067 4073
 *     t = Time.local(2003, 8, 4)       #=> 2003-08-04 00:00:00 -0500
4068 4074
 *     p t.monday?                      #=> true
......
4078 4084
 *  call-seq:
4079 4085
 *     time.tuesday? -> true or false
4080 4086
 *
4081
 *  Returns <code>true</code> if <i>time</i> represents Tuesday.
4087
 *  Returns +true+ if _time_ represents Tuesday.
4082 4088
 *
4083 4089
 *     t = Time.local(1991, 2, 19)      #=> 1991-02-19 00:00:00 -0600
4084 4090
 *     p t.tuesday?                     #=> true
......
4094 4100
 *  call-seq:
4095 4101
 *     time.wednesday? -> true or false
4096 4102
 *
4097
 *  Returns <code>true</code> if <i>time</i> represents Wednesday.
4103
 *  Returns +true+ if _time_ represents Wednesday.
4098 4104
 *
4099 4105
 *     t = Time.local(1993, 2, 24)      #=> 1993-02-24 00:00:00 -0600
4100 4106
 *     p t.wednesday?                   #=> true
......
4110 4116
 *  call-seq:
4111 4117
 *     time.thursday? -> true or false
4112 4118
 *
4113
 *  Returns <code>true</code> if <i>time</i> represents Thursday.
4119
 *  Returns +true+ if _time_ represents Thursday.
4114 4120
 *
4115 4121
 *     t = Time.local(1995, 12, 21)     #=> 1995-12-21 00:00:00 -0600
4116 4122
 *     p t.thursday?                    #=> true
......
4126 4132
 *  call-seq:
4127 4133
 *     time.friday? -> true or false
4128 4134
 *
4129
 *  Returns <code>true</code> if <i>time</i> represents Friday.
4135
 *  Returns +true+ if _time_ represents Friday.
4130 4136
 *
4131 4137
 *     t = Time.local(1987, 12, 18)     #=> 1987-12-18 00:00:00 -0600
4132 4138
 *     t.friday?                        #=> true
......
4142 4148
 *  call-seq:
4143 4149
 *     time.saturday? -> true or false
4144 4150
 *
4145
 *  Returns <code>true</code> if <i>time</i> represents Saturday.
4151
 *  Returns +true+ if _time_ represents Saturday.
4146 4152
 *
4147 4153
 *     t = Time.local(2006, 6, 10)      #=> 2006-06-10 00:00:00 -0500
4148 4154
 *     t.saturday?                      #=> true
......
4179 4185
 *     time.isdst -> true or false
4180 4186
 *     time.dst?  -> true or false
4181 4187
 *
4182
 *  Returns <code>true</code> if <i>time</i> occurs during Daylight
4188
 *  Returns +true+ if _time_ occurs during Daylight
4183 4189
 *  Saving Time in its time zone.
4184 4190
 *
4185 4191
 *   # CST6CDT:
......
4213 4219
 *  call-seq:
4214 4220
 *     time.zone -> string
4215 4221
 *
4216
 *  Returns the name of the time zone used for <i>time</i>. As of Ruby
4222
 *  Returns the name of the time zone used for _time_. As of Ruby
4217 4223
 *  1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
4218 4224
 *
4219 4225
 *     t = Time.gm(2000, "jan", 1, 20, 15, 1)
......
4244 4250
 *     time.gmtoff     -> fixnum
4245 4251
 *     time.utc_offset -> fixnum
4246 4252
 *
4247
 *  Returns the offset in seconds between the timezone of <i>time</i>
4253
 *  Returns the offset in seconds between the timezone of _time_
4248 4254
 *  and UTC.
4249 4255
 *
4250 4256
 *     t = Time.gm(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
......
4273 4279
 *  call-seq:
4274 4280
 *     time.to_a -> array
4275 4281
 *
4276
 *  Returns a ten-element <i>array</i> of values for <i>time</i>:
4277
 *  {<code>[ sec, min, hour, day, month, year, wday, yday, isdst, zone
4278
 *  ]</code>}. See the individual methods for an explanation of the
4282
 *  Returns a ten-element _array_ of values for _time_:
4283
 *
4284
 *     [sec, min, hour, day, month, year, wday, yday, isdst, zone]
4285
 *
4286
 *  See the individual methods for an explanation of the
4279 4287
 *  valid ranges of each value. The ten elements can be passed directly
4280
 *  to <code>Time::utc</code> or <code>Time::local</code> to create a
4281
 *  new <code>Time</code>.
4288
 *  to Time::utc or Time::local to create a
4289
 *  new Time object.
4282 4290
 *
4283 4291
 *     t = Time.now     #=> 2007-11-19 08:36:01 -0600
4284 4292
 *     now = t.to_a     #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
......
4372 4380
 *  call-seq:
4373 4381
 *     time.strftime( string ) -> string
4374 4382
 *
4375
 *  Formats <i>time</i> according to the directives in the given format
4376
 *  string.
4377
 *  The directives begins with a percent (%) character.
4383
 *  Formats _time_ according to the directives in the given format string.
4384
 *
4385
 *  The directives begin with a percent (%) character.
4378 4386
 *  Any text not listed as a directive will be passed through to the
4379 4387
 *  output string.
4380 4388
 *
4381 4389
 *  The directive consists of a percent (%) character,
4382 4390
 *  zero or more flags, optional minimum field width,
4383 4391
 *  optional modifier and a conversion specifier
4384
 *  as follows.
4392
 *  as follows:
4385 4393
 *
4386 4394
 *    %<flags><width><modifier><conversion>
4387 4395
 *
4388 4396
 *  Flags:
4389
 *    -  don't pad a numerical output.
4390
 *    _  use spaces for padding.
4391
 *    0  use zeros for padding.
4392
 *    ^  upcase the result string.
4393
 *    #  change case.
4394
 *    :  use colons for %z.
4397
 *    -  don't pad a numerical output
4398
 *    _  use spaces for padding
4399
 *    0  use zeros for padding
4400
 *    ^  upcase the result string
4401
 *    #  change case
4402
 *    :  use colons for %z
4395 4403
 *
4396 4404
 *  The minimum field width specifies the minimum width.
4397 4405
 *
4398
 *  The modifier is "E" and "O".
4406
 *  The modifiers are "E" and "O".
4399 4407
 *  They are ignored.
4400 4408
 *
4401 4409
 *  Format directives:
......
4403 4411
 *    Date (Year, Month, Day):
4404 4412
 *      %Y - Year with century (can be negative, 4 digits at least)
4405 4413
 *              -0001, 0000, 1995, 2009, 14292, etc.
4406
 *      %C - year / 100 (round down.  20 in 2009)
4414
 *      %C - year / 100 (rounded down such as 20 in 2009)
4407 4415
 *      %y - year % 100 (00..99)
4408 4416
 *
4409 4417
 *      %m - Month of the year, zero-padded (01..12)
......
4448 4456
 *      %z - Time zone as hour and minute offset from UTC (e.g. +0900)
4449 4457
 *              %:z - hour and minute offset from UTC with a colon (e.g. +09:00)
4450 4458
 *              %::z - hour, minute and second offset from UTC (e.g. +09:00:00)
4451
 *      %Z - Time zone abbreviation name or something similar information.
4459
 *      %Z - Abbreviated time zone name or similar information.
4452 4460
 *
4453 4461
 *    Weekday:
4454 4462
 *      %A - The full weekday name (``Sunday'')
......
4459 4467
 *      %w - Day of the week (Sunday is 0, 0..6)
4460 4468
 *
4461 4469
 *    ISO 8601 week-based year and week number:
4462
 *    The week 1 of YYYY starts with a Monday and includes YYYY-01-04.
4470
 *    The first week of YYYY starts with a Monday and includes YYYY-01-04.
4463 4471
 *    The days in the year before the first week are in the last week of
4464 4472
 *    the previous year.
4465 4473
 *      %G - The week-based year
......
4467 4475
 *      %V - Week number of the week-based year (01..53)
4468 4476
 *
4469 4477
 *    Week number:
4470
 *    The week 1 of YYYY starts with a Sunday or Monday (according to %U
4471
 *    or %W).  The days in the year before the first week are in week 0.
4472
 *      %U - Week number of the year.  The week starts with Sunday.  (00..53)
4473
 *      %W - Week number of the year.  The week starts with Monday.  (00..53)
4478
 *    The first week of YYYY that starts with a Sunday or Monday (according to %U
4479
 *    or %W). The days in the year before the first week are in week 0.
4480
 *      %U - Week number of the year. The week starts with Sunday. (00..53)
4481
 *      %W - Week number of the year. The week starts with Monday. (00..53)
4474 4482
 *
4475 4483
 *    Seconds since the Epoch:
4476 4484
 *      %s - Number of seconds since 1970-01-01 00:00:00 UTC.
......
4492 4500
 *      %T - 24-hour time (%H:%M:%S)
4493 4501
 *
4494 4502
 *  This method is similar to strftime() function defined in ISO C and POSIX.
4495
 *  Several directives (%a, %A, %b, %B, %c, %p, %r, %x, %X, %E*, %O* and %Z)
4496
 *  are locale dependent in the function.
4497
 *  However this method is locale independent since Ruby 1.9.
4498
 *  (%Z is platform dependent, though.)
4499
 *  So, the result may differ even if a same format string is used in other
4503
 *
4504
 *  While all directives are locale independant since Ruby 1.9 %Z is platform
4505
 *  dependant.
4506
 *  So, the result may differ even if the same format string is used in other
4500 4507
 *  systems such as C.
4501
 *  It is good practice to avoid %x and %X because there are corresponding
4502
 *  locale independent representations, %D and %T.
4503 4508
 *
4504 4509
 *  %z is recommended over %Z.
4505 4510
 *  %Z doesn't identify the timezone.
4506 4511
 *  For example, "CST" is used at America/Chicago (-06:00),
4507 4512
 *  America/Havana (-05:00), Asia/Harbin (+08:00), Australia/Darwin (+09:30)
4508 4513
 *  and Australia/Adelaide (+10:30).
4509
 *  Also, %Z is highly dependent for OS.
4514
 *  Also, %Z is highly dependent on the operating system.
4510 4515
 *  For example, it may generate a non ASCII string on Japanese Windows.
4511 4516
 *  i.e. the result can be different to "JST".
4512 4517
 *  So the numeric time zone offset, %z, is recommended.
......
4849 4854
 * call-seq:
4850 4855
 *   Time._load(string)   -> time
4851 4856
 *
4852
 * Unmarshal a dumped +Time+ object.
4857
 * Unmarshal a dumped Time object.
4853 4858
 */
4854 4859

  
4855 4860
static VALUE
......
4864 4869
/*
4865 4870
 *  Time is an abstraction of dates and times. Time is stored internally as
4866 4871
 *  the number of seconds with fraction since the _Epoch_, January 1, 1970
4867
 *  00:00 UTC. Also see the library modules Date. The Time class treats GMT
4872
 *  00:00 UTC. Also see the library module Date. The Time class treats GMT
4868 4873
 *  (Greenwich Mean Time) and UTC (Coordinated Universal Time) as equivalent.
4869 4874
 *  GMT is the older way of referring to these baseline times but persists in
4870 4875
 *  the names of calls on POSIX systems.
......
4873 4878
 *  with each other -- times that are apparently equal when displayed may be
4874 4879
 *  different when compared.
4875 4880
 *
4876
 *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational.
4881
 *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer,
4882
 *  Bignum or Rational.
4877 4883
 *  The integer is a number of nanoseconds since the _Epoch_ which can
4878 4884
 *  represent 1823-11-12 to 2116-02-20.
4879
 *  When Bignum or Rational is used (before 1823, after 2116, under nanosecond),
4880
 *  Time works slower than the integer is used.
4885
 *  When Bignum or Rational is used (before 1823, after 2116, under 
4886
 *  nanosecond), Time works slower as when integer is used.
4881 4887
 *
4882 4888
 *  = Examples
4883 4889
 *
......
4885 4891
 *
4886 4892
 *  == Creating a new Time instance
4887 4893
 *
4888
 *  You can create a new instance of time with Time.new. This will use the
4889
 *  current system time. Time.now is a synonym for this. You can also
4890
 *  pass parts of the time to Time.new such as year, month, minute, etc. When
4894
 *  You can create a new instance of Time with Time::new. This will use the
4895
 *  current system time. Time::now is an alias for this. You can also
4896
 *  pass parts of the time to Time::new such as year, month, minute, etc. When
4891 4897
 *  you want to construct a time this way you must pass at least a year. If you
4892
 *  pass the year with nothing else time with default to January 1 of that year
4898
 *  pass the year with nothing else time will default to January 1 of that year
4893 4899
 *  at 00:00:00 with the current system timezone. Here are some examples:
4894 4900
 *
4895 4901
 *    Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
......
4897 4903
 *    Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
4898 4904
 *    Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 -0200
4899 4905
 *
4900
 *  You can also use #gm, #local and #utc to infer GMT, local and UTC
4901
 *  timezones instead of using the current system setting.
4906
 *  You can also use #gm, #local and
4907
 *  #utc to infer GMT, local and UTC timezones instead of using 
4908
 *  the current system setting.
4902 4909
 *
4903
 *  You can also create a new time using Time.at which takes the number of
4910
 *  You can also create a new time using Time::at which takes the number of
4904 4911
 *  seconds (or fraction of seconds) since the {Unix
4905 4912
 *  Epoch}[http://en.wikipedia.org/wiki/Unix_time].
4906 4913
 *
......
4908 4915
 *
4909 4916
 *  == Working with an instance of Time
4910 4917
 *
4911
 *  Once you have an instance of time there is a multitude of things you can do
4912
 *  with it. Below are some examples. For all of the following examples, we
4918
 *  Once you have an instance of Time there is a multitude of things you can
4919
 *  do with it. Below are some examples. For all of the following examples, we
4913 4920
 *  will work on the assumption that you have done the following:
4914 4921
 *
4915 4922
 *    t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
......
4930 4937
 *
4931 4938
 *    t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
4932 4939
 *
4933
 *  How many second was that from the Unix Epoch?
4940
 *  How many seconds was that since the Unix Epoch?
4934 4941
 *
4935 4942
 *    t.to_i #=> 730522800
4936 4943
 *