class Time

Returns a new Time object based on the given arguments.

Required argument time may be either of:

• A Time object, whose value is the basis for the returned time; also influenced by optional keyword argument in: (see below).

• A numeric number of Epoch seconds for the returned time.

Examples:

t = Time.new(2000, 12, 31, 23, 59, 59) # => 2000-12-31 23:59:59 -0600
secs = t.to_i                          # => 978328799
Time.at(secs)                          # => 2000-12-31 23:59:59 -0600
Time.at(secs + 0.5)                    # => 2000-12-31 23:59:59.5 -0600
Time.at(1000000000)                    # => 2001-09-08 20:46:40 -0500
Time.at(0)                             # => 1969-12-31 18:00:00 -0600
Time.at(-1000000000)                   # => 1938-04-24 17:13:20 -0500

Optional numeric argument subsec and optional symbol argument units work together to specify subseconds for the returned time; argument units specifies the units for subsec:

• :millisecond: subsec in milliseconds:

  Time.at(secs, 0, :millisecond)     # => 2000-12-31 23:59:59 -0600
  Time.at(secs, 500, :millisecond)   # => 2000-12-31 23:59:59.5 -0600
  Time.at(secs, 1000, :millisecond)  # => 2001-01-01 00:00:00 -0600
  Time.at(secs, -1000, :millisecond) # => 2000-12-31 23:59:58 -0600
  

• :microsecond or :usec: subsec in microseconds:

  Time.at(secs, 0, :microsecond)        # => 2000-12-31 23:59:59 -0600
  Time.at(secs, 500000, :microsecond)   # => 2000-12-31 23:59:59.5 -0600
  Time.at(secs, 1000000, :microsecond)  # => 2001-01-01 00:00:00 -0600
  Time.at(secs, -1000000, :microsecond) # => 2000-12-31 23:59:58 -0600
  

• :nanosecond or :nsec: subsec in nanoseconds:

  Time.at(secs, 0, :nanosecond)           # => 2000-12-31 23:59:59 -0600
  Time.at(secs, 500000000, :nanosecond)   # => 2000-12-31 23:59:59.5 -0600
  Time.at(secs, 1000000000, :nanosecond)  # => 2001-01-01 00:00:00 -0600
  Time.at(secs, -1000000000, :nanosecond) # => 2000-12-31 23:59:58 -0600
  

Optional keyword argument +in: zone specifies the timezone for the returned time:

Time.at(secs, in: '+12:00') # => 2001-01-01 17:59:59 +1200
Time.at(secs, in: '-12:00') # => 2000-12-31 17:59:59 -1200

For the forms of argument zone, see Timezone Specifiers.

# File ruby_3_2_3/timev.rb, line 282
def self.at(time, subsec = false, unit = :microsecond, in: nil)
  if Primitive.mandatory_only?
    Primitive.time_s_at1(time)
  else
    Primitive.time_s_at(time, subsec, unit, Primitive.arg!(:in))
  end
end

Like Time.utc, except that the returned Time object has the local timezone, not the UTC timezone:

# With seven arguments.
Time.local(0, 1, 2, 3, 4, 5, 6)
# => 0000-01-02 03:04:05.000006 -0600
# With exactly ten arguments.
Time.local(0, 1, 2, 3, 4, 5, 6, 7, 8, 9)
# => 0005-04-03 02:01:00 -0600

static VALUE
time_s_mktime(int argc, VALUE *argv, VALUE klass)
{
    struct vtm vtm;

    time_arg(argc, argv, &vtm);
    return time_localtime(time_new_timew(klass, timelocalw(&vtm)));
}

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:

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.

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.

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:

  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:

  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):

  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:

  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):

  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):

  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.

  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:

  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:

  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:

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

• 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.

# File ruby_3_2_3/timev.rb, line 384
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

Creates a new Time object from the current system time. This is the same as Time.new without arguments.

Time.now               # => 2009-06-24 12:39:54 +0900
Time.now(in: '+04:00') # => 2009-06-24 07:39:54 +0400

For forms of argument zone, see Timezone Specifiers.

# File ruby_3_2_3/timev.rb, line 223
def self.now(in: nil)
  Primitive.time_s_now(Primitive.arg!(:in))
end

Returns a new Time object based the on given arguments, in the UTC timezone.

With one to seven arguments given, the arguments are interpreted as in the first calling sequence above:

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

Examples:

