檢視原始碼 時間 (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}此模組上的函式會使用 時間 結構，以及包含與 時間 結構相同欄位的任何結構，例如 NaiveDateTime 和 DateTime。此類函式會在類型規格中預期 Calendar.time/0 (而非 t/0)。
開發人員應避免直接建立時間結構，而應依賴此模組提供的函式，以及第三方日曆函式庫中的函式。
比較時間
使用 ==/2、>/2、</2 等符號在 Elixir 中進行比較時，會根據結構和 時間 結構欄位進行比較。若要正確比較時間，請使用 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]摘要
函式
將 amount_to_add 個 unit 加入指定的 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()
將 amount_to_add 個 unit 加入指定的 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 或任何子秒 unit，這些單位可從 System.time_unit/0 取得。如果第一個時間值早於第二個時間值，則傳回負數。
單位根據 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()
建立新的時間。
預期所有值都是整數。如果每個條目都符合其適當的範圍，則傳回 時間，如果時間無效，則會引發錯誤。
微秒也可以用精度表示，精度必須是 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