@spec add(
  Calendar.naive_datetime(),
  integer(),
  :day | :hour | :minute | System.time_unit()
) :: t()

將指定的時間量新增到 NaiveDateTime。

接受任何 unit 中的 amount_to_add。 unit 可以是 :day、:hour、:minute、:second 或 System.time_unit/0 中的任何次秒精度。預設為 :second。負值會在時間中往後移動。

此函數總是會考慮根據 Calendar.ISO 計算的單位。

範例

預設使用秒

# adds seconds by default
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], 2)
~N[2014-10-02 00:29:12]

# accepts negative offsets
iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], -2)
~N[2014-10-02 00:29:08]

它也可以使用亞秒精度

iex> NaiveDateTime.add(~N[2014-10-02 00:29:10], 2_000, :millisecond)
~N[2014-10-02 00:29:12.000]

以及天/小時/分鐘

iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 2, :day)
~N[2015-03-02 00:29:10]
iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 36, :hour)
~N[2015-03-01 12:29:10]
iex> NaiveDateTime.add(~N[2015-02-28 00:29:10], 60, :minute)
~N[2015-02-28 01:29:10]

此操作會將純粹日期時間的精度與給定的單位合併

iex> result = NaiveDateTime.add(~N[2014-10-02 00:29:10], 21, :millisecond)
~N[2014-10-02 00:29:10.021]
iex> result.microsecond
{21000, 3}

針對格里曆秒數或 Unix 紀元進行的運算已最佳化

# from Gregorian seconds
iex> NaiveDateTime.add(~N[0000-01-01 00:00:00], 63_579_428_950)
~N[2014-10-02 00:29:10]

傳遞 DateTime 會自動將其轉換為 NaiveDateTime，捨棄時區資訊

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.add(dt, 21, :second)
~N[2000-02-29 23:00:28]

@spec after?(Calendar.naive_datetime(), Calendar.naive_datetime()) :: boolean()

如果第一個 NaiveDateTime 嚴格晚於第二個，則傳回 true。

範例

iex> NaiveDateTime.after?(~N[2022-02-02 11:00:00], ~N[2021-01-01 11:00:00])
true
iex> NaiveDateTime.after?(~N[2021-01-01 11:00:00], ~N[2021-01-01 11:00:00])
false
iex> NaiveDateTime.after?(~N[2021-01-01 11:00:00], ~N[2022-02-02 11:00:00])
false

@spec before?(Calendar.naive_datetime(), Calendar.naive_datetime()) :: boolean()

如果第一個 NaiveDateTime 嚴格早於第二個，則傳回 true。

範例

iex> NaiveDateTime.before?(~N[2021-01-01 11:00:00], ~N[2022-02-02 11:00:00])
true
iex> NaiveDateTime.before?(~N[2021-01-01 11:00:00], ~N[2021-01-01 11:00:00])
false
iex> NaiveDateTime.before?(~N[2022-02-02 11:00:00], ~N[2021-01-01 11:00:00])
false

@spec beginning_of_day(Calendar.naive_datetime()) :: t()

計算一個 NaiveDateTime，作為給定 NaiveDateTime 的第一個時刻。

若要計算 DateTime 的一天開始，請呼叫此函數，然後轉換回 DateTime

datetime
|> NaiveDateTime.beginning_of_day()
|> DateTime.from_naive(datetime.time_zone)

請注意，一天的開始在給定的時區中可能不存在或不明確，因此您必須適當地處理這些情況。

範例

iex> NaiveDateTime.beginning_of_day(~N[2000-01-01 23:00:07.123456])
~N[2000-01-01 00:00:00.000000]

@spec compare(Calendar.naive_datetime(), Calendar.naive_datetime()) :: :lt | :eq | :gt

比較兩個 NaiveDateTime 結構。

如果 first 晚於 second，則傳回 :gt，反之則傳回 :lt。如果兩個 NaiveDateTime 相等，則傳回 :eq。

範例

iex> NaiveDateTime.compare(~N[2016-04-16 13:30:15], ~N[2016-04-28 16:19:25])
:lt
iex> NaiveDateTime.compare(~N[2016-04-16 13:30:15.1], ~N[2016-04-16 13:30:15.01])
:gt