Time.utc(2000)  # => 2000-01-01 00:00:00 UTC
Time.utc(-2000) # => -2000-01-01 00:00:00 UTC

There are no minimum and maximum values for the required argument year.

For the optional arguments:

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

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

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

  Time.utc(2000, 1, 1)  # => 2000-01-01 00:00:00 UTC
  Time.utc(2000, 1, 31) # => 2000-01-31 00:00:00 UTC
  

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

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

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

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

• sec: Second in range (0..59), or 60 if usec is zero:

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

• usec: Microsecond in range (0..999999):

  Time.utc(2000, 1, 1, 0, 0, 0, 0)      # => 2000-01-01 00:00:00 UTC
  Time.utc(2000, 1, 1, 0, 0, 0, 999999) # => 2000-01-01 00:00:00.999999 UTC
  

The values may be:

• Integers, as above.

• Numerics convertible to integers:

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

• String integers:

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

When exactly ten arguments are given, the arguments are interpreted as in the second calling sequence above:

Time.utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy)

where the dummy arguments are ignored:

a = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
# => [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Time.utc(*a) # => 0005-04-03 02:01:00 UTC

This form is useful for creating a Time object from a 10-element array returned by Time.to_a:

t = Time.new(2000, 1, 2, 3, 4, 5, 6) # => 2000-01-02 03:04:05 +000006
a = t.to_a   # => [5, 4, 3, 2, 1, 2000, 0, 2, false, nil]
Time.utc(*a) # => 2000-01-02 03:04:05 UTC

The two forms have their first six arguments in common, though in different orders; the ranges of these common arguments are the same for both forms; see above.

Raises an exception if the number of arguments is eight, nine, or greater than ten.

Time.gm is an alias for Time.utc.

Related: Time.local.

static VALUE
time_s_mkutc(int argc, VALUE *argv, VALUE klass)
{
    struct vtm vtm;

    time_arg(argc, argv, &vtm);
    return time_gmtime(time_new_timew(klass, timegmw(&vtm)));
}

Returns a new Time object whose value is the sum of the numeric value of self and the given numeric:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t + (60 * 60 * 24) # => 2000-01-02 00:00:00 -0600
t + 0.5            # => 2000-01-01 00:00:00.5 -0600

Related: Time#-.

static VALUE
time_plus(VALUE time1, VALUE time2)
{
    struct time_object *tobj;
    GetTimeval(time1, tobj);

    if (IsTimeval(time2)) {
        rb_raise(rb_eTypeError, "time + time?");
    }
    return time_add(tobj, time1, time2, 1);
}

When numeric is given, returns a new Time object whose value is the difference of the numeric value of self and numeric:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t - (60 * 60 * 24) # => 1999-12-31 00:00:00 -0600
t - 0.5            # => 1999-12-31 23:59:59.5 -0600

When other_time is given, returns a Float whose value is the difference of the numeric values of self and other_time:

t - t # => 0.0

Related: Time#+.

static VALUE
time_minus(VALUE time1, VALUE time2)
{
    struct time_object *tobj;

    GetTimeval(time1, tobj);
    if (IsTimeval(time2)) {
        struct time_object *tobj2;

        GetTimeval(time2, tobj2);
        return rb_Float(rb_time_unmagnify_to_float(wsub(tobj->timew, tobj2->timew)));
    }
    return time_add(tobj, time1, time2, -1);
}

Compares self with other_time; returns:

• -1, if self is less than other_time.

• 0, if self is equal to other_time.

• 1, if self is greater then other_time.

• nil, if self and other_time are incomparable.

Examples:

t = Time.now     # => 2007-11-19 08:12:12 -0600
t2 = t + 2592000 # => 2007-12-19 08:12:12 -0600
t <=> t2         # => -1
t2 <=> t         # => 1

t = Time.now     # => 2007-11-19 08:13:38 -0600
t2 = t + 0.1     # => 2007-11-19 08:13:38 -0600
t.nsec           # => 98222999
t2.nsec          # => 198222999
t <=> t2         # => -1
t2 <=> t         # => 1
t <=> t          # => 0

static VALUE
time_cmp(VALUE time1, VALUE time2)
{
    struct time_object *tobj1, *tobj2;
    int n;

    GetTimeval(time1, tobj1);
    if (IsTimeval(time2)) {
        GetTimeval(time2, tobj2);
        n = wcmp(tobj1->timew, tobj2->timew);
    }
    else {
        return rb_invcmp(time1, time2);
    }
    if (n == 0) return INT2FIX(0);
    if (n > 0) return INT2FIX(1);
    return INT2FIX(-1);
}

