tempo/naive_datetime · gtempo

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.add(duration.minutes(3))
// -> naive_datetime.literal("2024-06-21T23:20:00")

as_period

</>

pub fn as_period(
  start start: NaiveDateTime,
  end end: NaiveDateTime,
) -> Period

Creates a period between two naive datetimes. The specified start and end datetimes will be swapped if the start datetime is later than the end datetime.

Examples

naive_datetime.to_period(
  start: naive_datetime.literal("2024-06-12T23:17:00")
  end: naive_datetime.literal("2024-06-16T01:16:12"),
)
|> period.as_days
// -> 3

naive_datetime.to_period(
  start: naive_datetime.literal("2024-06-12T23:17:00"),
  end: naive_datetime.literal("2024-06-16T01:18:12"),
)
|> period.format
// -> "3 days, 2 hours, and 1 minute"

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.compare(to: naive_datetime.literal("2024-06-21T23:17:00"))
// -> order.Eq

naive_datetime.literal("2023-05-11T13:15:00")
|> naive_datetime.compare(to: naive_datetime.literal("2024-06-21T23:17:00"))
// -> order.Lt

difference

</>

pub fn difference(
  from a: NaiveDateTime,
  to b: NaiveDateTime,
) -> Period

Deprecated: Use `as_period` instead, this function is an alias for it. This function has the same name and one label as the `time.difference` and `date.difference` functions, but with different logic, making it too confusing.

Returns the difference between two naive datetimes as a period between them.

Examples

naive_datetime.literal("2024-06-16T01:16:12")
|> naive_datetime.difference_from(
  naive_datetime.literal("2024-06-12T23:17:00"),
)
|> period.as_days
// -> 3

naive_datetime.literal("2024-06-16T01:18:12")
|> naive_datetime.difference_from(
  naive_datetime.literal("2024-06-12T23:17:00"),
)
|> period.format
// -> "3 days, 2 hours, and 1 minute"

drop_time

</>

pub fn drop_time(datetime: NaiveDateTime) -> NaiveDateTime

Drops the time of a naive datetime, setting it to zero.

Examples

naive_datetime.literal("2024-06-13T23:17:00")
|> naive_datetime.drop_time
// -> datetime.literal("2024-06-13T00:00:00")

format

</>

pub fn format(
  naive_datetime: NaiveDateTime,
  in fmt: String,
) -> String

Formats a naive datetime value using the provided format string. Implements the same formatting directives as the great Day.js library: https://day.js.org/docs/en/display/format.

Values can be escaped by putting brackets around them, like “[Hello!] YYYY”.

Available directives: YY (two-digit year), YYYY (four-digit year), M (month), MM (two-digit month), MMM (short month name), MMMM (full month name), D (day of the month), DD (two-digit day of the month), d (day of the week), dd (min day of the week), ddd (short day of week), dddd (full day of the week), H (hour), HH (two-digit hour), h (12-hour clock hour), hh (two-digit 12-hour clock hour), m (minute), mm (two-digit minute), s (second), ss (two-digit second), SSS (millisecond), SSSS (microsecond), SSSSS (nanosecond), A (AM/PM), a (am/pm).

Example

naive_datetime.literal("2024-06-21T13:42:11.314")
|> naive_datetime.format("ddd @ h:mm A")
// -> "Fri @ 1:42 PM"

naive_datetime.literal("2024-06-03T09:02:01")
|> naive_datetime.format("YY YYYY M MM MMM MMMM D DD d dd ddd")
// --------------------> "24 2024 6 06 Jun June 3 03 1 Mo Mon"

naive_datetime.literal("2024-06-03T09:02:01.014920202")
|> naive_datetime.format("dddd SSS SSSS SSSSS")
// -> "Monday 014 014920 014920202"

naive_datetime.literal("2024-06-03T13:02:01")
|> naive_datetime.format("H HH h hh m mm s ss a A [An ant]")
// -------------------> "13 13 1 01 2 02 1 01 pm PM An ant"

from_string

</>

pub fn from_string(
  datetime: String,
) -> Result(NaiveDateTime, Error)

Parses a naive datetime string in the format YYYY-MM-DDThh:mm:ss.s, YYYY-MM-DD hh:mm:ss.s, YYYY-MM-DD, YYYY-M-D, YYYY/MM/DD, YYYY/M/D, YYYY.MM.DD, YYYY.M.D, YYYY_MM_DD, YYYY_M_D, YYYY MM DD, YYYY M D, or YYYYMMDD.

Examples

naive_datetime.from_string("20240612")
// -> Ok(naive_datetime.literal("2024-06-12T00:00:00"))

naive_datetime.from_string("2024-06-21 23:17:00")
// -> Ok(naive_datetime.literal("2024-06-21T23:17:00"))

naive_datetime.from_string("24-06-12|23:17:00")
// -> Error(tempo.NaiveDateTimeInvalidFormat)

