Project

General

Profile

Bug #7326 ยป time_patch0002.diff

bt (Bernd Homuth), 11/24/2012 07:38 PM

View differences:

time.c
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 2225
 *  It is initialized to the current system time if no argument.
2226 2226
 *  <b>Note:</b> The object created will be created using the
......
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.
2516 2516
 *
2517
 *     Time.at(0)            #=> 1969-12-31 18:00:00 -0600
2518
 *     Time.at(Time.at(0))   #=> 1969-12-31 18:00:00 -0600
2519
 *     Time.at(946702800)    #=> 1999-12-31 23:00:00 -0600
2520
 *     Time.at(-284061600)   #=> 1960-12-31 00:00:00 -0600
2521
 *     Time.at(946684800.2).usec #=> 200000
2522
 *     Time.at(946684800, 123456.789).nsec #=> 123456789
2517
 *     Time.at(0)                           #=> 1969-12-31 18:00:00 -0600
2518
 *     Time.at(Time.at(0))                  #=> 1969-12-31 18:00:00 -0600
2519
 *     Time.at(946702800)                   #=> 1999-12-31 23:00:00 -0600
2520
 *     Time.at(-284061600)                  #=> 1960-12-31 00:00:00 -0600
2521
 *     Time.at(946684800.2).usec            #=> 200000
2522
 *     Time.at(946684800, 123456.789).nsec  #=> 123456789
2523 2523
 */
2524 2524

  
2525 2525
static VALUE
......
3120 3120
 *
3121 3121
 *  Creates a time 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
......
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 3284
 *  nanoseconds from the Epoch.
3285 3285
 *  The accurate value is returned by nsec.
......
3298 3298
 *  call-seq:
3299 3299
 *     time.subsec    -> number
3300 3300
 *
3301
 *  Returns just the fraction for <i>time</i>.
3301
 *  Returns the fraction for _time_.
3302 3302
 *
3303 3303
 *  The result is possibly rational.
3304 3304
 *
......
3306 3306
 *     "%10.9f" % t.to_f   #=> "1238074392.940563917"
3307 3307
 *     t.subsec            #=> (94056401/100000000)
3308 3308
 *
3309
 *  The lowest digit of to_f and subsec is different because
3309
 *  The lowest digits of #to_f and #subsec are different because
3310 3310
 *  IEEE 754 double is not accurate enough to represent
3311 3311
 *  the rational.
3312 3312
 *  The accurate value is returned by subsec.
......
3369 3369
 * call-seq:
3370 3370
 *  time.eql?(other_time)
3371 3371
 *
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.
3372
 * Returns +true+ if _time_ and +other_time+ are
3373
 * both Time objects with the same seconds and fractional seconds.
3375 3374
 */
3376 3375

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

  
3426 3424
static VALUE
......
3483 3481
 *     time.localtime -> time
3484 3482
 *     time.localtime(utc_offset) -> time
3485 3483
 *
