类 Time

Time 对象表示日期和时间

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

虽然它的值可以用单个数字表示（参见下面的 纪元秒），但按部分处理该值可能很方便

t = Time.new(-2000, 1, 1, 0, 0, 0.0)
# => -2000-01-01 00:00:00 -0600
t.year # => -2000
t.month # => 1
t.mday # => 1
t.hour # => 0
t.min # => 0
t.sec # => 0
t.subsec # => 0

t = Time.new(2000, 12, 31, 23, 59, 59.5)
# => 2000-12-31 23:59:59.5 -0600
t.year # => 2000
t.month # => 12
t.mday # => 31
t.hour # => 23
t.min # => 59
t.sec # => 59
t.subsec # => (1/2)

纪元秒 ↑

纪元秒 是自 Unix 纪元（1970 年 1 月 1 日）以来的精确秒数（包括小数秒）。

您可以使用方法 Time.to_r 精确地检索该值。

Time.at(0).to_r        # => (0/1)
Time.at(0.999999).to_r # => (9007190247541737/9007199254740992)

其他检索方法，如 Time#to_i 和 Time#to_f 可能会返回舍入或截断小数秒的值。

时间分辨率 ↑

从系统时钟派生的 Time 对象（例如，通过方法 Time.now）具有系统支持的分辨率。

示例 ↑

所有这些示例都是使用 EST 时区完成的，EST 时区是 GMT-5。

创建新的 Time 实例 ↑

您可以使用 Time.new 创建 Time 的新实例。这将使用当前系统时间。 Time.now 是它的别名。您还可以将时间的部分内容传递给 Time.new，例如年、月、分钟等。当您想以这种方式构造时间时，您必须至少传递一年。如果您只传递年份，时间将默认为该年的 1 月 1 日 00:00:00，并使用当前系统时区。以下是一些示例

Time.new(2002)         #=> 2002-01-01 00:00:00 -0500
Time.new(2002, 10)     #=> 2002-10-01 00:00:00 -0500
Time.new(2002, 10, 31) #=> 2002-10-31 00:00:00 -0500

您可以传递 UTC 偏移量

Time.new(2002, 10, 31, 2, 2, 2, "+02:00") #=> 2002-10-31 02:02:02 +0200

或 时区对象

zone = timezone("Europe/Athens")      # Eastern European Time, UTC+2
Time.new(2002, 10, 31, 2, 2, 2, zone) #=> 2002-10-31 02:02:02 +0200

您还可以使用 Time.local 和 Time.utc 来推断本地和 UTC 时区，而不是使用当前系统设置。

您还可以使用 Time.at 创建新的时间，它接受自 Unix 纪元 以来经过的秒数（含亚秒）。

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

使用 Time 实例 ↑

一旦您拥有 Time 的实例，您就可以用它做很多事情。以下是一些示例。对于以下所有示例，我们将假设您已经完成了以下操作

t = Time.new(1993, 02, 24, 12, 0, 0, "+09:00")

那是星期一吗？

t.monday? #=> false

那是什么年份？

t.year #=> 1993

当时是夏令时吗？

t.dst? #=> false

一年后的那一天是什么？

t + (60*60*24*365) #=> 1994-02-24 12:00:00 +0900

自 Unix 纪元以来经过了多少秒？

t.to_i #=> 730522800

您还可以执行标准函数，例如比较两个时间。

t1 = Time.new(2010)
t2 = Time.new(2011)

t1 == t2 #=> false
t1 == t1 #=> true
t1 <  t2 #=> true
t1 >  t2 #=> false

Time.new(2010,10,31).between?(t1, t2) #=> true

这里有什么 ↑

首先，其他地方有什么。类 Time

这里，类 Time 提供了对以下内容有用的方法

  • {创建 Time 对象}[rdoc-ref:Time@Methods+for+Creating]。

  • {获取 Time 值}[rdoc-ref:Time@Methods+for+Fetching]。

  • {查询 Time 对象}[rdoc-ref:Time@Methods+for+Querying]。

  • {比较 Time 对象}[rdoc-ref:Time@Methods+for+Comparing]。

  • {转换 Time 对象}[rdoc-ref:Time@Methods+for+Converting]。

  • {舍入 Time}.

创建方法 ↑

  • ::new: 从指定的参数（年、月等）返回一个新的时间，包括一个可选的时区值。

  • ::local（别名为 ::mktime）：与 ::new 相同，但时区为本地时区。

  • ::utc（别名为 ::gm）：与 ::new 相同，但时区为 UTC。

  • ::at: 返回一个基于自纪元以来的秒数的新时间。

  • ::now: 返回一个基于当前系统时间的新时间。

  • +（加）：返回一个增加给定秒数的新时间。

  • -（减）：返回一个减少给定秒数的新时间。

获取方法 ↑

  • year: 返回时间的年份。

  • month（别名为 mon）：返回时间的月份。

  • mday（别名为 day）：返回时间的月份中的日期。

  • hour: 返回时间的时钟值。

  • min: 返回时间的分钟值。

  • sec: 返回时间的秒值。

  • usec（别名为 tv_usec）：返回时间的亚秒值中的微秒数。

  • nsec（别名为 tv_nsec：返回时间的亚秒部分中的纳秒数。

  • subsec: 返回时间的亚秒值。

  • wday: 返回时间的整数星期值（0 == 星期日）。

  • yday: 返回时间的整数年日值（1 == 1 月 1 日）。

  • hash: 返回时间的整数哈希值。

  • utc_offset（别名为 gmt_offset 和 gmtoff）：返回时间与 UTC 之间的偏移量（以秒为单位）。

  • to_f：返回时间自纪元以来的秒数的浮点数。

  • to_i（别名为 tv_sec）：返回时间自纪元以来的秒数的整数。

  • to_r：返回时间自纪元以来的秒数的 Rational 数。

  • zone：返回时间的时区字符串表示形式。

查询方法 ↑

  • utc?（别名为 gmt?）：返回时间是否为 UTC。

  • dst?（别名为 isdst）：返回时间是否为 DST（夏令时）。

  • sunday?：返回时间是否为星期日。

  • monday?：返回时间是否为星期一。

  • tuesday?：返回时间是否为星期二。

  • wednesday?：返回时间是否为星期三。

  • thursday?：返回时间是否为星期四。

  • friday?：返回时间是否为星期五。

  • saturday?：返回时间是否为星期六。

比较方法 ↑

  • #<=>: 比较 self 与另一个时间。

  • eql?：返回时间是否等于另一个时间。

转换方法 ↑

  • asctime（别名为 ctime）：以字符串形式返回时间。

  • inspect：以字符串形式详细返回时间。

  • strftime：根据给定格式以字符串形式返回时间。

  • to_a：返回时间中 10 个元素的数组。

  • to_s：返回时间的字符串表示形式。

  • getutc（别名为 getgm）：返回转换为 UTC 的新时间。

  • getlocal：返回转换为本地时间的新的时间。

  • utc（别名为 gmtime）：将时间就地转换为 UTC。

  • localtime：将时间就地转换为本地时间。

  • deconstruct_keys：返回用于模式匹配的时间组件的哈希。

舍入方法 ↑

  • round: 返回一个新的时间，其秒以下部分已四舍五入。

  • ceil: 返回一个新的时间，其秒以下部分已向上取整。

  • floor: 返回一个新的时间，其秒以下部分已向下取整。

有关参数 zone 的形式，请参见 时区说明符。

时区说明符 ↑

某些 Time 方法接受指定时区的参数

这些参数的值必须是以下之一（每个值将在下面详细说明）

时/分偏移量 ↑

zone 值可以是相对于 UTC 的字符串偏移量，格式为 '+HH:MM' 或 '-HH:MM'，其中

  • HH 是 2 位数的小时，范围为 0..23。

  • MM 是 2 位数的分钟，范围为 0..59。

示例

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: '-23:59')            # => 1999-12-31 20:16:01 -2359
Time.at(t, in: '+23:59')            # => 2000-01-02 20:14:01 +2359

单字母偏移量 ↑

zone 值可以是 'A'..'I' 或 'K'..'Z' 范围内的字母；请参见 军事时区列表

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: 'A')                 # => 2000-01-01 21:15:01 +0100
Time.at(t, in: 'I')                 # => 2000-01-02 05:15:01 +0900
Time.at(t, in: 'K')                 # => 2000-01-02 06:15:01 +1000
Time.at(t, in: 'Y')                 # => 2000-01-01 08:15:01 -1200
Time.at(t, in: 'Z')                 # => 2000-01-01 20:15:01 UTC

整数偏移量 ↑

zone 值可以是 -86399..86399 范围内的整数秒数

t = Time.utc(2000, 1, 1, 20, 15, 1) # => 2000-01-01 20:15:01 UTC
Time.at(t, in: -86399)              # => 1999-12-31 20:15:02 -235959
Time.at(t, in: 86399)               # => 2000-01-02 20:15:00 +235959

时区对象 ↑

zone 值可以是响应某些时区方法的对象，例如 Timezone 和 TZInfo 的实例。

时区方法包括

自定义时区类可能具有以下实例方法，如果定义了这些方法，则会调用它们。

  • abbr:

  • dst?:

  • name:

    • 当 Marshal.dump(t) 被调用时调用。

    • 参数：无。

    • 返回值：时区的字符串名称。

Time-Like Objects ↑

Time-like 对象是一个容器对象，能够与时区库交互以进行时区转换。

上面时区转换方法的参数将具有类似于 Time 的属性，除了与时区相关的属性没有意义。

时区对象的 local_to_utc 和 utc_to_local 方法返回的对象可能是与它们的参数相同的类，也可能是任意对象类，或者可能是类 Integer。

对于返回的类，除了 Integer 之外，该类必须具有以下方法。

  • year

  • mon

  • mday

  • hour

  • min

  • sec

  • isdst

  • to_i

对于返回的 Integer，其在 UTC 中分解的组件被解释为指定时区中的时间。

时区名称 ↑

如果类（类方法的接收者，或实例方法的接收者的类）具有 find_timezone 单例方法，则调用此方法以从时区名称获取相应的时区对象。

例如，使用 Timezone

class TimeWithTimezone < Time
  require 'timezone'
  def self.find_timezone(z) = Timezone[z]
end

TimeWithTimezone.now(in: "America/New_York")        #=> 2023-12-25 00:00:00 -0500
TimeWithTimezone.new("2023-12-25 America/New_York") #=> 2023-12-25 00:00:00 -0500

或者，使用 TZInfo

class TimeWithTZInfo < Time
  require 'tzinfo'
  def self.find_timezone(z) = TZInfo::Timezone.get(z)
end

TimeWithTZInfo.now(in: "America/New_York")          #=> 2023-12-25 00:00:00 -0500
TimeWithTZInfo.new("2023-12-25 America/New_York")   #=> 2023-12-25 00:00:00 -0500

您可以在子类中定义此方法，或者在顶层 Time 类中定义此方法。

公共类方法

at(time, subsec = false, unit = :microsecond, in: nil) 点击切换源代码

返回一个基于给定参数的新 Time 对象。

必需参数 time 可以是以下两种之一：

  • 一个 Time 对象，其值是返回时间的基准；也受可选关键字参数 in:（见下文）的影响。

  • 返回时间的 纪元秒 的数值。

示例

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

可选数值参数 subsec 和可选符号参数 units 协同工作以指定返回时间的亚秒；参数 units 指定 subsec 的单位。

  • :millisecond: subsec 以毫秒为单位

    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 或 :usec: subsec 以微秒为单位

    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 或 :nsec: subsec 以纳秒为单位

    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

可选关键字参数 in: zone 指定返回时间的时区

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

有关参数 zone 的形式，请参见 时区说明符。

# File ruby_3_3_0/timev.rb, line 284
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
gm(*args)

根据给定的参数返回一个新的 Time 对象，以 UTC 时区为准。

当给出 1 到 7 个参数时，这些参数的解释方式与上面第一个调用序列中的解释方式相同。

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

示例

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

必需参数 year 没有最小值和最大值。

对于可选参数

  • month: 月份范围为 (1..12)，或不区分大小写的 3 个字母的月份名称

    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: 月份中的日期范围为 (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: 小时范围为 (0..23)，如果 min、sec 和 usec 为零，则为 24

    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: 分钟范围为 (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: 秒范围为 (0..59)，如果 usec 为零，则为 60

    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: 微秒范围为 (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

这些值可以是

  • 整数，如上所述。

  • 可转换为整数的数字

    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 整数

    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

当给出正好十个参数时，这些参数的解释方式与上面第二个调用序列中的解释方式相同。

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

其中 dummy 参数被忽略。

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

此形式对于从 Time.to_a 返回的 10 元素数组创建 Time 对象很有用。

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

这两种形式的前六个参数相同，但顺序不同；这些公共参数的范围对于两种形式都相同；见上文。

如果参数数量为 8、9 或大于 10，则会引发异常。

相关：Time.local.

别名：utc
local(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) → new_time 点击切换源代码
local(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) → new_time

与 Time.utc 相似，但返回的 Time 对象具有本地时区，而不是 UTC 时区。

# 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)));
}
也称为：mktime
mktime(*args)

与 Time.utc 相似，但返回的 Time 对象具有本地时区，而不是 UTC 时区。

# 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
别名：local
new(year = nil, mon = nil, mday = nil, hour = nil, min = nil, sec = nil, zone = nil, in: nil, precision: 9) 点击切换源代码

根据给定的参数返回一个新的 Time 对象，默认情况下在本地时区。

如果没有位置参数，则返回 Time.now 的值。

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

如果有一个表示时间的字符串参数，则返回一个新的 Time 对象，该对象基于给定的参数，在本地时区。

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

如果有一到六个参数，则返回一个新的 Time 对象，该对象基于给定的参数，在本地时区。

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

对于位置参数（除了 zone）

  • year: 年份，没有范围限制

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

  • month: 月份范围为 (1..12)，或不区分大小写的 3 个字母的月份名称

    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: 月份中的日期范围为 (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: 小时范围为 (0..23)，如果 min、sec 和 usec 为零，则为 24

    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: 分钟范围为 (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: 秒，范围在 (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 可以是 Float 或 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

这些值可以是

  • 整数，如上所述。

  • 可转换为整数的数字

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

  • String 整数

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

当给出位置参数 zone 或关键字参数 in: 时，新的 Time 对象将位于指定的时区。有关参数 zone 的形式，请参见 时区说明符

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

由于 in: 关键字参数只提供默认值，因此如果第一个参数以单个字符串形式包含时区信息，则此关键字参数将被静默忽略。

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

  • precision: 子秒部分中有效数字的最大值，默认为 9。更多数字将被截断，就像 Time 的其他操作一样。除非第一个参数是字符串，否则将被忽略。

# File ruby_3_3_0/timev.rb, line 395
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
now(in: nil) 点击切换源代码

从当前系统时间创建一个新的 Time 对象。这与没有参数的 Time.new 相同。

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

有关参数 zone 的形式，请参见 时区说明符.

# File ruby_3_3_0/timev.rb, line 225
def self.now(in: nil)
  Primitive.time_s_now(Primitive.arg!(:in))
end
utc(year, month = 1, mday = 1, hour = 0, min = 0, sec = 0, usec = 0) → new_time 点击切换源代码
utc(sec, min, hour, mday, month, year, dummy, dummy, dummy, dummy) → new_time

根据给定的参数返回一个新的 Time 对象，以 UTC 时区为准。

当给出 1 到 7 个参数时，这些参数的解释方式与上面第一个调用序列中的解释方式相同。

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

示例

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

必需参数 year 没有最小值和最大值。

对于可选参数

  • month: 月份范围为 (1..12)，或不区分大小写的 3 个字母的月份名称

    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: 月份中的日期范围为 (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: 小时范围为 (0..23)，如果 min、sec 和 usec 为零，则为 24

    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: 分钟范围为 (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: 秒范围为 (0..59)，如果 usec 为零，则为 60

    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: 微秒范围为 (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

这些值可以是

  • 整数，如上所述。

  • 可转换为整数的数字

    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 整数

    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

当给出正好十个参数时，这些参数的解释方式与上面第二个调用序列中的解释方式相同。

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

其中 dummy 参数被忽略。

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

此形式对于从 Time.to_a 返回的 10 元素数组创建 Time 对象很有用。

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

这两种形式的前六个参数相同，但顺序不同；这些公共参数的范围对于两种形式都相同；见上文。

如果参数数量为 8、9 或大于 10，则会引发异常。

相关：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)));
}
也称为：gm

公共实例方法

self + numeric → new_time 点击切换源代码

返回一个新的 Time 对象，其值为 self 的数值和给定的 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

相关：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);
}
self - numeric → new_time 点击切换源代码
self - other_time → float

当给出 numeric 时，返回一个新的 Time 对象，其值为 self 的数值与 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

当给出 other_time 时，返回一个 Float，其值为 self 的数值与 other_time 的数值之差（以秒为单位）。

t - t # => 0.0

相关：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);
}
self <=> other_time → -1, 0, +1, or nil 点击切换源代码

比较 self 与 other_time；返回

  • -1，如果 self 小于 other_time。

  • 0，如果 self 等于 other_time。

  • 1，如果 self 大于 other_time。

  • nil，如果 self 和 other_time 不可比较。

示例

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);
}
asctime()

返回 self 的字符串表示形式，格式为 strftime('%a %b %e %T %Y') 或其简写形式 strftime('%c')；参见 日期和时间格式

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#to_s, Time#inspect

t.inspect                    # => "2000-12-31 23:59:59.5 +000001"
t.to_s                       # => "2000-12-31 23:59:59 +0000"
别名：ctime
ceil(ndigits = 0) → new_time 点击切换源代码

返回一个新的 Time 对象，其数值大于或等于 self，并且其秒数被截断到精度 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

相关：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);
}
ctime → string 点击切换源代码

返回 self 的字符串表示形式，格式为 strftime('%a %b %e %T %Y') 或其简写形式 strftime('%c')；参见 日期和时间格式

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#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());
}
别名：asctime
day()

返回 self 的月份中的整数天数，范围为 (1..31)

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

相关：Time#year, Time#hour, Time#min.

别名：mday
deconstruct_keys(array_of_names_or_nil) → hash 点击切换源代码

返回一个包含名称/值对的哈希表，用于模式匹配。可能的键包括：:year, :month, :day, :yday, :wday, :hour, :min, :sec, :subsec, :dst, :zone。

可能的用法

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"

注意，通过模式进行解构也可以与类检查结合使用

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;
}
dst? → true 或 false

如果self处于夏令时，则返回true，否则返回false

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
别名：isdst
eql?(other_time) 点击切换源代码

如果self和other_time都是具有完全相同时间值的Time对象，则返回true。

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;
}
floor(ndigits = 0) → new_time 点击切换源代码

返回一个新的Time对象，其数值小于或等于self，并且其秒数被截断到精度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

相关：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);
}
friday? → true 或 false 点击切换源代码

如果self表示星期五，则返回true，否则返回false

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

相关：Time#saturday?, Time#sunday?, Time#monday?.

static VALUE
time_friday(VALUE time)
{
    wday_p(5);
}
getgm -> new_time 点击切换源代码

返回一个新的Time对象，表示self的值转换为UTC时区

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

static VALUE
time_getgmtime(VALUE time)
{
    return time_gmtime(time_dup(time));
}
也称为：getutc
getlocal(zone = nil) → new_time 点击切换源代码

