NaiveDateTime

A NaiveDateTime struct (without a time zone) and functions.

The NaiveDateTime struct contains the fields year, month, day, hour, minute, second, microsecond and calendar. New naive datetimes can be built with the new/2 and new/8 functions or using the ~N (see Kernel.sigil_N/2) sigil:

~N[2000-01-01 23:00:07]

The date and time fields in the struct can be accessed directly:

naive = ~N[2000-01-01 23:00:07]
naive.year

naive.second

We call them “naive” because this datetime representation does not have a time zone. This means the datetime may not actually exist in certain areas in the world even though it is valid.

For example, when daylight saving changes are applied by a region, the clock typically moves forward or backward by one hour. This means certain datetimes never occur or may occur more than once. Since NaiveDateTime is not validated against a time zone, such errors would go unnoticed.

Developers should avoid creating the NaiveDateTime structs directly and instead, rely on the functions provided by this module as well as the ones in third-party calendar libraries.

Comparing naive date times

Comparisons in Elixir using ==/2, >/2, = 2019 ``` ## Function new/2 Builds a naive datetime from date and time structs. ## Examples ```elixir NaiveDateTime.new(~D[2010-01-13], ~T[23:00:07.005]) ``` ## Function new/8 Builds a new ISO naive datetime. Expects all values to be integers. Returnsif each entry fits its appropriate range, returnsotherwise. ## Examples ```elixir NaiveDateTime.new(2000, 1, 1, 0, 0, 0) ``` ```elixir NaiveDateTime.new(2000, 13, 1, 0, 0, 0) ``` ```elixir NaiveDateTime.new(2000, 2, 29, 0, 0, 0) ``` ```elixir NaiveDateTime.new(2000, 2, 30, 0, 0, 0) ``` ```elixir NaiveDateTime.new(2001, 2, 29, 0, 0, 0) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1}) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 999_999) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 24, 59, 59, 999_999) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 60, 59, 999_999) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 59, 60, 999_999) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 59, 59, 1_000_000) ``` ```elixir NaiveDateTime.new(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO) ``` ## Function new!/2 Builds a naive datetime from date and time structs. ## Examples ```elixir NaiveDateTime.new!(~D[2010-01-13], ~T[23:00:07.005]) ``` ## Function new!/8 Builds a new ISO naive datetime. Expects all values to be integers. Returnsnaive_datetimeif each entry fits its appropriate range, raises if time or date is invalid. ## Examples ```elixir NaiveDateTime.new!(2000, 1, 1, 0, 0, 0) ``` ```elixir NaiveDateTime.new!(2000, 2, 29, 0, 0, 0) ``` ```elixir NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1}) ``` ```elixir NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, 999_999) ``` ```elixir NaiveDateTime.new!(2000, 1, 1, 23, 59, 59, {0, 1}, Calendar.ISO) ``` ```elixir NaiveDateTime.new!(2000, 1, 1, 24, 59, 59, 999_999) ``` ## Function to_date/1 Converts aNaiveDateTimeinto aDate. BecauseDatedoes not hold time information, data will be lost during the conversion. ## Examples ```elixir NaiveDateTime.to_date(~N[2002-01-13 23:00:07]) ``` ## Function to_erl/1 Converts aNaiveDateTimestruct to an Erlang datetime tuple. Only supports converting naive datetimes which are in the ISO calendar, attempting to convert naive datetimes from other calendars will raise. WARNING: Loss of precision may occur, as Erlang time tuples only store hour/minute/second. ## Examples ```elixir NaiveDateTime.to_erl(~N[2000-01-01 13:30:15]) ``` This function can also be used to convert a DateTime to an Erlang datetime tuple without the time zone information: ```elixir 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" } NaiveDateTime.to_erl(dt) ``` ## Function to_gregorian_seconds/1 Converts aNaiveDateTimestruct to a number of gregorian seconds and microseconds. ## Examples ```elixir NaiveDateTime.to_gregorian_seconds(~N[0000-01-01 00:00:01]) ``` ```elixir NaiveDateTime.to_gregorian_seconds(~N[2020-05-01 00:26:31.005]) ``` ## Function to_iso8601/2 Converts the given naive datetime to [ISO 8601:2019](https://en.wikipedia.org/wiki/ISO_8601). By default,NaiveDateTime.to_iso8601/2returns naive datetimes formatted in the "extended" format, for human readability. It also supports the "basic" format through passing the:basicoption. Only supports converting naive datetimes which are in the ISO calendar, attempting to convert naive datetimes from other calendars will raise. ### Examples ```elixir NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13]) ``` ```elixir NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001]) ``` ```elixir NaiveDateTime.to_iso8601(~N[2000-02-28 23:00:13.001], :basic) ``` This function can also be used to convert a DateTime to ISO 8601 without the time zone information: ```elixir 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" } NaiveDateTime.to_iso8601(dt) ``` ## Function to_string/1 Converts the given naive datetime to a string according to its calendar. ### Examples ```elixir NaiveDateTime.to_string(~N[2000-02-28 23:00:13]) ``` ```elixir NaiveDateTime.to_string(~N[2000-02-28 23:00:13.001]) ``` ```elixir NaiveDateTime.to_string(~N[-0100-12-15 03:20:31]) ``` This function can also be used to convert a DateTime to a string without the time zone information: ```elixir 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" } NaiveDateTime.to_string(dt) ``` ## Function to_time/1 Converts aNaiveDateTimeintoTime. BecauseTimedoes not hold date information, data will be lost during the conversion. ## Examples ```elixir NaiveDateTime.to_time(~N[2002-01-13 23:00:07]) ``` ## Function truncate/2 Returns the given naive datetime with the microsecond field truncated to the given precision (:microsecond,:millisecondor:second). The given naive datetime is returned unchanged if it already has lower precision than the given precision. ## Examples ```elixir NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :microsecond) ``` ```elixir NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :millisecond) ``` ```elixir NaiveDateTime.truncate(~N[2017-11-06 00:23:51.123456], :second) ``` ## Function utc_now/1 Returns the current naive datetime in UTC. Prefer usingDateTime.utc_now/0when possible as, opposite toNaiveDateTime`, it will keep the time zone information. ## Examples elixir naive_datetime = NaiveDateTime.utc_now() naive_datetime.year >= 2016