Returns a new Time object whose numerical value is greater than or equal to self with its seconds truncated to precision ndigits:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t          # => 2010-03-30 05:43:25.123456789 UTC
t.ceil     # => 2010-03-30 05:43:26 UTC
t.ceil(2)  # => 2010-03-30 05:43:25.13 UTC
t.ceil(4)  # => 2010-03-30 05:43:25.1235 UTC
t.ceil(6)  # => 2010-03-30 05:43:25.123457 UTC
t.ceil(8)  # => 2010-03-30 05:43:25.12345679 UTC
t.ceil(10) # => 2010-03-30 05:43:25.123456789 UTC

t = Time.utc(1999, 12, 31, 23, 59, 59)
t              # => 1999-12-31 23:59:59 UTC
(t + 0.4).ceil # => 2000-01-01 00:00:00 UTC
(t + 0.9).ceil # => 2000-01-01 00:00:00 UTC
(t + 1.4).ceil # => 2000-01-01 00:00:01 UTC
(t + 1.9).ceil # => 2000-01-01 00:00:01 UTC

Related: Time#floor, Time#round.

static VALUE
time_ceil(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    if (!rb_equal(v, INT2FIX(0))) {
        v = subv(den, v);
    }
    return time_add(tobj, time, v, 1);
}

Returns a string representation of self, formatted by strftime('%a %b %e %T %Y') or its shorthand version strftime('%c'); see Formats for Dates and Times:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.ctime                      # => "Sun Dec 31 23:59:59 2000"
t.strftime('%a %b %e %T %Y') # => "Sun Dec 31 23:59:59 2000"
t.strftime('%c')             # => "Sun Dec 31 23:59:59 2000"

Time#asctime is an alias for Time#ctime.

Related: Time#to_s, Time#inspect:

t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
t.to_s                       # => "2000-12-31 23:59:59 +0000"

static VALUE
time_asctime(VALUE time)
{
    return strftimev("%a %b %e %T %Y", time, rb_usascii_encoding());
}

Returns a hash of the name/value pairs, to use in pattern matching. Possible keys are: :year, :month, :day, :yday, :wday, :hour, :min, :sec, :subsec, :dst, :zone.

Possible usages:

t = Time.utc(2022, 10, 5, 21, 25, 30)

if t in wday: 3, day: ..7  # uses deconstruct_keys underneath
  puts "first Wednesday of the month"
end
#=> prints "first Wednesday of the month"

case t
in year: ...2022
  puts "too old"
in month: ..9
  puts "quarter 1-3"
in wday: 1..5, month:
  puts "working day in month #{month}"
end
#=> prints "working day in month 10"

Note that deconstruction by pattern can also be combined with class check:

if t in Time(wday: 3, day: ..7)
  puts "first Wednesday of the month"
end

static VALUE
time_deconstruct_keys(VALUE time, VALUE keys)
{
    struct time_object *tobj;
    VALUE h;
    long i;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);

    if (NIL_P(keys)) {
        h = rb_hash_new_with_size(11);

        rb_hash_aset(h, sym_year, tobj->vtm.year);
        rb_hash_aset(h, sym_month, INT2FIX(tobj->vtm.mon));
        rb_hash_aset(h, sym_day, INT2FIX(tobj->vtm.mday));
        rb_hash_aset(h, sym_yday, INT2FIX(tobj->vtm.yday));
        rb_hash_aset(h, sym_wday, INT2FIX(tobj->vtm.wday));
        rb_hash_aset(h, sym_hour, INT2FIX(tobj->vtm.hour));
        rb_hash_aset(h, sym_min, INT2FIX(tobj->vtm.min));
        rb_hash_aset(h, sym_sec, INT2FIX(tobj->vtm.sec));
        rb_hash_aset(h, sym_subsec,
                     quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE)));
        rb_hash_aset(h, sym_dst, RBOOL(tobj->vtm.isdst));
        rb_hash_aset(h, sym_zone, time_zone(time));

        return h;
    }
    if (UNLIKELY(!RB_TYPE_P(keys, T_ARRAY))) {
        rb_raise(rb_eTypeError,
                 "wrong argument type %"PRIsVALUE" (expected Array or nil)",
                 rb_obj_class(keys));

    }

    h = rb_hash_new_with_size(RARRAY_LEN(keys));

    for (i=0; i<RARRAY_LEN(keys); i++) {
        VALUE key = RARRAY_AREF(keys, i);

        if (sym_year == key) rb_hash_aset(h, key, tobj->vtm.year);
        if (sym_month == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.mon));
        if (sym_day == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.mday));
        if (sym_yday == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.yday));
        if (sym_wday == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.wday));
        if (sym_hour == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.hour));
        if (sym_min == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.min));
        if (sym_sec == key) rb_hash_aset(h, key, INT2FIX(tobj->vtm.sec));
        if (sym_subsec == key) {
            rb_hash_aset(h, key, quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE)));
        }
        if (sym_dst == key) rb_hash_aset(h, key, RBOOL(tobj->vtm.isdst));
        if (sym_zone == key) rb_hash_aset(h, key, time_zone(time));
    }
    return h;
}