3486
 *  Converts <i>time</i> to local time (using the local time zone in
3484
 *  Converts _time_ to local time (using the local time zone in
3487 3485
 *  effect for this process) modifying the receiver.
3488 3486
 *
3489 3487
 *  If _utc_offset_ is given, it is used instead of the local time.
......
3520 3518
 *     time.gmtime    -> time
3521 3519
 *     time.utc       -> time
3522 3520
 *
3523
 *  Converts <i>time</i> to UTC (GMT), modifying the receiver.
3521
 *  Converts _time_ to UTC (GMT), modifying the receiver.
3524 3522
 *
3525 3523
 *     t = Time.now   #=> 2007-11-19 08:18:31 -0600
3526 3524
 *     t.gmt?         #=> false
......
3594 3592
 *     time.getlocal -> new_time
3595 3593
 *     time.getlocal(utc_offset) -> new_time
3596 3594
 *
3597
 *  Returns a new <code>new_time</code> object representing <i>time</i> in
3595
 *  Returns a new Time object representing _time_ in
3598 3596
 *  local time (using the local time zone in effect for this process).
3599 3597
 *
3600 3598
 *  If _utc_offset_ is given, it is used instead of the local time.
......
3634 3632
 *     time.getgm  -> new_time
3635 3633
 *     time.getutc -> new_time
3636 3634
 *
3637
 *  Returns a new <code>new_time</code> object representing <i>time</i> in
3638
 *  UTC.
3635
 *  Returns a new Time object representing _time_ in UTC.
3639 3636
 *
3640 3637
 *     t = Time.local(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 -0600
3641 3638
 *     t.gmt?                             #=> false
......
3665 3662
 *     time.asctime -> string
3666 3663
 *     time.ctime   -> string
3667 3664
 *
3668
 *  Returns a canonical string representation of <i>time</i>.
3665
 *  Returns a canonical string representation of _time_.
3669 3666
 *
3670 3667
 *     Time.now.asctime   #=> "Wed Apr  9 08:56:03 2003"
3671 3668
 */
......
3730 3727
 *     time + numeric -> time
3731 3728
 *
3732 3729
 *  Addition---Adds some number of seconds (possibly fractional) to
3733
 *  <i>time</i> and returns that value as a new time.
3730
 *  _time_ and returns that value as a new Time object.
3734 3731
 *
3735 3732
 *     t = Time.now         #=> 2007-11-19 08:22:21 -0600
3736 3733
 *     t + (60 * 60 * 24)   #=> 2007-11-20 08:22:21 -0600
......
3782 3779
 * call-seq:
3783 3780
 *   time.succ   -> new_time
3784 3781
 *
3785
 * Return a new time object, one second later than <code>time</code>.
3782
 * Returns a new Time object, one second later than _time_.
3786 3783
 * Time#succ is obsolete since 1.9.2 for time is not a discrete value.
3787 3784
 *
3788 3785
 *     t = Time.now       #=> 2007-11-19 08:23:57 -0600
......
3810 3807
 *   time.round([ndigits])   -> new_time
3811 3808
 *
3812 3809
 * Rounds sub seconds to a given precision in decimal digits (0 digits by default).
3813
 * It returns a new time object.
3810
 * It returns a new Time object.
3814 3811
 * _ndigits_ should be zero or positive integer.
3815 3812
 *
3816 3813
 *     require 'time'
......
3883 3880
 *  call-seq:
3884 3881
 *     time.sec -> fixnum
3885 3882
 *
3886
 *  Returns the second of the minute (0..60) for <i>time</i>.
3883
 *  Returns the second of the minute (0..60) for _time_.
3887 3884
 *
3888 3885
 *  <em>[Yes, seconds range from zero to 60.  This allows the system to inject
3889 3886
 *  leap seconds.  See http://en.wikipedia.org/wiki/Leap_second for further
......
3907 3904
 *  call-seq:
3908 3905
 *     time.min -> fixnum
3909 3906
 *
3910
 *  Returns the minute of the hour (0..59) for <i>time</i>.
3907
 *  Returns the minute of the hour (0..59) for _time_.
3911 3908
 *
3912 3909
 *     t = Time.now   #=> 2007-11-19 08:25:51 -0600
3913 3910
 *     t.min          #=> 25
......
3927 3924
 *  call-seq:
3928 3925
 *     time.hour -> fixnum
3929 3926
 *
3930
 *  Returns the hour of the day (0..23) for <i>time</i>.
3927
 *  Returns the hour of the day (0..23) for _time_.
3931 3928
 *
3932 3929
 *     t = Time.now   #=> 2007-11-19 08:26:20 -0600
3933 3930
 *     t.hour         #=> 8
......
3948 3945
 *     time.day  -> fixnum
3949 3946
 *     time.mday -> fixnum
3950 3947
 *
3951
 *  Returns the day of the month (1..n) for <i>time</i>.
3948
 *  Returns the day of the month (1..n) for _time_.
3952 3949
 *
3953 3950
 *     t = Time.now   #=> 2007-11-19 08:27:03 -0600
3954 3951
 *     t.day          #=> 19
......
3970 3967
 *     time.mon   -> fixnum
3971 3968
 *     time.month -> fixnum
3972 3969
 *
3973
 *  Returns the month of the year (1..12) for <i>time</i>.
3970
 *  Returns the month of the year (1..12) for _time_.
3974 3971
 *
3975 3972
 *     t = Time.now   #=> 2007-11-19 08:27:30 -0600
3976 3973
 *     t.mon          #=> 11
......
3991 3988
 *  call-seq:
3992 3989
 *     time.year -> fixnum
3993 3990
 *
3994
 *  Returns the year for <i>time</i> (including the century).
3991
 *  Returns the year for _time_ (including the century).
3995 3992
 *
3996 3993
 *     t = Time.now   #=> 2007-11-19 08:27:51 -0600
3997 3994
 *     t.year         #=> 2007
......
4046 4043
 *  call-seq:
4047 4044
 *     time.sunday? -> true or false
4048 4045
 *
4049
 *  Returns <code>true</code> if <i>time</i> represents Sunday.
4046
 *  Returns +true+ if _time_ represents Sunday.
4050 4047
 *
4051 4048
 *     t = Time.local(1990, 4, 1)       #=> 1990-04-01 00:00:00 -0600
4052 4049
 *     t.sunday?                        #=> true
......
4062 4059
 *  call-seq:
4063 4060
 *     time.monday? -> true or false
4064 4061
 *
4065
 *  Returns <code>true</code> if <i>time</i> represents Monday.
4062
 *  Returns +true+ if _time_ represents Monday.
4066 4063
 *
4067 4064
 *     t = Time.local(2003, 8, 4)       #=> 2003-08-04 00:00:00 -0500
4068 4065
 *     p t.monday?                      #=> true
......
4078 4075
 *  call-seq:
4079 4076
 *     time.tuesday? -> true or false
4080 4077
 *
4081
 *  Returns <code>true</code> if <i>time</i> represents Tuesday.
4078
 *  Returns +true+ if _time_ represents Tuesday.
4082 4079
 *
4083 4080
 *     t = Time.local(1991, 2, 19)      #=> 1991-02-19 00:00:00 -0600
4084 4081
 *     p t.tuesday?                     #=> true
......
4094 4091
 *  call-seq:
4095 4092
 *     time.wednesday? -> true or false
4096 4093
 *
4097
 *  Returns <code>true</code> if <i>time</i> represents Wednesday.
4094
 *  Returns +true+ if _time_ represents Wednesday.
4098 4095
 *
4099 4096
 *     t = Time.local(1993, 2, 24)      #=> 1993-02-24 00:00:00 -0600
4100 4097
 *     p t.wednesday?                   #=> true
......
4110 4107
 *  call-seq:
4111 4108
 *     time.thursday? -> true or false
4112 4109
 *
4113
 *  Returns <code>true</code> if <i>time</i> represents Thursday.
4110
 *  Returns +true+ if _time_ represents Thursday.
4114 4111
 *
4115 4112
 *     t = Time.local(1995, 12, 21)     #=> 1995-12-21 00:00:00 -0600
4116 4113
 *     p t.thursday?                    #=> true
......
4126 4123
 *  call-seq:
4127 4124
 *     time.friday? -> true or false
4128 4125
 *
4129
 *  Returns <code>true</code> if <i>time</i> represents Friday.
4126
 *  Returns +true+ if _time_ represents Friday.
4130 4127
 *
4131 4128
 *     t = Time.local(1987, 12, 18)     #=> 1987-12-18 00:00:00 -0600
4132 4129
 *     t.friday?                        #=> true
......
4142 4139
 *  call-seq:
4143 4140
 *     time.saturday? -> true or false
4144 4141
 *
4145
 *  Returns <code>true</code> if <i>time</i> represents Saturday.
4142
 *  Returns +true+ if _time_ represents Saturday.
4146 4143
 *
4147 4144
 *     t = Time.local(2006, 6, 10)      #=> 2006-06-10 00:00:00 -0500
4148 4145
 *     t.saturday?                      #=> true
......
4179 4176
 *     time.isdst -> true or false
4180 4177
 *     time.dst?  -> true or false
4181 4178
 *
4182
 *  Returns <code>true</code> if <i>time</i> occurs during Daylight
4179
 *  Returns +true+ if _time_ occurs during Daylight
4183 4180
 *  Saving Time in its time zone.
4184 4181
 *
4185 4182
 *   # CST6CDT:
......
4213 4210
 *  call-seq:
4214 4211
 *     time.zone -> string
4215 4212
 *
4216
 *  Returns the name of the time zone used for <i>time</i>. As of Ruby
4213
 *  Returns the name of the time zone used for _time_. As of Ruby
4217 4214
 *  1.8, returns ``UTC'' rather than ``GMT'' for UTC times.
4218 4215
 *
4219 4216
 *     t = Time.gm(2000, "jan", 1, 20, 15, 1)
......
4244 4241
 *     time.gmtoff     -> fixnum
4245 4242
 *     time.utc_offset -> fixnum
4246 4243
 *
4247
 *  Returns the offset in seconds between the timezone of <i>time</i>
4244
 *  Returns the offset in seconds between the timezone of _time_
4248 4245
 *  and UTC.
4249 4246
 *
4250 4247
 *     t = Time.gm(2000,1,1,20,15,1)   #=> 2000-01-01 20:15:01 UTC
......
4273 4270
 *  call-seq:
4274 4271
 *     time.to_a -> array
4275 4272
 *
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
4273
 *  Returns a ten-element _array_ of values for _time_:
4274
 *
4275
 *     [sec, min, hour, day, month, year, wday, yday, isdst, zone]
4276
 *
4277
 *  See the individual methods for an explanation of the
4279 4278
 *  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>.
4279
 *  to Time::utc or Time::local to create a
4280
 *  new Time object.
4282 4281
 *
4283 4282
 *     t = Time.now     #=> 2007-11-19 08:36:01 -0600
4284 4283
 *     now = t.to_a     #=> [1, 36, 8, 19, 11, 2007, 1, 323, false, "CST"]
......
4372 4371
 *  call-seq:
4373 4372
 *     time.strftime( string ) -> string
4374 4373
 *
4375
 *  Formats <i>time</i> according to the directives in the given format
4376
 *  string.
4377
 *  The directives begins with a percent (%) character.
4374
 *  Formats _time_ according to the directives in the given format string.
4375
 *
4376
 *  The directives begin with a percent (%) character.
4378 4377
 *  Any text not listed as a directive will be passed through to the
4379 4378
 *  output string.
4380 4379
 *
4381 4380
 *  The directive consists of a percent (%) character,
4382 4381
 *  zero or more flags, optional minimum field width,
4383 4382
 *  optional modifier and a conversion specifier
4384
 *  as follows.
4383
 *  as follows:
4385 4384
 *
4386 4385
 *    %<flags><width><modifier><conversion>
4387 4386
 *
4388 4387
 *  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.
4388
 *    -  don't pad a numerical output
4389
 *    _  use spaces for padding
4390
 *    0  use zeros for padding
4391
 *    ^  upcase the result string
4392
 *    #  change case
4393
 *    :  use colons for %z
4395 4394
 *
4396 4395
 *  The minimum field width specifies the minimum width.
4397 4396
 *
4398
 *  The modifier is "E" and "O".
4397
 *  The modifiers are "E" and "O".
4399 4398
 *  They are ignored.
4400 4399
 *
4401 4400
 *  Format directives:
......
4849 4848
 * call-seq:
4850 4849
 *   Time._load(string)   -> time
4851 4850
 *
4852
 * Unmarshal a dumped +Time+ object.
4851
 * Unmarshal a dumped Time object.
4853 4852
 */
4854 4853

  
4855 4854
static VALUE
......
4873 4872
 *  with each other -- times that are apparently equal when displayed may be
4874 4873
 *  different when compared.
4875 4874
 *
4876
 *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer, Bignum or Rational.
4875
 *  Since Ruby 1.9.2, Time implementation uses a signed 63 bit integer,
4876
 *  Bignum or Rational.
4877 4877
 *  The integer is a number of nanoseconds since the _Epoch_ which can
4878 4878
 *  represent 1823-11-12 to 2116-02-20.
4879 4879
 *  When Bignum or Rational is used (before 1823, after 2116, under nanosecond),
......
4885 4885
 *
4886 4886
 *  == Creating a new Time instance
4887 4887
 *
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
4888
 *  You can create a new instance of Time with Time::new. This will use the
4889
 *  current system time. Time::now is an alias for this. You can also
4890
 *  pass parts of the time to Time::new such as year, month, minute, etc. When
4891 4891
 *  you want to construct a time this way you must pass at least a year. If you
4892 4892
 *  pass the year with nothing else time with default to January 1 of that year
4893 4893
 *  at 00:00:00 with the current system timezone. Here are some examples:
......
4900 4900
 *  You can also use #gm, #local and #utc to infer GMT, local and UTC
4901 4901
 *  timezones instead of using the current system setting.
4902 4902
 *
4903
 *  You can also create a new time using Time.at which takes the number of
4903
 *  You can also create a new time using Time::at which takes the number of
4904 4904
 *  seconds (or fraction of seconds) since the {Unix
4905 4905
 *  Epoch}[http://en.wikipedia.org/wiki/Unix_time].
4906 4906
 *
......
4908 4908
 *
4909 4909
 *  == Working with an instance of Time
4910 4910
 *
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
4911
 *  Once you have an instance of Time there is a multitude of things you can
4912
 *  do with it. Below are some examples. For all of the following examples, we
4913 4913
 *  will work on the assumption that you have done the following:
4914 4914
 *
4915 4915
 *    t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
4916
-