此函數也可拿來比較沒有時區資訊的 DateTime

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.compare(dt, ~N[2000-02-29 23:00:07])
:eq
iex> NaiveDateTime.compare(dt, ~N[2000-01-29 23:00:07])
:gt
iex> NaiveDateTime.compare(dt, ~N[2000-03-29 23:00:07])
:lt

@spec convert(Calendar.naive_datetime(), Calendar.calendar()) ::
  {:ok, t()} | {:error, :incompatible_calendars}

將給定的 naive_datetime 從一個日曆轉換到另一個日曆。

如果無法在日曆之間明確轉換（請參閱 Calendar.compatible_calendars?/2），則會傳回 {:error, :incompatible_calendars} 元組。

範例

想像一下有人實作 Calendar.Holocene，這是一個基於格里曆的日曆，會在目前的格里曆年份中精確地加上 10,000 年

iex> NaiveDateTime.convert(~N[2000-01-01 13:30:15], Calendar.Holocene)
{:ok, %NaiveDateTime{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1,
                     hour: 13, minute: 30, second: 15, microsecond: {0, 0}}}

@spec convert!(Calendar.naive_datetime(), Calendar.calendar()) :: t()

將給定的 naive_datetime 從一個日曆轉換到另一個日曆。

如果無法在日曆之間進行明確轉換（請參閱 Calendar.compatible_calendars?/2），則會引發 ArgumentError。

範例

想像一下有人實作 Calendar.Holocene，這是一個基於格里曆的日曆，會在目前的格里曆年份中精確地加上 10,000 年

iex> NaiveDateTime.convert!(~N[2000-01-01 13:30:15], Calendar.Holocene)
%NaiveDateTime{calendar: Calendar.Holocene, year: 12000, month: 1, day: 1,
               hour: 13, minute: 30, second: 15, microsecond: {0, 0}}

@spec diff(
  Calendar.naive_datetime(),
  Calendar.naive_datetime(),
  :day | :hour | :minute | System.time_unit()
) :: integer()

從 naive_datetime1 中減去 naive_datetime2。

答案可以在任何 :day、:hour、:minute 或 System.time_unit/0 中取得的任何 unit 中回傳。單位是根據 Calendar.ISO 測量，預設為 :second。

不支援小數結果，且會進行截斷。

範例

iex> NaiveDateTime.diff(~N[2014-10-02 00:29:12], ~N[2014-10-02 00:29:10])
2
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:12], ~N[2014-10-02 00:29:10], :microsecond)
2_000_000

iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10.042], ~N[2014-10-02 00:29:10.021])
0
iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10.042], ~N[2014-10-02 00:29:10.021], :millisecond)
21

iex> NaiveDateTime.diff(~N[2014-10-02 00:29:10], ~N[2014-10-02 00:29:12])
-2
iex> NaiveDateTime.diff(~N[-0001-10-02 00:29:10], ~N[-0001-10-02 00:29:12])
-2

它也可以計算日、時或分的差異

iex> NaiveDateTime.diff(~N[2014-10-10 00:29:10], ~N[2014-10-02 00:29:10], :day)
8
iex> NaiveDateTime.diff(~N[2014-10-02 12:29:10], ~N[2014-10-02 00:29:10], :hour)
12
iex> NaiveDateTime.diff(~N[2014-10-02 00:39:10], ~N[2014-10-02 00:29:10], :minute)
10

但它也會將未完成的天數四捨五入為零

iex> NaiveDateTime.diff(~N[2014-10-10 00:29:09], ~N[2014-10-02 00:29:10], :day)
7

@spec end_of_day(Calendar.naive_datetime()) :: t()

計算一個 NaiveDateTime，作為給定 NaiveDateTime 的最後一個時刻。

若要計算 DateTime 的一天結束，請呼叫此函式，然後轉換回 DateTime

datetime
|> NaiveDateTime.end_of_day()
|> DateTime.from_naive(datetime.time_zone)

請注意，在給定的時區中，一天的結束可能不存在或不明確，因此您必須適當地處理這些情況。

範例

iex> NaiveDateTime.end_of_day(~N[2000-01-01 23:00:07.123456])
~N[2000-01-01 23:59:59.999999]

@spec from_erl(:calendar.datetime(), Calendar.microsecond(), Calendar.calendar()) ::
  {:ok, t()} | {:error, atom()}

將一個 Erlang datetime tuple 轉換為 NaiveDateTime 結構。

嘗試轉換無效的 ISO 日曆日期會產生錯誤組。

範例