Returns true if self and other_time are both Time objects with the exact same time value.

static VALUE
time_eql(VALUE time1, VALUE time2)
{
    struct time_object *tobj1, *tobj2;

    GetTimeval(time1, tobj1);
    if (IsTimeval(time2)) {
        GetTimeval(time2, tobj2);
        return rb_equal(w2v(tobj1->timew), w2v(tobj2->timew));
    }
    return Qfalse;
}

Returns a new Time object whose numerical value is less than or equal to self with its seconds truncated to precision ndigits:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t           # => 2010-03-30 05:43:25.123456789 UTC
t.floor     # => 2010-03-30 05:43:25 UTC
t.floor(2)  # => 2010-03-30 05:43:25.12 UTC
t.floor(4)  # => 2010-03-30 05:43:25.1234 UTC
t.floor(6)  # => 2010-03-30 05:43:25.123456 UTC
t.floor(8)  # => 2010-03-30 05:43:25.12345678 UTC
t.floor(10) # => 2010-03-30 05:43:25.123456789 UTC

t = Time.utc(1999, 12, 31, 23, 59, 59)
t               # => 1999-12-31 23:59:59 UTC
(t + 0.4).floor # => 1999-12-31 23:59:59 UTC
(t + 0.9).floor # => 1999-12-31 23:59:59 UTC
(t + 1.4).floor # => 2000-01-01 00:00:00 UTC
(t + 1.9).floor # => 2000-01-01 00:00:00 UTC

Related: Time#ceil, Time#round.

static VALUE
time_floor(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    return time_add(tobj, time, v, -1);
}

Returns true if self represents a Friday, false otherwise:

t = Time.utc(2000, 1, 7) # => 2000-01-07 00:00:00 UTC
t.friday?                # => true

Related: Time#saturday?, Time#sunday?, Time#monday?.

static VALUE
time_friday(VALUE time)
{
    wday_p(5);
}

Returns a new Time object representing the value of self converted to the UTC timezone:

local = Time.local(2000) # => 2000-01-01 00:00:00 -0600
local.utc?               # => false
utc = local.getutc       # => 2000-01-01 06:00:00 UTC
utc.utc?                 # => true
utc == local             # => true

Time#getgm is an alias for Time#getutc.

static VALUE
time_getgmtime(VALUE time)
{
    return time_gmtime(time_dup(time));
}

Returns a new Time object representing the value of self converted to a given timezone; if zone is nil, the local timezone is used:

t = Time.utc(2000)                    # => 2000-01-01 00:00:00 UTC
t.getlocal                            # => 1999-12-31 18:00:00 -0600
t.getlocal('+12:00')                  # => 2000-01-01 12:00:00 +1200

For forms of argument zone, see Timezone Specifiers.

static VALUE
time_getlocaltime(int argc, VALUE *argv, VALUE time)
{
    VALUE off;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(off = argv[0])) {
        VALUE zone = off;
        if (maybe_tzobj_p(zone)) {
            VALUE t = time_dup(time);
            if (zone_localtime(off, t)) return t;
        }

        if (NIL_P(off = utc_offset_arg(off))) {
            off = zone;
            if (NIL_P(zone = find_timezone(time, off))) invalid_utc_offset(off);
            time = time_dup(time);
            if (!zone_localtime(zone, time)) invalid_utc_offset(off);
            return time;
        }
        else if (off == UTC_ZONE) {
            return time_gmtime(time_dup(time));
        }
        validate_utc_offset(off);

        time = time_dup(time);
        time_set_utc_offset(time, off);
        return time_fixoff(time);
    }

    return time_localtime(time_dup(time));
}

