== Timezone Specifiers

- Time.at: keyword argument +in:+.

- Time.new: positional argument +zone+ or keyword argument +in:+.

* Time.utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time

* Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time

*

* in the UTC timezone.

*

* With one to seven arguments given,

* # => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]

* Time.utc(*a) # => 0005-04-03 02:01:00 UTC

*

* array returned by Time.to_a:

*

* t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006

* Time.local(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) -> new_time

* Time.local(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) -> new_time

*

* has the local timezone, not the UTC timezone:

*

* # With seven arguments.

* eql?(other_time)

*

* Returns +true+ if +self+ and +other_time+ are

*/

static VALUE

* With no argument given:

*

* - Returns +self+ if +self+ is a local time.

*

* t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC

* t.localtime # => 2000-01-01 14:15:01 -0600

*

* With argument +zone+ given,

* +self+ to the given time zone:

*

* t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC

* t.utc # => 2000-01-01 06:00:00 UTC

* t.utc? # => true

*

*/

static VALUE

* call-seq:

* getlocal(zone = nil) -> new_time

*

* converted to a given timezone;

* if +zone+ is +nil+, the local timezone is used:

*

* call-seq:

* getutc -> new_time

*

* converted to the UTC timezone:

*

* local = Time.local(2000) # => 2000-01-01 00:00:00 -0600

* call-seq:

* self + numeric -> new_time

*

* of +self+ and the given +numeric+:

*

* t = Time.new(2000) # => 2000-01-01 00:00:00 -0600

* self - other_time -> float

*

* When +numeric+ is given,

* of the numeric value of +self+ and +numeric+:

*

* t = Time.new(2000) # => 2000-01-01 00:00:00 -0600

* call-seq:

* round(ndigits = 0) -> new_time

*

* with its seconds value rounded to precision +ndigits+:

*

* t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)

* call-seq:

* floor(ndigits = 0) -> new_time

*

* is less than or equal to +self+ with its seconds

* truncated to precision +ndigits+:

*

* call-seq:

* ceil(ndigits = 0) -> new_time

*

* is greater than or equal to +self+ with its seconds

* truncated to precision +ndigits+:

*

* # [sec, min, hour, day, mon, year, wday, yday, dst?, zone]

*

* The returned array is suitable for use as an argument to Time.utc or Time.local

*

*/

#

# Time.new(2000, 1, 1, 0, 0, 0) # => 2000-01-01 00:00:00 -0600

#

#

# == \Time Resolution

#

# (for example, by method Time.now)

# has the resolution supported by the system.

#

#

# All of these examples were done using the EST timezone which is GMT-5.

#

#

# You can create a new instance of Time with Time.new. This will use the

# current system time. Time.now is an alias for this. You can also

#

# Time.at(628232400) #=> 1989-11-28 00:00:00 -0500

#

#

# Once you have an instance of Time there is a multitude of things you can

# do with it. Below are some examples. For all of the following examples, we

#

# == What's Here

#

#

# - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here].

# - Includes {module Comparable}[rdoc-ref:Comparable@What-27s+Here].

#

#

#

# === Methods for Creating

#

#

# :include: doc/_timezones.rdoc

class Time

# This is the same as Time.new without arguments.

#

# Time.now # => 2009-06-24 12:39:54 +0900

Primitive.time_s_now(Primitive.arg!(:in))

end

#

# Required argument +time+ may be either of:

#

# also influenced by optional keyword argument +in:+ (see below).

# - A numeric number of

# {Epoch seconds}[rdoc-ref:Time@Epoch+Seconds]

# call-seq:

# Time.new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9)

#

# by default in the local timezone.

#

# With no positional arguments, returns the value of Time.now:

# Time.new # => 2021-04-24 17:27:46.0512465 -0500

#

# With one string argument that represents a time, returns a new

#

# Time.new('2000-12-31 23:59:59.5') # => 2000-12-31 23:59:59.5 -0600

# Time.new('2000-12-31 23:59:59.5 +0900') # => 2000-12-31 23:59:59.5 +0900

# Time.new('2000-12-31 23:59:59.5') # => 2000-12-31 23:59:59.5 -0600

# Time.new('2000-12-31 23:59:59.56789', precision: 3) # => 2000-12-31 23:59:59.567 -0600

#

# based on the given arguments, in the local timezone.

#

# Time.new(2000, 1, 2, 3, 4, 5) # => 2000-01-02 03:04:05 -0600

# Time.new(*a) # => 0000-01-01 00:00:00 -0600

#

# When positional argument +zone+ or keyword argument +in:+ is given,

# For the forms of argument +zone+, see

# {Timezone Specifiers}[rdoc-ref:Time@Timezone+Specifiers]:

#

# Time.new('2000-01-01 00:00:00 +0100', in: '-0500').utc_offset # => 3600

#

# - +precision+: maximum effective digits in sub-second part, default is 9.

# Ignored unless the first argument is a string.

#

def initialize(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil,