查看源代码 时间 (Elixir v1.16.2)
时间结构体和函数。
时间结构体包含小时、分钟、秒和微秒字段。可以使用 new/4 函数或使用 ~T（参见 sigil_T/2）符号来构建新时间。
iex> ~T[23:00:07.001]
~T[23:00:07.001]new/4 和符号都返回一个结构体，其中时间字段可以直接访问。
iex> time = ~T[23:00:07.001]
iex> time.hour
23
iex> time.microsecond
{1000, 3}此模块中的函数可以使用 Time 结构体，以及任何包含与 Time 结构体相同字段的结构体，例如 NaiveDateTime 和 DateTime。此类函数在它们的类型规范中需要 Calendar.time/0（而不是 t/0）。
开发者应该避免直接创建时间结构体，而是依赖此模块提供的函数以及第三方日历库中的函数。
比较时间
在 Elixir 中使用 ==/2、>/2、</2 和类似的比较是结构化的，并且基于 Time 结构体的字段。为了正确比较时间，请使用 compare/2 函数。此模块中存在 compare/2 函数还允许使用 Enum.min/2 和 Enum.max/2 函数来获取 Enum 中的最小和最大时间。例如
iex> Enum.min([~T[23:00:07.001], ~T[10:00:07.001]], Time)
~T[10:00:07.001]摘要
函数
将 unit 单位的 amount_to_add 添加到给定的 time。
如果第一个时间严格晚于第二个时间，则返回 true。
如果第一个时间严格早于第二个时间，则返回 true。
比较两个时间结构体。
将给定的 time 转换为不同的日历。
类似于 Time.convert/2，但如果两个日历之间的转换不可行，则引发 ArgumentError。
返回两个时间之间的差值，仅考虑小时、分钟、秒和微秒。
将 Erlang 时间元组转换为 Time 结构体。
将 Erlang 时间元组转换为 Time 结构体。
解析由 ISO 8601:2019 描述的扩展“本地时间”格式。
解析由 ISO 8601:2019 描述的扩展“本地时间”格式。
将午夜后的秒数转换为 Time 结构体。
将给定的 time 转换为 Erlang 时间元组。
将 Time 结构体转换为午夜后的秒数。
将给定的 time 转换为字符串。
返回给定的时间，其中微秒字段被截断到给定的精度（:microsecond、millisecond 或 :second）。
返回 UTC 中的当前时间。
类型
@type t() :: %Time{ calendar: Calendar.calendar(), hour: Calendar.hour(), microsecond: Calendar.microsecond(), minute: Calendar.minute(), second: Calendar.second() }
函数
@spec add(Calendar.time(), integer(), :hour | :minute | System.time_unit()) :: t()
将 unit 单位的 amount_to_add 添加到给定的 time。
接受任何 unit 中的 amount_to_add。 unit 可以是 :hour、:minute、:second 或来自 System.time_unit/0 的任何亚秒精度。默认值为 :second。负值将向时间倒退。
此函数始终认为单位是根据 Calendar.ISO 计算的。
请注意，结果值表示一天中的时间，这意味着它是循环的，例如，对于 ISO 日历，它永远不会超过 24 小时。
示例
iex> Time.add(~T[10:00:00], 27000)
~T[17:30:00]
iex> Time.add(~T[11:00:00.005], 2400)
~T[11:40:00.005]
iex> Time.add(~T[00:00:00.000], 86_399_999, :millisecond)
~T[23:59:59.999]允许使用负值
iex> Time.add(~T[23:00:00], -60)
~T[22:59:00]请注意，时间是循环的
iex> Time.add(~T[17:10:05], 86400)
~T[17:10:05]也支持小时和分钟
iex> Time.add(~T[17:10:05], 2, :hour)
~T[19:10:05]
iex> Time.add(~T[17:10:05], 30, :minute)
~T[17:40:05]此操作将时间的精度与给定的单位合并
iex> result = Time.add(~T[00:29:10], 21, :millisecond)
~T[00:29:10.021]
iex> result.microsecond
{21000, 3}@spec after?(Calendar.time(), Calendar.time()) :: boolean()
如果第一个时间严格晚于第二个时间，则返回 true。
示例
iex> Time.after?(~T[16:04:28], ~T[16:04:16])
true
iex> Time.after?(~T[16:04:16], ~T[16:04:16])
false
iex> Time.after?(~T[16:04:16.001], ~T[16:04:16.01])
false@spec before?(Calendar.time(), Calendar.time()) :: boolean()
如果第一个时间严格早于第二个时间，则返回 true。
示例
iex> Time.before?(~T[16:04:16], ~T[16:04:28])
true
iex> Time.before?(~T[16:04:16], ~T[16:04:16])
false
iex> Time.before?(~T[16:04:16.01], ~T[16:04:16.001])
false@spec compare(Calendar.time(), Calendar.time()) :: :lt | :eq | :gt
比较两个时间结构体。
如果第一个时间晚于第二个时间，则返回 :gt，反之亦然返回 :lt。如果两个时间相等，则返回 :eq。
示例
iex> Time.compare(~T[16:04:16], ~T[16:04:28])
:lt
iex> Time.compare(~T[16:04:16], ~T[16:04:16])
:eq
iex> Time.compare(~T[16:04:16.01], ~T[16:04:16.001])
:gt此函数还可以通过仅考虑时间字段来比较更复杂的日历类型
iex> Time.compare(~N[1900-01-01 16:04:16], ~N[2015-01-01 16:04:16])
:eq
iex> Time.compare(~N[2015-01-01 16:04:16], ~N[2015-01-01 16:04:28])
:lt
iex> Time.compare(~N[2015-01-01 16:04:16.01], ~N[2000-01-01 16:04:16.001])
:gt@spec convert(Calendar.time(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}
将给定的 time 转换为不同的日历。
如果转换成功，则返回 {:ok, time}，否则返回 {:error, reason}。
示例
假设有人实现了 Calendar.Holocene，这是一个基于公历的日历，它将公历年份增加 10,000 年
iex> Time.convert(~T[13:30:15], Calendar.Holocene)
{:ok, %Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}@spec convert!(Calendar.time(), Calendar.calendar()) :: t()
类似于 Time.convert/2，但如果两个日历之间的转换不可行，则引发 ArgumentError。
示例
假设有人实现了 Calendar.Holocene，这是一个基于公历的日历，它将公历年份增加 10,000 年
iex> Time.convert!(~T[13:30:15], Calendar.Holocene)
%Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}@spec diff(Calendar.time(), Calendar.time(), :hour | :minute | System.time_unit()) :: integer()
返回两个时间之间的差值，仅考虑小时、分钟、秒和微秒。
与 compare/2 函数一样，可以使用 Time 结构体和其他包含时间的结构体。例如，如果传递了 NaiveDateTime 或 DateTime，则只考虑小时、分钟、秒和微秒。在计算差值时，将忽略有关日期或时区的任何附加信息。
答案可以以 :hour、:minute、:second 或任何来自 System.time_unit/0 的亚秒 unit 返回。如果第一个时间值早于第二个时间值，则返回负数。
单位是根据 Calendar.ISO 测量的，默认值为 :second。不支持分数结果，并将其截断。
示例
iex> Time.diff(~T[00:29:12], ~T[00:29:10])
2
# When passing a `NaiveDateTime` the date part is ignored.
iex> Time.diff(~N[2017-01-01 00:29:12], ~T[00:29:10])
2
# Two `NaiveDateTime` structs could have big differences in the date
# but only the time part is considered.
iex> Time.diff(~N[2017-01-01 00:29:12], ~N[1900-02-03 00:29:10])
2
iex> Time.diff(~T[00:29:12], ~T[00:29:10], :microsecond)
2_000_000
iex> Time.diff(~T[00:29:10], ~T[00:29:12], :microsecond)
-2_000_000
iex> Time.diff(~T[02:29:10], ~T[00:29:10], :hour)
2
iex> Time.diff(~T[02:29:10], ~T[00:29:11], :hour)
1@spec from_erl(:calendar.time(), Calendar.microsecond(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}
将 Erlang 时间元组转换为 Time 结构体。
示例
iex> Time.from_erl({23, 30, 15}, {5000, 3})
{:ok, ~T[23:30:15.005]}
iex> Time.from_erl({24, 30, 15})
{:error, :invalid_time}@spec from_erl!(:calendar.time(), Calendar.microsecond(), Calendar.calendar()) :: t()
将 Erlang 时间元组转换为 Time 结构体。
示例
iex> Time.from_erl!({23, 30, 15})
~T[23:30:15]
iex> Time.from_erl!({23, 30, 15}, {5000, 3})
~T[23:30:15.005]
iex> Time.from_erl!({24, 30, 15})
** (ArgumentError) cannot convert {24, 30, 15} to time, reason: :invalid_time@spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}
解析由 ISO 8601:2019 描述的扩展“本地时间”格式。
字符串中可能包含时区偏移量，但它们将被简单地丢弃，因为时间中不包含此类信息。
如标准中所述，如果需要，可以省略分隔符“T”，因为在此函数中没有歧义。
示例
iex> Time.from_iso8601("23:50:07")
{:ok, ~T[23:50:07]}
iex> Time.from_iso8601("23:50:07Z")
{:ok, ~T[23:50:07]}
iex> Time.from_iso8601("T23:50:07Z")
{:ok, ~T[23:50:07]}
iex> Time.from_iso8601("23:50:07,0123456")
{:ok, ~T[23:50:07.012345]}
iex> Time.from_iso8601("23:50:07.0123456")
{:ok, ~T[23:50:07.012345]}
iex> Time.from_iso8601("23:50:07.123Z")
{:ok, ~T[23:50:07.123]}
iex> Time.from_iso8601("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:07A")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:07.")
{:error, :invalid_format}
iex> Time.from_iso8601("23:50:61")
{:error, :invalid_time}@spec from_iso8601!(String.t(), Calendar.calendar()) :: t()
解析由 ISO 8601:2019 描述的扩展“本地时间”格式。
如果格式无效，则会引发异常。
示例
iex> Time.from_iso8601!("23:50:07,123Z")
~T[23:50:07.123]
iex> Time.from_iso8601!("23:50:07.123Z")
~T[23:50:07.123]
iex> Time.from_iso8601!("2015:01:23 23-50-07")
** (ArgumentError) cannot parse "2015:01:23 23-50-07" as time, reason: :invalid_formatfrom_seconds_after_midnight(seconds, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
查看源代码 (自 1.11.0 起)@spec from_seconds_after_midnight( integer(), Calendar.microsecond(), Calendar.calendar() ) :: t()
将午夜后的秒数转换为 Time 结构体。
示例
iex> Time.from_seconds_after_midnight(10_000)
~T[02:46:40]
iex> Time.from_seconds_after_midnight(30_000, {5000, 3})
~T[08:20:00.005]
iex> Time.from_seconds_after_midnight(-1)
~T[23:59:59]
iex> Time.from_seconds_after_midnight(100_000)
~T[03:46:40]@spec new( Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond() | non_neg_integer(), Calendar.calendar() ) :: {:ok, t()} | {:error, atom()}
构建新的时间。
要求所有值都是整数。如果每个条目都符合其适当的范围，则返回 {:ok, time}，否则返回 {:error, reason}。
微秒也可以使用精度给出，精度必须是 0 到 6 之间的整数。
内置日历不支持闰秒。
示例
iex> Time.new(0, 0, 0, 0)
{:ok, ~T[00:00:00.000000]}
iex> Time.new(23, 59, 59, 999_999)
{:ok, ~T[23:59:59.999999]}
iex> Time.new(24, 59, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 60, 59, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 59, 60, 999_999)
{:error, :invalid_time}
iex> Time.new(23, 59, 59, 1_000_000)
{:error, :invalid_time}
# Invalid precision
Time.new(23, 59, 59, {999_999, 10})
{:error, :invalid_time}new!(hour, minute, second, microsecond \\ {0, 0}, calendar \\ Calendar.ISO)
查看源代码 (自 1.11.0 起)@spec new!( Calendar.hour(), Calendar.minute(), Calendar.second(), Calendar.microsecond() | non_neg_integer(), Calendar.calendar() ) :: t()
构建新的时间。
要求所有值都是整数。如果每个条目都符合其适当的范围，则返回 time，如果时间无效，则引发异常。
微秒也可以使用精度给出，精度必须是 0 到 6 之间的整数。
内置日历不支持闰秒。
示例
iex> Time.new!(0, 0, 0, 0)
~T[00:00:00.000000]
iex> Time.new!(23, 59, 59, 999_999)
~T[23:59:59.999999]
iex> Time.new!(24, 59, 59, 999_999)
** (ArgumentError) cannot build time, reason: :invalid_time@spec to_erl(Calendar.time()) :: :calendar.time()
将给定的 time 转换为 Erlang 时间元组。
警告：可能会发生精度损失，因为 Erlang 时间元组只包含小时/分钟/秒。
示例
iex> Time.to_erl(~T[23:30:15.999])
{23, 30, 15}
iex> Time.to_erl(~N[2010-04-17 23:30:15.999])
{23, 30, 15}@spec to_iso8601(Calendar.time(), :extended | :basic) :: String.t()
将给定的时间转换为 ISO 8601:2019。
默认情况下，Time.to_iso8601/2 以“扩展”格式返回时间，以便于人类阅读。它还支持通过传递 :basic 选项的“基本”格式。
示例
iex> Time.to_iso8601(~T[23:00:13])
"23:00:13"
iex> Time.to_iso8601(~T[23:00:13.001])
"23:00:13.001"
iex> Time.to_iso8601(~T[23:00:13.001], :basic)
"230013.001"
iex> Time.to_iso8601(~N[2010-04-17 23:00:13])
"23:00:13"@spec to_seconds_after_midnight(Calendar.time()) :: {integer(), non_neg_integer()}
将 Time 结构体转换为午夜后的秒数。
返回值是一个包含秒数和微秒数的二元元组。
示例
iex> Time.to_seconds_after_midnight(~T[23:30:15])
{84615, 0}
iex> Time.to_seconds_after_midnight(~N[2010-04-17 23:30:15.999])
{84615, 999000}@spec to_string(Calendar.time()) :: String.t()
将给定的 time 转换为字符串。
示例
iex> Time.to_string(~T[23:00:00])
"23:00:00"
iex> Time.to_string(~T[23:00:00.001])
"23:00:00.001"
iex> Time.to_string(~T[23:00:00.123456])
"23:00:00.123456"
iex> Time.to_string(~N[2015-01-01 23:00:00.001])
"23:00:00.001"
iex> Time.to_string(~N[2015-01-01 23:00:00.123456])
"23:00:00.123456"返回给定的时间，其中微秒字段被截断到给定的精度（:microsecond、millisecond 或 :second）。
如果给定时间本身的精度低于给定的精度，则返回该时间本身。
示例
iex> Time.truncate(~T[01:01:01.123456], :microsecond)
~T[01:01:01.123456]
iex> Time.truncate(~T[01:01:01.123456], :millisecond)
~T[01:01:01.123]
iex> Time.truncate(~T[01:01:01.123456], :second)
~T[01:01:01]@spec utc_now(Calendar.calendar()) :: t()
返回 UTC 中的当前时间。
示例
iex> time = Time.utc_now()
iex> time.hour >= 0
true