Returns self, converted to the UTC timezone:

t = Time.new(2000) # => 2000-01-01 00:00:00 -0600
t.utc?             # => false
t.utc              # => 2000-01-01 06:00:00 UTC
t.utc?             # => true

Time#gmtime is an alias for Time#utc.

Related: Time#getutc (returns a new converted Time object).

static VALUE
time_gmtime(VALUE time)
{
    struct time_object *tobj;
    struct vtm vtm;

    GetTimeval(time, tobj);
    if (TZMODE_UTC_P(tobj)) {
        if (tobj->vtm.tm_got)
            return time;
    }
    else {
        time_modify(time);
    }

    vtm.zone = str_utc;
    GMTIMEW(tobj->timew, &vtm);
    tobj->vtm = vtm;

    tobj->vtm.tm_got = 1;
    TZMODE_SET_UTC(tobj);
    return time;
}

Returns the offset in seconds between the timezones of UTC and self:

Time.utc(2000, 1, 1).utc_offset   # => 0
Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.

Time#gmt_offset and Time#gmtoff are aliases for Time#utc_offset.

VALUE
rb_time_utc_offset(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);

    if (TZMODE_UTC_P(tobj)) {
        return INT2FIX(0);
    }
    else {
        MAKE_TM(time, tobj);
        return tobj->vtm.utc_offset;
    }
}

Returns the integer hash code for self.

Related: Object#hash.

static VALUE
time_hash(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_hash(w2v(tobj->timew));
}

Returns the integer hour of the day for self, in range (0..23):

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

Related: Time#year, Time#mon, Time#min.

static VALUE
time_hour(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.hour);
}

Returns a string representation of self with subseconds:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.inspect # => "2000-12-31 23:59:59.5 +000001"

Related: Time#ctime, Time#to_s:

t.ctime   # => "Sun Dec 31 23:59:59 2000"
t.to_s    # => "2000-12-31 23:59:59 +0000"

static VALUE
time_inspect(VALUE time)
{
    struct time_object *tobj;
    VALUE str, subsec;

    GetTimeval(time, tobj);
    str = strftimev("%Y-%m-%d %H:%M:%S", time, rb_usascii_encoding());
    subsec = w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE)));
    if (subsec == INT2FIX(0)) {
    }
    else if (FIXNUM_P(subsec) && FIX2LONG(subsec) < TIME_SCALE) {
        long len;
        rb_str_catf(str, ".%09ld", FIX2LONG(subsec));
        for (len=RSTRING_LEN(str); RSTRING_PTR(str)[len-1] == '0' && len > 0; len--)
            ;
        rb_str_resize(str, len);
    }
    else {
        rb_str_cat_cstr(str, " ");
        subsec = quov(subsec, INT2FIX(TIME_SCALE));
        rb_str_concat(str, rb_obj_as_string(subsec));
    }
    if (TZMODE_UTC_P(tobj)) {
        rb_str_cat_cstr(str, " UTC");
    }
    else {
        /* ?TODO: subsecond offset */
        long off = NUM2LONG(rb_funcall(tobj->vtm.utc_offset, rb_intern("round"), 0));
        char sign = (off < 0) ? (off = -off, '-') : '+';
        int sec = off % 60;
        int min = (off /= 60) % 60;
        off /= 60;
        rb_str_catf(str, " %c%.2d%.2d", sign, (int)off, min);
        if (sec) rb_str_catf(str, "%.2d", sec);
    }
    return str;
}

Returns true if self is in daylight saving time, false otherwise:

t = Time.local(2000, 1, 1) # => 2000-01-01 00:00:00 -0600
t.zone                     # => "Central Standard Time"
t.dst?                     # => false
t = Time.local(2000, 7, 1) # => 2000-07-01 00:00:00 -0500
t.zone                     # => "Central Daylight Time"
t.dst?                     # => true

Time#isdst is an alias for Time#dst?.

static VALUE
time_isdst(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    if (tobj->vtm.isdst == VTM_ISDST_INITVAL) {
        rb_raise(rb_eRuntimeError, "isdst is not set yet");
    }
    return RBOOL(tobj->vtm.isdst);
}

With no argument given:

• Returns self if self is a local time.