get_date

</>

pub fn get_date(datetime: NaiveDateTime) -> Date

Gets the date of a naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.get_date
// -> date.literal("2024-06-21")

get_time

</>

pub fn get_time(datetime: NaiveDateTime) -> Time

Gets the time of a naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.get_time
// -> time.literal("23:17:00")

is_earlier

</>

pub fn is_earlier(
  a: NaiveDateTime,
  than b: NaiveDateTime,
) -> Bool

Checks if the first naive datetime is earlier than the second naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_earlier(
  than: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> False

naive_datetime.literal("2013-06-12T23:17:00")
|> naive_datetime.is_earlier(
  than: naive_datetime.literal("2024-06-12T23:17:00"),
)
// -> True

is_earlier_or_equal

</>

pub fn is_earlier_or_equal(
  a: NaiveDateTime,
  to b: NaiveDateTime,
) -> Bool

Checks if the first naive datetime is earlier or equal to the second naive datetime.

Examples

naive_datetime.literal("2024-08-12T23:17:00")
|> naive_datetime.is_earlier_or_equal(
  to: naive_datetime.literal("2024-06-12T00:00:00"),
)
// -> False

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_earlier_or_equal(
  to: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> True

is_equal

</>

pub fn is_equal(a: NaiveDateTime, to b: NaiveDateTime) -> Bool

Checks if the first naive datetime is equal to the second naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_equal(
  to: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> True

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_equal(
  to: naive_datetime.literal("2024-06-21T23:17:01"),
)
// -> False

is_later

</>

pub fn is_later(a: NaiveDateTime, than b: NaiveDateTime) -> Bool

Checks if the first naive datetime is later than the second naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_later(
  than: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> False

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_later(
  than: naive_datetime.literal("2022-04-12T00:00:00"),
)
// -> True

is_later_or_equal

</>

pub fn is_later_or_equal(
  a: NaiveDateTime,
  to b: NaiveDateTime,
) -> Bool

Checks if the first naive datetime is later or equal to the second naive datetime.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.is_later_or_equal(
  to: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> True

naive_datetime.literal("2022-04-12T00:00:00")
|> naive_datetime.is_later_or_equal(
  to: naive_datetime.literal("2024-06-21T23:17:00"),
)
// -> False

literal

</>

pub fn literal(naive_datetime: String) -> NaiveDateTime

Creates a new naive datetime value from a string literal, but will panic if the string is invalid.

Useful for declaring date literals that you know are valid within your
program.

Examples

naive_datetime.literal("2024-06-21T23:04:00.009")
|> naive_datetime.to_string
// -> "2024-06-21T23:04:00.009"

naive_datetime.literal("2024-06-21T23:04:00.009-04:00")
// panic

new

</>

pub fn new(date: Date, time: Time) -> NaiveDateTime

Creates a new naive datetime from a date and time value.

Examples

naive_datetime.new(
  date.literal("2024-06-21"), 
  time.literal("23:04:00.009"),
)
// -> naive_datetime.literal("2024-06-21T23:04:00.009")

now_local

</>

pub fn now_local() -> NaiveDateTime

Gets the current local naive datetime of the host. Always prefer using duration.start_monotonic to record time passing and time.now_unique to sort events by time.

Examples

naive_datetime.now_local()
|> naive_datetime.to_string
// -> "2024-06-21T12:23:23.380956212"

now_utc

</>

pub fn now_utc() -> NaiveDateTime

Gets the current UTC naive datetime of the host. Always prefer using duration.start_monotonic to record time passing and time.now_unique to sort events by time.

Examples

naive_datetime.now_utc()
|> naive_datetime.to_string
// -> "2024-06-21T16:23:23.380413364"

parse

</>

pub fn parse(
  str: String,
  in fmt: String,
) -> Result(NaiveDateTime, Error)

Parses a naive datetime string in the provided format. Always prefer using this over parse_any. All parsed formats must have all parts of a naive datetime (date and time). Use the other modules for parsing lesser date time values.

Values can be escaped by putting brackets around them, like “[Hello!] YYYY”.

Available directives: YY (two-digit year), YYYY (four-digit year), M (month), MM (two-digit month), MMM (short month name), MMMM (full month name), D (day of the month), DD (two-digit day of the month), H (hour), HH (two-digit hour), h (12-hour clock hour), hh (two-digit 12-hour clock hour), m (minute), mm (two-digit minute), s (second), ss (two-digit second), SSS (millisecond), SSSS (microsecond), SSSSS (nanosecond), A (AM/PM), a (am/pm).

Example

naive_datetime.parse("2024/06/08, 13:42:11", "YYYY/MM/DD, HH:mm:ss")
// -> Ok(naive_datetime.literal("2024-06-08T13:42:11"))

naive_datetime.parse("January 13, 2024. 3:42:11", "MMMM DD, YYYY. H:mm:ss")
// -> Ok(naive_datetime.literal("2024-01-13T03:42:11"))

naive_datetime.parse("Hi! 2024 11 13 12 2 am", "[Hi!] YYYY M D h m a")
// -> Ok(naive_datetime.literal("2024-11-13T00:02:00"))

parse_any

</>

pub fn parse_any(str: String) -> Result(NaiveDateTime, Error)

Tries to parse a given date string without a known format. It will not parse two digit years and will assume the month always comes before the day in a date. Will leave off any time offset values present.

Example

naive_datetime.parse_any("2024.06.21 01:32 PM -04:00")
// -> Ok(naive_datetime.literal("2024-06-21T13:32:00"))

naive_datetime.parse_any("2024.06.21")
// -> Error(tempo.ParseMissingTime)

set_offset

</>

pub fn set_offset(
  datetime: NaiveDateTime,
  offset: Offset,
) -> DateTime

Sets a naive datetime’s offset to the provided offset, leaving the date and time unchanged while returning a datetime value.

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.set_offset(offset.literal("+10:00"))
// -> datetime.literal("2024-06-21T23:17:00+10:00")

set_utc

</>

pub fn set_utc(datetime: NaiveDateTime) -> DateTime

Sets a naive datetime’s offset to UTC, leaving the date and time unchanged while returning a datetime value. Alias for set_offset(naive_datetime, offset.utc).

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.set_utc
// -> datetime.literal("2024-06-21T23:17:00Z")

subtract

</>

pub fn subtract(
  datetime: NaiveDateTime,
  duration duration_to_subtract: Duration,
) -> NaiveDateTime

Subtracts a duration from a naive datetime.

Examples

naive_datetime.literal("2024-06-12T23:17:00")
|> naive_datetime.subtract(duration.days(3))
// -> naive_datetime.literal("2024-06-09T23:17:00")

time_left_in_day

</>

pub fn time_left_in_day(naive_datetime: NaiveDateTime) -> Time

Gets the time left in the day.

Does not account for leap seconds like the rest of the package.

Examples

naive_datetime.literal("2015-06-30T23:59:03")
|> naive_datetime |> tempo.naive_datetime_get_time_left_in_day
// -> time.literal("00:00:57")

naive_datetime.literal("2024-06-18T08:05:20")
|> naive_datetime |> tempo.naive_datetime_get_time_left_in_day
// -> time.literal("15:54:40")

to_micro_precision

</>

pub fn to_micro_precision(
  naive_datetime: NaiveDateTime,
) -> NaiveDateTime

Sets a naive datetime’s time value to a microsecond precision. Drops any nanoseconds from the underlying time value.

Example

naive_datetime.literal("2024-06-13T13:42:11.195423534")
|> naive_datetime.to_micro_precision
|> naive_datetime.to_string
// -> "2024-06-13T13:42:11.195423"

to_milli_precision

</>

pub fn to_milli_precision(
  naive_datetime: NaiveDateTime,
) -> NaiveDateTime

Sets a naive datetime’s time value to a millisecond precision. Drops any microseconds from the underlying time value.

Example

naive_datetime.literal("2024-06-13T13:42:11.195423")
|> naive_datetime.to_milli_precision
|> naive_datetime.to_string
// -> "2024-06-13T13:42:11.195"

to_nano_precision

</>

pub fn to_nano_precision(
  naive_datetime: NaiveDateTime,
) -> NaiveDateTime

Sets a naive datetime’s time value to a nanosecond precision. Leaves the underlying time value unchanged.

Example

naive_datetime.literal("2024-06-13T13:42:11.195")
|> naive_datetime.to_nano_precision
|> naive_datetime.to_string
// -> "2024-06-13T13:42:11.195000000"

to_second_precision

</>

pub fn to_second_precision(
  naive_datetime: NaiveDateTime,
) -> NaiveDateTime

Sets a naive datetime’s time value to a second precision. Drops any milliseconds from the underlying time value.

Example

naive_datetime.literal("2024-06-13T13:42:11.195423")
|> naive_datetime.to_second_precision
|> naive_datetime.to_string
// -> "2024-06-13T13:42:11"

to_string

</>

pub fn to_string(datetime: NaiveDateTime) -> String

Returns a string representation of a naive datetime value in the ISO 8601 format

Examples

naive_datetime.literal("2024-06-21T23:17:00")
|> naive_datetime.to_string
// -> "2024-06-21T23:17:00"

to_tuple

</>

pub fn to_tuple(
  naive_datetime: NaiveDateTime,
) -> #(#(Int, Int, Int), #(Int, Int, Int))

Returns a tuple of the date and time values in the format used in Erlang.

Example

naive_datetime.literal("2024-06-21T23:17:07")
|> naive_datetime.to_tuple
// -> #(#(2024, 6, 21), #(23, 17, 7))