iex> NaiveDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}})
{:ok, ~N[2000-01-01 13:30:15]}
iex> NaiveDateTime.from_erl({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
{:ok, ~N[2000-01-01 13:30:15.005]}
iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
{:error, :invalid_date}
iex> NaiveDateTime.from_erl({{2000, 13, 1}, {13, 30, 15}})
{:error, :invalid_date}

@spec from_erl!(:calendar.datetime(), Calendar.microsecond(), Calendar.calendar()) ::
  t()

將一個 Erlang datetime tuple 轉換為 NaiveDateTime 結構。

如果日期時間無效，則會引發錯誤。嘗試轉換無效的 ISO 日曆日期會產生錯誤組。

範例

iex> NaiveDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}})
~N[2000-01-01 13:30:15]
iex> NaiveDateTime.from_erl!({{2000, 1, 1}, {13, 30, 15}}, {5000, 3})
~N[2000-01-01 13:30:15.005]
iex> NaiveDateTime.from_erl!({{2000, 13, 1}, {13, 30, 15}})
** (ArgumentError) cannot convert {{2000, 13, 1}, {13, 30, 15}} to naive datetime, reason: :invalid_date

@spec from_gregorian_seconds(integer(), Calendar.microsecond(), Calendar.calendar()) ::
  t()

將格里曆秒數轉換為 NaiveDateTime 結構。

範例

iex> NaiveDateTime.from_gregorian_seconds(1)
~N[0000-01-01 00:00:01]
iex> NaiveDateTime.from_gregorian_seconds(63_755_511_991, {5000, 3})
~N[2020-05-01 00:26:31.005]
iex> NaiveDateTime.from_gregorian_seconds(-1)
~N[-0001-12-31 23:59:59]

@spec from_iso8601(String.t(), Calendar.calendar()) :: {:ok, t()} | {:error, atom()}

解析 ISO 8601:2019 所描述的「日期和時間」擴充格式。

時區偏移量可以包含在字串中，但它們只會被捨棄，因為此類資訊未包含在簡潔日期時間中。

如標準中所述，如果需要，可以省略分隔符號「T」，因為此函式中沒有歧義。

請注意，內建的 Calendar.ISO 不支援閏秒。

範例

iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07")
{:ok, ~N[2015-01-23 23:50:07]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07")
{:ok, ~N[2015-01-23 23:50:07]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07Z")
{:ok, ~N[2015-01-23 23:50:07]}

iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07.0")
{:ok, ~N[2015-01-23 23:50:07.0]}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07,0123456")
{:ok, ~N[2015-01-23 23:50:07.012345]}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07.0123456")
{:ok, ~N[2015-01-23 23:50:07.012345]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123Z")
{:ok, ~N[2015-01-23 23:50:07.123]}

iex> NaiveDateTime.from_iso8601("2015-01-23P23:50:07")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015:01:23 23-50-07")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:07A")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23 23:50:61")
{:error, :invalid_time}
iex> NaiveDateTime.from_iso8601("2015-01-32 23:50:07")
{:error, :invalid_date}

iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123+02:30")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123+00:00")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-02:30")
{:ok, ~N[2015-01-23 23:50:07.123]}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-00:00")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-00:60")
{:error, :invalid_format}
iex> NaiveDateTime.from_iso8601("2015-01-23T23:50:07.123-24:00")
{:error, :invalid_format}

@spec from_iso8601!(String.t(), Calendar.calendar()) :: t()

解析 ISO 8601:2019 所描述的「日期和時間」擴充格式。

如果格式無效，則會引發錯誤。

範例

iex> NaiveDateTime.from_iso8601!("2015-01-23T23:50:07.123Z")
~N[2015-01-23 23:50:07.123]
iex> NaiveDateTime.from_iso8601!("2015-01-23T23:50:07,123Z")
~N[2015-01-23 23:50:07.123]
iex> NaiveDateTime.from_iso8601!("2015-01-23P23:50:07")
** (ArgumentError) cannot parse "2015-01-23P23:50:07" as naive datetime, reason: :invalid_format

@spec local_now(Calendar.calendar()) :: t()

傳回 Elixir 程式執行機器上的「當地時間」。

警告：此函式可能會造成隱藏的錯誤。它會根據執行時間的時區設定而定。這可能會變更，並設定為有夏令時間跳躍（春季前進或秋季後退）的時區。