• Otherwise returns a new Time in the user’s local timezone:

  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, returns the new Time object created by converting self to the given time zone:

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
t.localtime("-09:00")               # => 2000-01-01 11:15:01 -0900

For forms of argument zone, see Timezone Specifiers.

static VALUE
time_localtime_m(int argc, VALUE *argv, VALUE time)
{
    VALUE off;

    if (rb_check_arity(argc, 0, 1) && !NIL_P(off = argv[0])) {
        return time_zonelocal(time, off);
    }

    return time_localtime(time);
}

Returns the integer day of the month for self, in range (1..31):

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

Time#day is an alias for Time#mday.

Related: Time#year, Time#hour, Time#min.

static VALUE
time_mday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.mday);
}

Returns the integer minute of the hour for self, in range (0..59):

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

Related: Time#year, Time#mon, Time#sec.

static VALUE
time_min(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.min);
}

Returns the integer month of the year for self, in range (1..12):

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

Time#month is an alias for Time#mday.

Related: Time#year, Time#hour, Time#min.

static VALUE
time_mon(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.mon);
}

Returns true if self represents a Monday, false otherwise:

t = Time.utc(2000, 1, 3) # => 2000-01-03 00:00:00 UTC
t.monday?                # => true

Related: Time#tuesday?, Time#wednesday?, Time#thursday?.

static VALUE
time_monday(VALUE time)
{
    wday_p(1);
}

Returns a new Time object whose numeric value is that of self, with its seconds value rounded to precision ndigits:

t = Time.utc(2010, 3, 30, 5, 43, 25.123456789r)
t          # => 2010-03-30 05:43:25.123456789 UTC
t.round    # => 2010-03-30 05:43:25 UTC
t.round(0) # => 2010-03-30 05:43:25 UTC
t.round(1) # => 2010-03-30 05:43:25.1 UTC
t.round(2) # => 2010-03-30 05:43:25.12 UTC
t.round(3) # => 2010-03-30 05:43:25.123 UTC
t.round(4) # => 2010-03-30 05:43:25.1235 UTC

t = Time.utc(1999, 12,31, 23, 59, 59)
t                # => 1999-12-31 23:59:59 UTC
(t + 0.4).round  # => 1999-12-31 23:59:59 UTC
(t + 0.49).round # => 1999-12-31 23:59:59 UTC
(t + 0.5).round  # => 2000-01-01 00:00:00 UTC
(t + 1.4).round  # => 2000-01-01 00:00:00 UTC
(t + 1.49).round # => 2000-01-01 00:00:00 UTC
(t + 1.5).round  # => 2000-01-01 00:00:01 UTC

Related: Time#ceil, Time#floor.

static VALUE
time_round(int argc, VALUE *argv, VALUE time)
{
    VALUE ndigits, v, den;
    struct time_object *tobj;

    if (!rb_check_arity(argc, 0, 1) || NIL_P(ndigits = argv[0]))
        den = INT2FIX(1);
    else
        den = ndigits_denominator(ndigits);

    GetTimeval(time, tobj);
    v = w2v(rb_time_unmagnify(tobj->timew));

    v = modv(v, den);
    if (lt(v, quov(den, INT2FIX(2))))
        return time_add(tobj, time, v, -1);
    else
        return time_add(tobj, time, subv(den, v), 1);
}

Returns true if self represents a Saturday, false otherwise:

t = Time.utc(2000, 1, 1) # => 2000-01-01 00:00:00 UTC
t.saturday?              # => true

Related: Time#sunday?, Time#monday?, Time#tuesday?.

static VALUE
time_saturday(VALUE time)
{
    wday_p(6);
}

Returns the integer second of the minute for self, in range (0..60):

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

Note: the second value may be 60 when there is a leap second.

Related: Time#year, Time#mon, Time#min.

static VALUE
time_sec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return INT2FIX(tobj->vtm.sec);
}

Returns a string representation of self, formatted according to the given string format. See Formats for Dates and Times.

