class method

Time.new

(?::Integer year, ?::Integer? month, ?::Integer? day, ?::Integer? hour, ?::Integer? min, ?::Numeric? sec, ?::String | ::Integer | nil) -> ::Time

(?::Integer year, ?::Integer? month, ?::Integer? day, ?::Integer? hour, ?::Integer? min, ?::Numeric? sec, in: ::String | ::Integer | nil) -> ::Time

(::String, ?in: ::string | ::int | nil, ?precision: ::int) -> ::Time

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

timev.rb View on GitHub ↗

# File tmp/rubies/ruby-4.0.0/timev.rb, line 440
def initialize(year = (now = true), mon = (str = year; nil), mday = nil, hour = nil, min = nil, sec = nil, zone = nil,
               in: nil, precision: 9)
  if zone
    if Primitive.arg!(:in)
      raise ArgumentError, "timezone argument given as positional and keyword arguments"
    end
  else
    zone = Primitive.arg!(:in)
  end

  if now
    return Primitive.time_init_now(zone)
  end

  if str and Primitive.time_init_parse(str, zone, precision)
    return self
  end

  Primitive.time_init_args(year, mon, mday, hour, min, sec, zone)
end

Returns a new Time object based on the given arguments, by default in the local timezone.

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

Example

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

With one string argument that represents a time, returns a new Time object based on the given argument, in the local timezone.

Example

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', in: '+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

With one to six arguments, returns a new Time object based on the given arguments, in the local timezone.

Example

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

For the positional arguments (other than zone):

year: Year, with no range limits:

Example

Time.new(999999999)  # => 999999999-01-01 00:00:00 -0600
Time.new(-999999999) # => -999999999-01-01 00:00:00 -0600

month: Month in range (1..12), or case-insensitive 3-letter month name:

Example

Time.new(2000, 1)     # => 2000-01-01 00:00:00 -0600
Time.new(2000, 12)    # => 2000-12-01 00:00:00 -0600
Time.new(2000, 'jan') # => 2000-01-01 00:00:00 -0600
Time.new(2000, 'JAN') # => 2000-01-01 00:00:00 -0600

mday: Month day in range(1..31):

Example

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

hour: Hour in range (0..23), or 24 if min, sec, and usec are zero:

Example

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

min: Minute in range (0..59):

Example

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

sec: Second in range (0…61):

Example

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

sec may be Float or Rational.

Example

Time.new(2000, 1, 1, 0, 0, 59.5)  # => 2000-12-31 23:59:59.5 +0900
Time.new(2000, 1, 1, 0, 0, 59.7r) # => 2000-12-31 23:59:59.7 +0900

These values may be:

Integers, as above.

Numerics convertible to integers:

Example

Time.new(Float(0.0), Rational(1, 1), 1.0, 0.0, 0.0, 0.0)
# => 0000-01-01 00:00:00 -0600

String integers:

Example

a = %w[0 1 1 0 0 0]
# => ["0", "1", "1", "0", "0", "0"]
Time.new(*a) # => 0000-01-01 00:00:00 -0600

When positional argument zone or keyword argument in: is given, the new Time object is in the specified timezone. For the forms of argument zone, see Timezone Specifiers:

Example

Time.new(2000, 1, 1, 0, 0, 0, '+12:00')
# => 2000-01-01 00:00:00 +1200
Time.new(2000, 1, 1, 0, 0, 0, in: '-12:00')
# => 2000-01-01 00:00:00 -1200
Time.new(in: '-12:00')
# => 2022-08-23 08:49:26.1941467 -1200

Since in: keyword argument just provides the default, so if the first argument in single string form contains time zone information, this keyword argument will be silently ignored.

Example

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. More digits will be truncated, as other operations of Time. Ignored unless the first argument is a string.

Ruby version changes

3.3
- Time.new with a string argument became stricter. [Bug #19293]
  
  Example
```
Time.new('2023-12-20')
#  no time information (ArgumentError)
```
3.2
- Time.new now can parse a string like generated by Time#inspect and return a Time instance based on the given argument. [Feature #18033]
3.1
- Time.new now accepts optional in: keyword argument for the timezone, as well as Time.at and Time.now, so that is now you can omit minor arguments to Time.new. [Feature #17485]
  
  Example
```
Time.new(2021, 12, 25, in: "+07:00")
#=> 2021-12-25 00:00:00 +0700
```
  At the same time, time component strings are converted to integers more strictly now.
  
  Example
```
Time.new(2021, 12, 25, "+07:30")
#=> invalid value for Integer(): "+07:30" (ArgumentError)
```
  Ruby 3.0 or earlier returned probably unexpected result 2021-12-25 07:00:00, not 2021-12-25 07:30:00 nor 2021-12-25 00:00:00 +07:30.

See also .mktime .now .local .parse also in 4.1 · 3.4 · 3.3 · 3.2 · 3.1 · 3.0

‹ prev.mktime next ›.now