此函式可用於顯示機器目前的時區設定時間。範例是桌面程式會顯示時鐘給使用者。對於任何其他用途，使用此函式可能不是個好主意。

對於大多數情況，請改用 DateTime.now/2 或 DateTime.utc_now/1。

不包含小數秒數。

範例

iex> naive_datetime = NaiveDateTime.local_now()
iex> naive_datetime.year >= 2019
true

@spec new(Date.t(), Time.t()) :: {:ok, t()}

根據日期和時間結構建立一個天真的日期時間。

範例

iex> NaiveDateTime.new(~D[2010-01-13], ~T[23:00:07.005])
{:ok, ~N[2010-01-13 23:00:07.005]}

@spec new(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond() | non_neg_integer(),
  Calendar.calendar()
) :: {:ok, t()} | {:error, atom()}

建立一個新的 ISO 天真日期時間。

預期所有值都是整數。如果每個輸入都符合適當的範圍，則傳回 {:ok, naive_datetime}；否則傳回 {:error, reason}。

範例

iex> NaiveDateTime.new(2000, 1, 1, 0, 0, 0)
{:ok, ~N[2000-01-01 00:00:00]}
iex> NaiveDateTime.new(2000, 13, 1, 0, 0, 0)
{:error, :invalid_date}
iex> NaiveDateTime.new(2000, 2, 29, 0, 0, 0)
{:ok, ~N[2000-02-29 00:00:00]}
iex> NaiveDateTime.new(2000, 2, 30, 0, 0, 0)
{:error, :invalid_date}
iex> NaiveDateTime.new(2001, 2, 29, 0, 0, 0)
{:error, :invalid_date}

iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1})
{:ok, ~N[2000-01-01 23:59:59.0]}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 999_999)
{:ok, ~N[2000-01-01 23:59:59.999999]}
iex> NaiveDateTime.new(2000, 1, 1, 24, 59, 59, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 60, 59, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 60, 999_999)
{:error, :invalid_time}
iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 1_000_000)
{:error, :invalid_time}

iex> NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO)
{:ok, ~N[2000-01-01 23:59:59.0]}

@spec new!(Date.t(), Time.t()) :: t()

根據日期和時間結構建立一個天真的日期時間。

範例

iex> NaiveDateTime.new!(~D[2010-01-13], ~T[23:00:07.005])
~N[2010-01-13 23:00:07.005]

@spec new!(
  Calendar.year(),
  Calendar.month(),
  Calendar.day(),
  Calendar.hour(),
  Calendar.minute(),
  Calendar.second(),
  Calendar.microsecond() | non_neg_integer(),
  Calendar.calendar()
) :: t()

建立一個新的 ISO 天真日期時間。

預期所有值都是整數。如果每個輸入都符合適當的範圍，則傳回 naive_datetime；如果時間或日期無效，則會引發例外。

範例

iex> NaiveDateTime.new!(2000, 1, 1, 0, 0, 0)
~N[2000-01-01 00:00:00]
iex> NaiveDateTime.new!(2000, 2, 29, 0, 0, 0)
~N[2000-02-29 00:00:00]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1})
~N[2000-01-01 23:59:59.0]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, 999_999)
~N[2000-01-01 23:59:59.999999]
iex> NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO)
~N[2000-01-01 23:59:59.0]
iex> NaiveDateTime.new!(2000, 1, 1, 24, 59, 59, 999_999)
** (ArgumentError) cannot build naive datetime, reason: :invalid_time

@spec to_date(Calendar.naive_datetime()) :: Date.t()

將 NaiveDateTime 轉換成 Date。

由於 Date 不包含時間資訊，因此在轉換過程中資料會遺失。

範例

iex> NaiveDateTime.to_date(~N[2002-01-13 23:00:07])
~D[2002-01-13]

@spec to_erl(Calendar.naive_datetime()) :: :calendar.datetime()

將 NaiveDateTime 結構轉換成 Erlang 日期時間元組。

僅支援轉換 ISO 日曆中的樸素日期時間，嘗試轉換其他日曆中的樸素日期時間會引發例外。

警告：可能會發生精確度損失，因為 Erlang 時間元組只儲存小時/分鐘/秒。

範例

iex> NaiveDateTime.to_erl(~N[2000-01-01 13:30:15])
{{2000, 1, 1}, {13, 30, 15}}

