| blob | ad8b16a0e27e52a40556a9f923996324c542600e |
1 # A +Time+ object represents a date and time:
2 #
3 # Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
4 #
5 # Although its value can be expressed as a single numeric
6 # (see {Epoch Seconds}[rdoc-ref:Time@Epoch+Seconds] below),
7 # it can be convenient to deal with the value by parts:
8 #
9 # t = Time.new(-2000, 1, 1, 0, 0, 0.0)
10 # # => -2000-01-01 00:00:00 -0600
11 # t.year # => -2000
12 # t.month # => 1
13 # t.mday # => 1
14 # t.hour # => 0
15 # t.min # => 0
16 # t.sec # => 0
17 # t.subsec # => 0
18 #
19 # t = Time.new(2000, 12, 31, 23, 59, 59.5)
20 # # => 2000-12-31 23:59:59.5 -0600
21 # t.year # => 2000
22 # t.month # => 12
23 # t.mday # => 31
24 # t.hour # => 23
25 # t.min # => 59
26 # t.sec # => 59
27 # t.subsec # => (1/2)
28 #
29 # == Epoch Seconds
30 #
31 # <i>Epoch seconds</i> is the exact number of seconds
32 # (including fractional subseconds) since the Unix Epoch, January 1, 1970.
33 #
34 # You can retrieve that value exactly using method Time.to_r:
35 #
36 # Time.at(0).to_r # => (0/1)
37 # Time.at(0.999999).to_r # => (9007190247541737/9007199254740992)
38 #
39 # Other retrieval methods such as Time#to_i and Time#to_f
40 # may return a value that rounds or truncates subseconds.
41 #
42 # == \Time Resolution
43 #
44 # A +Time+ object derived from the system clock
45 # (for example, by method Time.now)
46 # has the resolution supported by the system.
47 #
48 # == \Time Internal Representation
49 #
50 # Time implementation uses a signed 63 bit integer, Integer(T_BIGNUM), or
51 # Rational.
52 # It is a number of nanoseconds since the _Epoch_.
53 # The signed 63 bit integer can represent 1823-11-12 to 2116-02-20.
54 # When Integer or Rational is used (before 1823, after 2116, under
55 # nanosecond), Time works slower than when the signed 63 bit integer is used.
56 #
57 # Ruby uses the C function "localtime" and "gmtime" to map between the number
58 # and 6-tuple (year,month,day,hour,minute,second).
59 # "localtime" is used for local time and "gmtime" is used for UTC.
60 #
61 # Integer(T_BIGNUM) and Rational has no range limit,
62 # but the localtime and gmtime has range limits
63 # due to the C types "time_t" and "struct tm".
64 # If that limit is exceeded, Ruby extrapolates the localtime function.
65 #
66 # The Time class always uses the Gregorian calendar.
67 # I.e. the proleptic Gregorian calendar is used.
68 # Other calendars, such as Julian calendar, are not supported.
69 #
70 # "time_t" can represent 1901-12-14 to 2038-01-19 if it is 32 bit signed integer,
71 # -292277022657-01-27 to 292277026596-12-05 if it is 64 bit signed integer.
72 # However "localtime" on some platforms doesn't supports negative time_t (before 1970).
73 #
74 # "struct tm" has tm_year member to represent years.
75 # (tm_year = 0 means the year 1900.)
76 # It is defined as int in the C standard.
77 # tm_year can represent between -2147481748 to 2147485547 if int is 32 bit.
78 #
79 # Ruby supports leap seconds as far as if the C function "localtime" and
80 # "gmtime" supports it.
81 # They use the tz database in most Unix systems.
82 # The tz database has timezones which supports leap seconds.
83 # For example, "Asia/Tokyo" doesn't support leap seconds but
84 # "right/Asia/Tokyo" supports leap seconds.
85 # So, Ruby supports leap seconds if the TZ environment variable is
86 # set to "right/Asia/Tokyo" in most Unix systems.
87 #
88 # == Examples
89 #
90 # All of these examples were done using the EST timezone which is GMT-5.
91 #
92 # === Creating a New +Time+ Instance
93 #
94 # You can create a new instance of Time with Time.new. This will use the
95 # current system time. Time.now is an alias for this. You can also
96 # pass parts of the time to Time.new such as year, month, minute, etc. When
97 # you want to construct a time this way you must pass at least a year. If you
98 # pass the year with nothing else time will default to January 1 of that year
99 # at 00:00:00 with the current system timezone. Here are some examples:
100 #
101 # Time.new(2002) #=> 2002-01-01 00:00:00 -0500
102 # Time.new(2002, 10) #=> 2002-10-01 00:00:00 -0500
103 # Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500
104 #
105 # You can pass a UTC offset:
106 #
107 # Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200
108 #
109 # Or {a timezone object}[rdoc-ref:Time@Timezone+Objects]:
110 #
111 # zone = timezone("Europe/Athens") # Eastern European Time, UTC+2
112 # Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200
113 #
114 # You can also use Time.local and Time.utc to infer
115 # local and UTC timezones instead of using the current system
116 # setting.
117 #
118 # You can also create a new time using Time.at which takes the number of
119 # seconds (with subsecond) since the {Unix
120 # Epoch}[https://en.wikipedia.org/wiki/Unix_time].
121 #
122 # Time.at(628232400) #=> 1989-11-28 00:00:00 -0500
123 #
124 # === Working with an Instance of +Time+
125 #
126 # Once you have an instance of Time there is a multitude of things you can
127 # do with it. Below are some examples. For all of the following examples, we
128 # will work on the assumption that you have done the following:
129 #
130 # t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")
131 #
132 # Was that a monday?
133 #
134 # t.monday? #=> false
135 #
136 # What year was that again?
137 #
138 # t.year #=> 1993
139 #
140 # Was it daylight savings at the time?
141 #
142 # t.dst? #=> false
143 #
144 # What's the day a year later?
145 #
146 # t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900
147 #
148 # How many seconds was that since the Unix Epoch?
149 #
150 # t.to_i #=> 730522800
151 #
152 # You can also do standard functions like compare two times.
153 #
154 # t1 = Time.new(2010)
155 # t2 = Time.new(2011)
156 #
157 # t1 == t2 #=> false
158 # t1 == t1 #=> true
159 # t1 < t2 #=> true
160 # t1 > t2 #=> false
161 #
162 # Time.new(2010,10,31).between?(t1, t2) #=> true
163 #
164 # == What's Here
165 #
166 # First, what's elsewhere. \Class +Time+:
167 #
168 # - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].
169 # - Includes {module Comparable}[rdoc-ref:Comparable@What-27s+Here].
170 #
171 # Here, class +Time+ provides methods that are useful for:
172 #
173 # - {Creating +Time+ objects}[rdoc-ref:Time@Methods+for+Creating].
174 # - {Fetching +Time+ values}[rdoc-ref:Time@Methods+for+Fetching].
175 # - {Querying a +Time+ object}[rdoc-ref:Time@Methods+for+Querying].
176 # - {Comparing +Time+ objects}[rdoc-ref:Time@Methods+for+Comparing].
177 # - {Converting a +Time+ object}[rdoc-ref:Time@Methods+for+Converting].
178 # - {Rounding a +Time+}[rdoc-ref:Time@Methods+for+Rounding].
179 #
180 # === Methods for Creating
181 #
182 # - ::new: Returns a new time from specified arguments (year, month, etc.),
183 # including an optional timezone value.
184 # - ::local (aliased as ::mktime): Same as ::new, except the
185 # timezone is the local timezone.
186 # - ::utc (aliased as ::gm): Same as ::new, except the timezone is UTC.
187 # - ::at: Returns a new time based on seconds since epoch.
188 # - ::now: Returns a new time based on the current system time.
189 # - #+ (plus): Returns a new time increased by the given number of seconds.
190 # - #- (minus): Returns a new time decreased by the given number of seconds.
191 #
192 # === Methods for Fetching
193 #
194 # - #year: Returns the year of the time.
195 # - #month (aliased as #mon): Returns the month of the time.
196 # - #mday (aliased as #day): Returns the day of the month.
197 # - #hour: Returns the hours value for the time.
198 # - #min: Returns the minutes value for the time.
199 # - #sec: Returns the seconds value for the time.
200 # - #usec (aliased as #tv_usec): Returns the number of microseconds
201 # in the subseconds value of the time.
202 # - #nsec (aliased as #tv_nsec: Returns the number of nanoseconds
203 # in the subsecond part of the time.
204 # - #subsec: Returns the subseconds value for the time.
205 # - #wday: Returns the integer weekday value of the time (0 == Sunday).
206 # - #yday: Returns the integer yearday value of the time (1 == January 1).
207 # - #hash: Returns the integer hash value for the time.
208 # - #utc_offset (aliased as #gmt_offset and #gmtoff): Returns the offset
209 # in seconds between time and UTC.
210 # - #to_f: Returns the float number of seconds since epoch for the time.
211 # - #to_i (aliased as #tv_sec): Returns the integer number of seconds since epoch
212 # for the time.
213 # - #to_r: Returns the Rational number of seconds since epoch for the time.
214 # - #zone: Returns a string representation of the timezone of the time.
215 #
216 # === Methods for Querying
217 #
218 # - #utc? (aliased as #gmt?): Returns whether the time is UTC.
219 # - #dst? (aliased as #isdst): Returns whether the time is DST (daylight saving time).
220 # - #sunday?: Returns whether the time is a Sunday.
221 # - #monday?: Returns whether the time is a Monday.
222 # - #tuesday?: Returns whether the time is a Tuesday.
223 # - #wednesday?: Returns whether the time is a Wednesday.
224 # - #thursday?: Returns whether the time is a Thursday.
225 # - #friday?: Returns whether time is a Friday.
226 # - #saturday?: Returns whether the time is a Saturday.
227 #
228 # === Methods for Comparing
229 #
230 # - #<=>: Compares +self+ to another time.
231 # - #eql?: Returns whether the time is equal to another time.
232 #
233 # === Methods for Converting
234 #
235 # - #asctime (aliased as #ctime): Returns the time as a string.
236 # - #inspect: Returns the time in detail as a string.
237 # - #strftime: Returns the time as a string, according to a given format.
238 # - #to_a: Returns a 10-element array of values from the time.
239 # - #to_s: Returns a string representation of the time.
240 # - #getutc (aliased as #getgm): Returns a new time converted to UTC.
241 # - #getlocal: Returns a new time converted to local time.
242 # - #utc (aliased as #gmtime): Converts time to UTC in place.
243 # - #localtime: Converts time to local time in place.
244 # - #deconstruct_keys: Returns a hash of time components used in pattern-matching.
245 #
246 # === Methods for Rounding
247 #
248 # - #round:Returns a new time with subseconds rounded.
249 # - #ceil: Returns a new time with subseconds raised to a ceiling.
250 # - #floor: Returns a new time with subseconds lowered to a floor.
251 #
252 # For the forms of argument +zone+, see
253 # {Timezone Specifiers}[rdoc-ref:Time@Timezone+Specifiers].
254 #
255 # :include: doc/_timezones.rdoc
256 class Time
257 # Creates a new +Time+ object from the current system time.
258 # This is the same as Time.new without arguments.
259 #
260 # Time.now # => 2009-06-24 12:39:54 +0900
261 # Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400
262 #
263 # For forms of argument +zone+, see
264 # {Timezone Specifiers}[rdoc-ref:Time@Timezone+Specifiers].
265 def self.now(in: nil)
266 Primitive.time_s_now(Primitive.arg!(:in))
267 end
269 # Returns a new +Time+ object based on the given arguments.
270 #
271 # Required argument +time+ may be either of:
272 #
273 # - A +Time+ object, whose value is the basis for the returned time;
274 # also influenced by optional keyword argument +in:+ (see below).
275 # - A numeric number of
276 # {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]
277 # for the returned time.
278 #
279 # Examples:
280 #
281 # t = Time.new(2000, 12, 31, 23, 59, 59) # => 2000-12-31 23:59:59 -0600
282 # secs = t.to_i # => 978328799
283 # Time.at(secs) # => 2000-12-31 23:59:59 -0600
284 # Time.at(secs + 0.5) # => 2000-12-31 23:59:59.5 -0600
285 # Time.at(1000000000) # => 2001-09-08 20:46:40 -0500
286 # Time.at(0) # => 1969-12-31 18:00:00 -0600
287 # Time.at(-1000000000) # => 1938-04-24 17:13:20 -0500
288 #
289 # Optional numeric argument +subsec+ and optional symbol argument +units+
290 # work together to specify subseconds for the returned time;
291 # argument +units+ specifies the units for +subsec+:
292 #
293 # - +:millisecond+: +subsec+ in milliseconds:
294 #
295 # Time.at(secs, 0, :millisecond) # => 2000-12-31 23:59:59 -0600
296 # Time.at(secs, 500, :millisecond) # => 2000-12-31 23:59:59.5 -0600
297 # Time.at(secs, 1000, :millisecond) # => 2001-01-01 00:00:00 -0600
298 # Time.at(secs, -1000, :millisecond) # => 2000-12-31 23:59:58 -0600
299 #
300 # - +:microsecond+ or +:usec+: +subsec+ in microseconds:
301 #
302 # Time.at(secs, 0, :microsecond) # => 2000-12-31 23:59:59 -0600
303 # Time.at(secs, 500000, :microsecond) # => 2000-12-31 23:59:59.5 -0600
304 # Time.at(secs, 1000000, :microsecond) # => 2001-01-01 00:00:00 -0600
305 # Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600
306 #
307 # - +:nanosecond+ or +:nsec+: +subsec+ in nanoseconds:
308 #
309 # Time.at(secs, 0, :nanosecond) # => 2000-12-31 23:59:59 -0600
310 # Time.at(secs, 500000000, :nanosecond) # => 2000-12-31 23:59:59.5 -0600
311 # Time.at(secs, 1000000000, :nanosecond) # => 2001-01-01 00:00:00 -0600
312 # Time.at(secs, -1000000000, :nanosecond) # => 2000-12-31 23:59:58 -0600
313 #
314 #
315 # Optional keyword argument <tt>in: zone</tt> specifies the timezone
316 # for the returned time:
317 #
318 # Time.at(secs, in: '+12:00') # => 2001-01-01 17:59:59 +1200
319 # Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200
320 #
321 # For the forms of argument +zone+, see
322 # {Timezone Specifiers}[rdoc-ref:Time@Timezone+Specifiers].
323 #
324 def self.at(time, subsec = false, unit = :microsecond, in: nil)
325 if Primitive.mandatory_only?
326 Primitive.time_s_at1(time)
327 else
328 Primitive.time_s_at(time, subsec, unit, Primitive.arg!(:in))
329 end
330 end
332 # call-seq:
333 # Time.new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9)
334 #
335 # Returns a new +Time+ object based on the given arguments,
336 # by default in the local timezone.
337 #
338 # With no positional arguments, returns the value of Time.now:
339 #
340 # Time.new # => 2021-04-24 17:27:46.0512465 -0500
341 #
342 # With one string argument that represents a time, returns a new
343 # +Time+ object based on the given argument, in the local timezone.
344 #
345 # Time.new('2000-12-31 23:59:59.5') # => 2000-12-31 23:59:59.5 -0600
346 # Time.new('2000-12-31 23:59:59.5 +0900') # => 2000-12-31 23:59:59.5 +0900
347 # Time.new('2000-12-31 23:59:59.5', in: '+0900') # => 2000-12-31 23:59:59.5 +0900
348 # Time.new('2000-12-31 23:59:59.5') # => 2000-12-31 23:59:59.5 -0600
349 # Time.new('2000-12-31 23:59:59.56789', precision: 3) # => 2000-12-31 23:59:59.567 -0600
350 #
351 # With one to six arguments, returns a new +Time+ object
352 # based on the given arguments, in the local timezone.
353 #
354 # Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600
355 #
356 # For the positional arguments (other than +zone+):
357 #
358 # - +year+: Year, with no range limits:
359 #
360 # Time.new(999999999) # => 999999999-01-01 00:00:00 -0600
361 # Time.new(-999999999) # => -999999999-01-01 00:00:00 -0600
362 #
363 # - +month+: Month in range (1..12), or case-insensitive
364 # 3-letter month name:
365 #
366 # Time.new(2000, 1) # => 2000-01-01 00:00:00 -0600
367 # Time.new(2000, 12) # => 2000-12-01 00:00:00 -0600
368 # Time.new(2000, 'jan') # => 2000-01-01 00:00:00 -0600
369 # Time.new(2000, 'JAN') # => 2000-01-01 00:00:00 -0600
370 #
371 # - +mday+: Month day in range(1..31):
372 #
373 # Time.new(2000, 1, 1) # => 2000-01-01 00:00:00 -0600
374 # Time.new(2000, 1, 31) # => 2000-01-31 00:00:00 -0600
375 #
376 # - +hour+: Hour in range (0..23), or 24 if +min+, +sec+, and +usec+
377 # are zero:
378 #
379 # Time.new(2000, 1, 1, 0) # => 2000-01-01 00:00:00 -0600
380 # Time.new(2000, 1, 1, 23) # => 2000-01-01 23:00:00 -0600
381 # Time.new(2000, 1, 1, 24) # => 2000-01-02 00:00:00 -0600
382 #
383 # - +min+: Minute in range (0..59):
384 #
385 # Time.new(2000, 1, 1, 0, 0) # => 2000-01-01 00:00:00 -0600
386 # Time.new(2000, 1, 1, 0, 59) # => 2000-01-01 00:59:00 -0600
387 #
388 # - +sec+: Second in range (0...61):
389 #
390 # Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600
391 # Time.new(2000, 1, 1, 0, 0, 59) # => 2000-01-01 00:00:59 -0600
392 # Time.new(2000, 1, 1, 0, 0, 60) # => 2000-01-01 00:01:00 -0600
393 #
394 # +sec+ may be Float or Rational.
395 #
396 # Time.new(2000, 1, 1, 0, 0, 59.5) # => 2000-12-31 23:59:59.5 +0900
397 # Time.new(2000, 1, 1, 0, 0, 59.7r) # => 2000-12-31 23:59:59.7 +0900
398 #
399 # These values may be:
400 #
401 # - Integers, as above.
402 # - Numerics convertible to integers:
403 #
404 # Time.new(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0)
405 # # => 0000-01-01 00:00:00 -0600
406 #
407 # - String integers:
408 #
409 # a = %w[0 1 1 0 0 0]
410 # # => ["0", "1", "1", "0", "0", "0"]
411 # Time.new(*a) # => 0000-01-01 00:00:00 -0600
412 #
413 # When positional argument +zone+ or keyword argument +in:+ is given,
414 # the new +Time+ object is in the specified timezone.
415 # For the forms of argument +zone+, see
416 # {Timezone Specifiers}[rdoc-ref:Time@Timezone+Specifiers]:
417 #
418 # Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
419 # # => 2000-01-01 00:00:00 +1200
420 # Time.new(2000, 1, 1, 0, 0, 0, in: '-12:00')
421 # # => 2000-01-01 00:00:00 -1200
422 # Time.new(in: '-12:00')
423 # # => 2022-08-23 08:49:26.1941467 -1200
424 #
425 # Since +in:+ keyword argument just provides the default, so if the
426 # first argument in single string form contains time zone information,
427 # this keyword argument will be silently ignored.
428 #
429 # Time.new('2000-01-01 00:00:00 +0100', in: '-0500').utc_offset # => 3600
430 #
431 # - +precision+: maximum effective digits in sub-second part, default is 9.
432 # More digits will be truncated, as other operations of +Time+.
433 # Ignored unless the first argument is a string.
434 #
435 def initialize(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil,
436 in: nil, precision: 9)
437 if zone
438 if Primitive.arg!(:in)
439 raise ArgumentError, "timezone argument given as positional and keyword arguments"
440 end
441 else
442 zone = Primitive.arg!(:in)
443 end
445 if now
446 return Primitive.time_init_now(zone)
447 end
449 if str and Primitive.time_init_parse(str, zone, precision)
450 return self
451 end
453 Primitive.time_init_args(year, mon, mday, hour, min, sec, zone)
454 end
455 end