static VALUE
time_strftime(VALUE time, VALUE format)
{
    struct time_object *tobj;
    const char *fmt;
    long len;
    rb_encoding *enc;
    VALUE tmp;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    StringValue(format);
    if (!rb_enc_str_asciicompat_p(format)) {
        rb_raise(rb_eArgError, "format should have ASCII compatible encoding");
    }
    tmp = rb_str_tmp_frozen_acquire(format);
    fmt = RSTRING_PTR(tmp);
    len = RSTRING_LEN(tmp);
    enc = rb_enc_get(format);
    if (len == 0) {
        rb_warning("strftime called with empty format string");
        return rb_enc_str_new(0, 0, enc);
    }
    else {
        VALUE str = rb_strftime_alloc(fmt, len, enc, time, &tobj->vtm, tobj->timew,
                                      TZMODE_UTC_P(tobj));
        rb_str_tmp_frozen_release(format, tmp);
        if (!str) rb_raise(rb_eArgError, "invalid format: %"PRIsVALUE, format);
        return str;
    }
}

Returns the exact subseconds for self as a Numeric (Integer or Rational):

t = Time.now # => 2022-07-11 15:11:36.8490302 -0500
t.subsec     # => (4245151/5000000)

If the subseconds is zero, returns integer zero:

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

static VALUE
time_subsec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return quov(w2v(wmod(tobj->timew, WINT2FIXWV(TIME_SCALE))), INT2FIX(TIME_SCALE));
}

Returns true if self represents a Sunday, false otherwise:

t = Time.utc(2000, 1, 2) # => 2000-01-02 00:00:00 UTC
t.sunday?                # => true

Related: Time#monday?, Time#tuesday?, Time#wednesday?.

static VALUE
time_sunday(VALUE time)
{
    wday_p(0);
}

Returns true if self represents a Thursday, false otherwise:

t = Time.utc(2000, 1, 6) # => 2000-01-06 00:00:00 UTC
t.thursday?              # => true

Related: Time#friday?, Time#saturday?, Time#sunday?.

static VALUE
time_thursday(VALUE time)
{
    wday_p(4);
}

Returns a 10-element array of values representing self:

Time.utc(2000, 1, 1).to_a
# => [0,   0,   0,    1,   1,   2000, 6,    1,    false, "UTC"]
#    [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 to create a new Time object.

static VALUE
time_to_a(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    return rb_ary_new3(10,
                    INT2FIX(tobj->vtm.sec),
                    INT2FIX(tobj->vtm.min),
                    INT2FIX(tobj->vtm.hour),
                    INT2FIX(tobj->vtm.mday),
                    INT2FIX(tobj->vtm.mon),
                    tobj->vtm.year,
                    INT2FIX(tobj->vtm.wday),
                    INT2FIX(tobj->vtm.yday),
                    RBOOL(tobj->vtm.isdst),
                    time_zone(time));
}

Returns the value of self as a Float number Epoch seconds; subseconds are included.

The stored value of self is a Rational, which means that the returned value may be approximate:

Time.utc(1970, 1, 1, 0, 0, 0).to_f         # => 0.0
Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_f # => 0.999999
Time.utc(1950, 1, 1, 0, 0, 0).to_f         # => -631152000.0
Time.utc(1990, 1, 1, 0, 0, 0).to_f         # => 631152000.0

Related: Time#to_i, Time#to_r.

static VALUE
time_to_f(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_Float(rb_time_unmagnify_to_float(tobj->timew));
}

Returns the value of self as integer Epoch seconds; subseconds are truncated (not rounded):

Time.utc(1970, 1, 1, 0, 0, 0).to_i         # => 0
Time.utc(1970, 1, 1, 0, 0, 0, 999999).to_i # => 0
Time.utc(1950, 1, 1, 0, 0, 0).to_i         # => -631152000
Time.utc(1990, 1, 1, 0, 0, 0).to_i         # => 631152000

Time#tv_sec is an alias for Time#to_i.

Related: Time#to_f Time#to_r.

static VALUE
time_to_i(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return w2v(wdiv(tobj->timew, WINT2FIXWV(TIME_SCALE)));
}

Returns the value of self as a Rational exact number of Epoch seconds;

Time.now.to_r # => (16571402750320203/10000000)

Related: Time#to_f, Time#to_i.

static VALUE
time_to_r(VALUE time)
{
    struct time_object *tobj;
    VALUE v;

    GetTimeval(time, tobj);
    v = rb_time_unmagnify_to_rational(tobj->timew);
    if (!RB_TYPE_P(v, T_RATIONAL)) {
        v = rb_Rational1(v);
    }
    return v;
}

Returns a string representation of self, without subseconds:

t = Time.new(2000, 12, 31, 23, 59, 59, 0.5)
t.to_s    # => "2000-12-31 23:59:59 +0000"

