时间 | Time

时间结构和功能。

时间结构包含字段(小时、分钟、秒和微秒)。新时代可以用new/4函数或使用~T警号：

iex> ~T[23:00:07.001]
~T[23:00:07.001]

双双new/4然后Sigil返回一个结构，其中可以直接访问时间字段：

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）。

开发人员应避免直接创建时间结构，而应依赖此模块提供的函数以及第三方日历库中的函数。

比较时间

使用==，，，>，，，<和类似的结构，并且基于Time构造字段。若要在时间间进行适当的比较，请使用compare/2功能。

类型

T%28%29

功能

compare(time1, time2)

比较两种时间结构

convert(time, calendar)

皈依time到不同的日历

转换！（时间，日历）

类似于Time.convert/2，但提出了一个ArgumentError如果无法在两个日历之间进行转换

diff（time1，time2，单位\：秒）

返回两次之间的差值，仅考虑小时、分钟秒和微秒。

from_erl（元组，微秒\ {0，0}，日历\ Calendar.ISO）

将Erlang时间元组转换为Time结构

from_erl！（元组，微秒\ {0，0}，日历\ Calendar.ISO）

将Erlang时间元组转换为Time结构

from_iso8601（字符串，日历\ Calendar.ISO）

解析扩展的“本地时间”格式。ISO 8601：2004

from_iso8601！（串）

解析扩展的“本地时间”格式。ISO 8601：2004

新（小时，分钟，秒，微秒\ {0，0}，日历\ Calendar.ISO）

创造新时代

to_erl（时间）

转换time为Erlang时间元组

to_iso8601（时间，格式\：扩展）

将给定时间转换为ISO 8601：2004

to_string（时间）

转换给定的time成串

utc_now（日历\ Calendar.ISO）

返回UTC的当前时间。

t()

t() :: %Time{calendar: Calendar.calendar, hour: Calendar.hour, microsecond: Calendar.microsecond, minute: Calendar.minute, second: Calendar.second}

compare(time1, time2)

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

convert(time, calendar)

convert(Calendar.time, Calendar.calendar) ::
  {:ok, t} |
  {:error, atom}

转换time为不同的日历。

回报{:ok, time}如果转换成功，或{:error, reason}如果不是因为某种原因。

实例

想象一下有人Calendar.Holocene，一种基于公历的日历，它将当前的公历年相加整整10000年：

iex> Time.convert(~T[13:30:15], Calendar.Holocene)
{:ok, %Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}

convert!(time, calendar)

convert!(Calendar.time, Calendar.calendar) :: t

类似于Time.convert/2，但提出了一个ArgumentError如果无法在两个日历之间进行转换。

实例

想象一下有人Calendar.Holocene，一种基于公历的日历，它将当前的公历年相加整整10000年：

iex> Time.convert!(~T[13:30:15], Calendar.Holocene)
%Time{calendar: Calendar.Holocene, hour: 13, minute: 30, second: 15, microsecond: {0, 0}}

diff(time1, time2, unit \ :second)

diff(Calendar.time, Calendar.time, System.time_unit) :: integer

返回两次之间的差值，仅考虑小时、分钟秒和微秒。

就像compare/2兼用Time可以使用包含时间的结构和其他结构。例如，如果NaiveDateTime或DateTime则只考虑小时、月、秒和微秒。在计算差异时，将忽略有关日期或时区的任何其他信息。

答案可以在任何地方返回。unit可从System.time_unit/0如果第一个单元小于第二个单元，则返回一个负数。

此函数返回秒的差，其中秒是根据Calendar.ISO...

实例

iex> Time.diff(~T[00:29:12], ~T[00:29:10])
2

# When passing a [`NaiveDateTime`](NaiveDateTime.html) the date part is ignored.
iex> Time.diff(~N[2017-01-01 00:29:12], ~T[00:29:10])
2

# Two [`NaiveDateTime`](NaiveDateTime.html) 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

from_erl(tuple, microsecond \ {0, 0}, calendar \ Calendar.ISO)

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}

from_erl!(tuple, microsecond \ {0, 0}, calendar \ Calendar.ISO)

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

from_iso8601(string, calendar \ Calendar.ISO)

解析扩展的“本地时间”格式。ISO 8601：2004...

时区偏移量可能包含在字符串中，但它们将被简单地丢弃，因为这些信息有时不包括在内。

按照标准中的规定，如果需要，可以省略分隔符“T”，因为该函数中没有歧义。

不支持精度较低的时间表示。

注意，虽然ISO 8601允许时间指定24：00：00为第二天的零小时，但该表示法不受Elixir的支持。

实例

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}

from_iso8601!(string)

from_iso8601!(String.t) :: t

解析扩展的“本地时间”格式。ISO 8601：2004...

如果格式无效，则引发。

实例

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_format

new(hour, minute, second, microsecond \ {0, 0}, calendar \ Calendar.ISO)

new(Calendar.hour, Calendar.minute, Calendar.second, Calendar.microsecond, Calendar.calendar) ::
  {:ok, t} |
  {:error, atom}

创造一个新时代。

期望所有的值都是整数。回报{:ok, time}如果每个条目符合其适当范围，则返回{:error, reason}否则。

注意，在闰秒的情况下，时间可能有60秒。微秒也可以给出一个精度，它必须是一个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(23, 59, 60, 999_999)
{:ok, ~T[23:59:60.999999]}

# Time with microseconds and their precision
iex> Time.new(23, 59, 60, {10_000, 2})
{:ok, ~T[23:59:60.01]}

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, 61, 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}

to_erl(time)

to_erl(Calendar.time) :: :calendar.time

皈依time一个二郎时代的元组。

警告：由于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}

to_iso8601(time, format \ :extended)

to_iso8601(Calendar.time, :extended | :basic) :: String.t

将给定时间转换为ISO 8601：2004...

默认情况下，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"

to_string(time)

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"

utc_now(calendar \ Calendar.ISO)

utc_now(Calendar.calendar) :: t

返回UTC的当前时间。

实例

iex> time = Time.utc_now()
iex> time.hour >= 0
true