返回一个新的Time对象，表示self的值转换为给定的时区；如果zone为nil，则使用本地时区

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

有关参数 zone 的形式，请参见 时区说明符.

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));
}
getutc → new_time

返回一个新的Time对象，表示self的值转换为UTC时区

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
别名：getgm
gmt?()

如果 self 代表 UTC (GMT) 时间，则返回 true

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

别名：utc?
gmt_offset()

返回 UTC 和 self 时区之间的秒偏移量

Time.utc(2000, 1, 1).utc_offset   # => 0
Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
别名：gmtoff
gmtime -> self 点击切换源代码

返回 self，转换为 UTC 时区

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#getutc (返回一个新的转换后的 Time 对象)。

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);
    time_set_vtm(time, tobj, vtm);

    tobj->vtm.tm_got = 1;
    TZMODE_SET_UTC(tobj);
    return time;
}
也称为：utc
gmtoff -> integer 点击切换源代码

返回 UTC 和 self 时区之间的秒偏移量

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

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;
    }
}
也称为：gmt_offset, utc_offset
hash → integer 点击切换源代码

返回 self 的整数哈希码。

相关：Object#hash.

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

    GetTimeval(time, tobj);
    return rb_hash(w2v(tobj->timew));
}
hour → integer 点击切换源代码

返回 self 的一天中的整数小时，范围为 (0..23)

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

相关：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);
}
inspect → string 点击切换源代码

返回 self 的字符串表示形式，包含亚秒

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

相关：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;
}
isdst -> true or false 点击切换源代码

如果self处于夏令时，则返回true，否则返回false

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

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);
}
也称为：dst?
localtime → self or new_time 点击切换源代码
localtime(zone) → new_time

没有给出参数

  • 如果 self 是本地时间，则返回 self。

  • 否则返回用户本地时区中的一个新的 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

给出参数 zone，返回通过将 self 转换为给定时区创建的新 Time 对象

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

有关参数 zone 的形式，请参见 时区说明符.

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);
}
mday -> integer 点击切换源代码

返回 self 的月份中的整数天数，范围为 (1..31)

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

相关：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);
}
也称为：day
min → integer 点击切换源代码

返回 self 的小时中的整数分钟，范围为 (0..59)

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

相关：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);
}
mon → 整数 点击切换源代码

返回 self 所代表的年份中的月份整数，范围为 (1..12)

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

相关：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);
}
别名：month
monday? → true 或 false 点击切换源代码

如果 self 代表星期一，则返回 true，否则返回 false

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

相关：Time#tuesday?，Time#wednesday?，Time#thursday?.

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

返回 self 所代表的年份中的月份整数，范围为 (1..12)

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

相关：Time#year, Time#hour, Time#min.

别名：mon
nsec → 整数

返回 self 的亚秒部分中的纳秒数，范围为 (0..999_999_999)；低位数字被截断，而不是四舍五入

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

相关：Time#subsec（返回精确的亚秒数）。

别名：tv_nsec
round(ndigits = 0) → new_time 点击切换源代码

返回一个新的 Time 对象，其数值与 self 相同，但其秒值已四舍五入到精度 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

相关：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);
}
saturday? → true 或 false 点击切换源代码

如果 self 代表星期六，则返回 true，否则返回 false

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

相关：Time#sunday?，Time#monday?，Time#tuesday?.

static VALUE
time_saturday(VALUE time)
{
    wday_p(6);
}
sec → 整数 点击切换源代码

返回 self 所代表的分钟中的秒整数，范围为 (0..60)

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

注意：当出现闰秒时，秒值可能为 60。

相关：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);
}
strftime(format_string) → 字符串 点击切换源代码

返回 self 的字符串表示形式，格式根据给定的字符串 format 进行格式化。参见 日期和时间的格式.

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;
    }
}
subsec → 数值 点击切换源代码

返回 self 的精确亚秒数，以 Numeric（Integer 或 Rational）形式表示

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