Related: Time#ctime, Time#inspect:

t.ctime   # => "Sun Dec 31 23:59:59 2000"
t.inspect # => "2000-12-31 23:59:59.5 +000001"

static VALUE
time_to_s(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    if (TZMODE_UTC_P(tobj))
        return strftimev("%Y-%m-%d %H:%M:%S UTC", time, rb_usascii_encoding());
    else
        return strftimev("%Y-%m-%d %H:%M:%S %z", time, rb_usascii_encoding());
}

Returns true if self represents a Tuesday, false otherwise:

t = Time.utc(2000, 1, 4) # => 2000-01-04 00:00:00 UTC
t.tuesday?               # => true

Related: Time#wednesday?, Time#thursday?, Time#friday?.

static VALUE
time_tuesday(VALUE time)
{
    wday_p(2);
}

Returns the number of nanoseconds in the subseconds part of self in the range (0..999_999_999); lower-order digits are truncated, not rounded:

t = Time.now # => 2022-07-11 15:04:53.3219637 -0500
t.nsec       # => 321963700

Related: Time#subsec (returns exact subseconds).

Time#tv_nsec is an alias for Time#usec.

static VALUE
time_nsec(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return rb_to_int(w2v(wmulquoll(wmod(tobj->timew, WINT2WV(TIME_SCALE)), 1000000000, TIME_SCALE)));
}

Returns the number of microseconds in the subseconds part of self in the range (0..999_999); lower-order digits are truncated, not rounded:

t = Time.now # => 2022-07-11 14:59:47.5484697 -0500
t.usec       # => 548469

Related: Time#subsec (returns exact subseconds).

Time#tv_usec is an alias for Time#usec.

static VALUE
time_usec(VALUE time)
{
    struct time_object *tobj;
    wideval_t w, q, r;

    GetTimeval(time, tobj);

    w = wmod(tobj->timew, WINT2WV(TIME_SCALE));
    wmuldivmod(w, WINT2FIXWV(1000000), WINT2FIXWV(TIME_SCALE), &q, &r);
    return rb_to_int(w2v(q));
}

Returns true if self represents a time in UTC (GMT):

now = Time.now
# => 2022-08-18 10:24:13.5398485 -0500
now.utc? # => false
utc = Time.utc(2000, 1, 1, 20, 15, 1)
# => 2000-01-01 20:15:01 UTC
utc.utc? # => true

Time#gmt? is an alias for Time#utc?.

Related: Time.utc.

static VALUE
time_utc_p(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    return RBOOL(TZMODE_UTC_P(tobj));
}

Returns the integer day of the week for self, in range (0..6), with Sunday as zero.

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

Related: Time#year, Time#hour, Time#min.

static VALUE
time_wday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.wday != VTM_WDAY_INITVAL);
    return INT2FIX((int)tobj->vtm.wday);
}

Returns true if self represents a Wednesday, false otherwise:

t = Time.utc(2000, 1, 5) # => 2000-01-05 00:00:00 UTC
t.wednesday?             # => true

Related: Time#thursday?, Time#friday?, Time#saturday?.

static VALUE
time_wednesday(VALUE time)
{
    wday_p(3);
}

Returns the integer day of the year of self, in range (1..366).

Time.new(2000, 1, 1).yday   # => 1
Time.new(2000, 12, 31).yday # => 366

static VALUE
time_yday(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM_ENSURE(time, tobj, tobj->vtm.yday != 0);
    return INT2FIX(tobj->vtm.yday);
}

Returns the integer year for self:

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

Related: Time#mon, Time#hour, Time#min.

static VALUE
time_year(VALUE time)
{
    struct time_object *tobj;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);
    return tobj->vtm.year;
}

Returns the string name of the time zone for self:

Time.utc(2000, 1, 1).zone # => "UTC"
Time.new(2000, 1, 1).zone # => "Central Standard Time"

static VALUE
time_zone(VALUE time)
{
    struct time_object *tobj;
    VALUE zone;

    GetTimeval(time, tobj);
    MAKE_TM(time, tobj);

    if (TZMODE_UTC_P(tobj)) {
        return rb_usascii_str_new_cstr("UTC");
    }
    zone = tobj->vtm.zone;
    if (NIL_P(zone))
        return Qnil;

    if (RB_TYPE_P(zone, T_STRING))
        zone = rb_str_dup(zone);
    return zone;
}