此函式也可轉換 DateTime 為不含時區資訊的 Erlang datetime tuple

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_erl(dt)
{{2000, 2, 29}, {23, 00, 07}}

@spec to_gregorian_seconds(Calendar.naive_datetime()) ::
  {integer(), non_neg_integer()}

將 NaiveDateTime 結構轉換成格里曆秒數和微秒數。

範例

iex> NaiveDateTime.to_gregorian_seconds(~N[0000-01-01 00:00:01])
{1, 0}
iex> NaiveDateTime.to_gregorian_seconds(~N[2020-05-01 00:26:31.005])
{63_755_511_991, 5000}

@spec to_iso8601(Calendar.naive_datetime(), :basic | :extended) :: String.t()

將指定的無時區日期時間轉換成 ISO 8601:2019。

預設情況下，NaiveDateTime.to_iso8601/2 傳回格式化為「延伸」格式的樸素日期時間，以供人類閱讀。它也支援透過傳遞 :basic 選項來使用「基本」格式。

僅支援轉換 ISO 日曆中的樸素日期時間，嘗試轉換其他日曆中的樸素日期時間會引發例外。

範例

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13])
"2000-02-28T23:00:13"

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001])
"2000-02-28T23:00:13.001"

iex> NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001], :basic)
"20000228T230013.001"

此函式也可轉換 DateTime 為不含時區資訊的 ISO 8601

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_iso8601(dt)
"2000-02-29T23:00:07"

@spec to_string(Calendar.naive_datetime()) :: String.t()

根據其日曆將指定的無時區日期時間轉換成字串。

範例

iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13])
"2000-02-28 23:00:13"
iex> NaiveDateTime.to_string(~N[2000-02-28 23:00:13.001])
"2000-02-28 23:00:13.001"
iex> NaiveDateTime.to_string(~N[-0100-12-15 03:20:31])
"-0100-12-15 03:20:31"

此函式也可轉換 DateTime 為不含時區資訊的字串

iex> dt = %DateTime{year: 2000, month: 2, day: 29, zone_abbr: "CET",
...>                hour: 23, minute: 0, second: 7, microsecond: {0, 0},
...>                utc_offset: 3600, std_offset: 0, time_zone: "Europe/Warsaw"}
iex> NaiveDateTime.to_string(dt)
"2000-02-29 23:00:07"

@spec to_time(Calendar.naive_datetime()) :: Time.t()

將 NaiveDateTime 轉換成 Time。

由於 Time 不包含日期資訊，資料會在轉換過程中遺失。

範例

iex> NaiveDateTime.to_time(~N[2002-01-13 23:00:07])
~T[23:00:07]

@spec truncate(t(), :microsecond | :millisecond | :second) :: t()

傳回指定的無時區日期時間，微秒欄位已截斷至指定的精度（:microsecond、:millisecond 或 :second）。

如果樸素日期時間的精度已低於指定的精度，則傳回未變更的樸素日期時間。

範例

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :microsecond)
~N[2017-11-06 00:23:51.123456]

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :millisecond)
~N[2017-11-06 00:23:51.123]

iex> NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :second)
~N[2017-11-06 00:23:51]

@spec utc_now(Calendar.calendar() | :native | :microsecond | :millisecond | :second) ::
  t()

傳回 UTC 中目前的無時區日期時間。

如果可以，建議使用 DateTime.utc_now/0，因為與 NaiveDateTime 相反，它會保留時區資訊。

您也可以提供時間單位來自動截斷樸素日期時間。此功能自 v1.15.0 起提供。

範例

iex> naive_datetime = NaiveDateTime.utc_now()
iex> naive_datetime.year >= 2016
true

iex> naive_datetime = NaiveDateTime.utc_now(:second)
iex> naive_datetime.microsecond
{0, 0}

@spec utc_now(:native | :microsecond | :millisecond | :second, Calendar.calendar()) ::
  t()

傳回 UTC 中目前的無時區日期時間，支援特定日曆和精度。

盡可能優先使用 DateTime.utc_now/2，因為與 NaiveDateTime 相反，它會保留時區資訊。

範例

iex> naive_datetime = NaiveDateTime.utc_now(:second, Calendar.ISO)
iex> naive_datetime.year >= 2016
true

iex> naive_datetime = NaiveDateTime.utc_now(:second, Calendar.ISO)
iex> naive_datetime.microsecond
{0, 0}