如果秒以下部分为零，则返回整数零

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));
}
sunday? → true 或 false 点击切换源代码

如果 self 表示星期日，则返回 true，否则返回 false

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

相关：Time#monday?，Time#tuesday?，Time#wednesday?.

static VALUE
time_sunday(VALUE time)
{
    wday_p(0);
}
thursday? → true 或 false 点击切换源代码

如果 self 表示星期四，则返回 true，否则返回 false

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

相关：Time#friday?，Time#saturday?，Time#sunday?.

static VALUE
time_thursday(VALUE time)
{
    wday_p(4);
}
to_a → 数组 点击切换源代码

返回一个包含 10 个元素的数组，表示 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]

返回的数组适合用作 Time.utc 或 Time.local 的参数，以创建新的 Time 对象。

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));
}
to_f → 浮点数 点击切换源代码

返回 self 的值，以 Float 数字 纪元秒 表示；包括秒以下部分。

self 的存储值为 Rational，这意味着返回的值可能是近似的

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

相关：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));
}
to_i → 整数 点击切换源代码

返回 self 的值，以整数 纪元秒 表示；秒以下部分被截断（不四舍五入）

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#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)));
}
也称为：tv_sec
to_r → 有理数 点击切换源代码

返回 self 的值，以 Rational 精确表示 纪元秒 的数量；

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

相关：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;
}
to_s → 字符串 点击切换源代码

返回 self 的字符串表示形式，不包括秒以下部分

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

相关：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());
}
tuesday? → true 或 false 点击切换源代码

如果 self 代表星期二，则返回 true，否则返回 false

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

相关：Time#wednesday?，Time#thursday?，Time#friday?.

static VALUE
time_tuesday(VALUE time)
{
    wday_p(2);
}
tv_nsec -> integer 点击切换源代码

返回 self 的亚秒部分中的纳秒数，范围为 (0..999_999_999)；低位数字被截断，而不是四舍五入

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

相关：Time#subsec（返回精确的亚秒数）。

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)));
}
别名：nsec
tv_sec()

返回 self 的值，以整数 纪元秒 表示；秒以下部分被截断（不四舍五入）

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#to_f Time#to_r.

别名：to_i
tv_usec -> integer 点击切换源代码

返回 self 的亚秒部分中的微秒数，范围为 (0..999_999)；低位数字被截断，而不是四舍五入

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

相关：Time#subsec（返回精确的亚秒数）。

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));
}
别名：usec
usec → integer

返回 self 的亚秒部分中的微秒数，范围为 (0..999_999)；低位数字被截断，而不是四舍五入

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

相关：Time#subsec（返回精确的亚秒数）。

别名：tv_usec
utc → self

返回 self，转换为 UTC 时区

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#getutc (返回一个新的转换后的 Time 对象)。

别名：gmtime
utc? → true or false 点击切换源代码

如果 self 代表 UTC (GMT) 时间，则返回 true

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

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

    GetTimeval(time, tobj);
    return RBOOL(TZMODE_UTC_P(tobj));
}
别名：gmt?
utc_offset → integer

返回 UTC 和 self 时区之间的秒偏移量

Time.utc(2000, 1, 1).utc_offset   # => 0
Time.local(2000, 1, 1).utc_offset # => -21600 # -6*3600, or minus six hours.
别名：gmtoff
wday → integer 点击切换源代码

返回 self 的星期几的整数，范围为 (0..6)，其中星期日为零。

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

相关：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);
}
wednesday? → true or false 点击切换源代码

如果 self 代表星期三，则返回 true，否则返回 false

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

相关：Time#thursday?，Time#friday?，Time#saturday?.

static VALUE
time_wednesday(VALUE time)
{
    wday_p(3);
}
yday → integer 点击切换源代码

返回 self 的一年中的整数天数，范围为 (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);
}
year → integer 点击切换源代码

返回 self 的整数年份

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

相关：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;
}
zone → string or timezone 点击切换源代码

返回 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;
}