Datetime

(Fn [(Ref Datetime a), (Ref Datetime b)] Bool)

                        (< a b)
                    

is defined as the timezone-unaware comparison of a and b.

(Fn [(Ref Datetime a), (Ref Datetime a)] Bool)

                        (= a b)
                    

is defined as the equality of all members of a and b, even the optional ones.

(Fn [(Ref Datetime a), (Ref Datetime b)] Bool)

                        (> a b)
                    

is defined as the timezone-unaware comparison of a and b.

(Fn [(Ref Datetime a), Int] Datetime)

                        (add-months dt n)
                    

adds n months to the Datetime dt.

If the resulting month has fewer days than the original day, the day is clamped to the last day of the month. For example, adding 1 month to January 31 yields February 28 (or 29 in a leap year).

n may be negative to subtract months.

(Fn [(Ref Datetime a), Int] Datetime)

                        (add-seconds d n)
                    

adds a number of seconds n to a Datetime.

If n is negative, it will be subtracted instead.

(Fn [(Ref Datetime a), Int] Datetime)

                        (add-years dt n)
                    

adds n years to the Datetime dt.

If the date is February 29 and the resulting year is not a leap year, the day is clamped to February 28.

n may be negative to subtract years.

(Fn [(Ref Datetime a), (Ref Datetime b)] Bool)

                        (after-instant? a b)
                    

checks whether a names a later instant than b, comparing them as UTC instants (see equal-instant?). This is the timezone-aware counterpart to >.

(Fn [(Ref Datetime a), (Ref Datetime b)] Bool)

                        (before-instant? a b)
                    

checks whether a names an earlier instant than b, comparing them as UTC instants (see equal-instant?). This is the timezone-aware counterpart to <.

(Fn [(Ref Datetime a)] Datetime)

copies a Datetime. This will also copy the timezone contained in it.

(Fn [Int, Int, Int] Datetime)

                        (date y m d)
                    

create a Datetime from a year y, month m, and day d.

(Fn [(Ref Datetime a)] (Ref Int a))

gets the day property of a Datetime.

(Fn [Datetime] ())

deletes a Datetime. Should usually not be called manually.

(Fn [(Ref Datetime a), (Ref Datetime b)] Int)

                        (diff a b)
                    

returns the signed difference in seconds between a and b.

The result is positive when a is later than b, and negative when a is earlier. This is a timezone-unaware comparison, similar to > and <.

(Fn [(Ref Datetime a), (Ref Datetime b)] Bool)

                        (equal-instant? a b)
                    

checks whether a and b name the same instant.

Unlike =, which compares the wall-clock fields directly and is timezone- unaware, this compares the two Datetimes as UTC instants (via to-unix-timestamp), so e.g. 14:00 EST and 19:00 UTC are equal. The comparison is to the second, with nanoseconds as the tiebreaker.

(Fn [(Ref String a), (Ref Datetime b)] String)

                        (format s dt)
                    

The interface implementation of format for Datetime values.

It mimics the C interface.

(Fn [a] Datetime)

                        (from-ordinal ord)
                    

converts a Gregorian ordinal ord to a Datetime.

(Fn [Int] Datetime)

                        (from-unix-timestamp ts)
                    

returns the Datetime equivalent to the UNIX timestamp ts, i.e. the number of seconds elapsed since the 1st of January, 1970.

(Fn [(Ref Datetime a)] (Ref (Maybe Int) a))

gets the hours property of a Datetime.

(Fn [(Ref Datetime a), (Ref Timezone b)] Datetime)

                        (in-timezone dt target)
                    

returns the Datetime dt expressed in the timezone target, preserving the instant: the wall-clock fields are shifted so they name the same moment measured in target, and the timezone is set to target.

(let [dt (Datetime.init 2024 1 1 (Maybe.Just 22) (Maybe.Just 0) (Maybe.Just 0)
                        (Maybe.Nothing) (Maybe.Just (Timezone.init @"EST" -18000l false)))]
  (Datetime.isotime &(Datetime.in-timezone &dt &Timezone.utc))) ; => "03:00:00"

(Fn [Int, Int, Int, (Maybe Int), (Maybe Int), (Maybe Int), (Maybe Int), (Maybe Timezone)] Datetime)

creates a Datetime.

(Fn [(Ref Datetime a)] (Array Int))

                        (isocalendar dt)
                    

returns the ISO 8601 week date of the Datetime dt as a three-element array [iso-year iso-week iso-weekday]. iso-week runs from 1 to 53 and iso-weekday from 1 (Monday) to 7 (Sunday). The ISO year can differ from the calendar year near a year boundary: 2023-01-01 is week 52 of 2022, and 2024-12-30 is week 01 of 2025.

(Fn [(Ref Datetime a)] String)

                        (isoformat dt)
                    

returns the ISO format for the Datetime dt.

The ISO format is of the form YYYY-MM-DD. The time value is not represented.

(Fn [(Ref Datetime a)] String)

                        (isotime dt)
                    

returns the ISO time format for the Datetime dt.

The ISO format is of the form HH:MM:SS. The date value is not represented.

(Fn [(Ref Datetime a)] Int)

                        (isoweekday dt)
                    

returns the ISO representation of weekday of the Datetime dt as a number in the range of 1 to 7.

(Fn [(Ref Datetime a)] Bool)

                        (leap? dt)
                    

checks whether the Datetime dt is a leap year.

(Fn [(Ref Datetime a)] (Ref (Maybe Int) a))

gets the minutes property of a Datetime.

(Fn [(Ref Datetime a)] (Ref Int a))

gets the month property of a Datetime.

(Fn [(Ref Datetime a)] String)

                        (month-short-string dt)
                    

returns the abbreviated name of the month of the Datetime dt.

(Fn [(Ref Datetime a)] String)

                        (month-string dt)
                    

returns the name of the month of the Datetime dt.

(Fn [(Ref Datetime a)] (Ref (Maybe Int) a))

gets the nanoseconds property of a Datetime.

(Fn [] Datetime)

                        (now)
                    

returns the Datetime representing the current time.

All of the time information is obtained from the operating system directly.

(Fn [(Ref Datetime a)] String)

converts a Datetime to a string.

(Fn [(Ref Datetime a)] (Ref (Maybe Int) a))

gets the seconds property of a Datetime.

(Fn [Datetime, Int] Datetime)

sets the day property of a Datetime.

(Fn [(Ref Datetime a), Int] ())

sets the day property of a Datetime in place.

(Fn [Datetime, (Maybe Int)] Datetime)

sets the hours property of a Datetime.

(Fn [(Ref Datetime a), (Maybe Int)] ())

sets the hours property of a Datetime in place.

(Fn [Datetime, (Maybe Int)] Datetime)

sets the minutes property of a Datetime.

(Fn [(Ref Datetime a), (Maybe Int)] ())

sets the minutes property of a Datetime in place.

(Fn [Datetime, Int] Datetime)

sets the month property of a Datetime.

(Fn [(Ref Datetime a), Int] ())

sets the month property of a Datetime in place.

(Fn [Datetime, (Maybe Int)] Datetime)

sets the nanoseconds property of a Datetime.

(Fn [(Ref Datetime a), (Maybe Int)] ())

sets the nanoseconds property of a Datetime in place.

(Fn [Datetime, (Maybe Int)] Datetime)

sets the seconds property of a Datetime.

(Fn [(Ref Datetime a), (Maybe Int)] ())

sets the seconds property of a Datetime in place.

(Fn [Datetime, (Maybe Timezone)] Datetime)

sets the tz property of a Datetime.

(Fn [(Ref Datetime a), (Maybe Timezone)] ())

sets the tz property of a Datetime in place.

(Fn [Datetime, Int] Datetime)

sets the year property of a Datetime.

(Fn [(Ref Datetime a), Int] ())

sets the year property of a Datetime in place.

(Fn [(Ref Datetime a)] String)

converts a Datetime to a string.

(Fn [a, (Ref String b)] String)

                        (strftime dt s)
                    

formats the Datetime dt according to the string provided in s. The formatting options mimic the C interface.

You can alternatively use the fmt macro or format function, but you’ll only be able to use one of the formatting properties there. Thus this function is provided as a convenience for fine-grained string tweaking.

Example:

&(Datetime.strftime &(Datetime.now) "%Y-%m-%d %I:%M:%S.%n %p %z")

(Fn [(Ref String a), (Ref String b)] (Result Datetime String))

                        (strptime input fmt)
                    

parses a string input according to format string fmt, returning a (Result Datetime String).

The format specifiers mirror those of strftime:

• %Y — 4-digit year
• %y — 2-digit year (00–68 → 2000–2068, 69–99 → 1969–1999)
• %m — 2-digit month (01–12)
• %b — abbreviated month name (Jan, Feb, ...)
• %B — full month name (January, February, ...)
• %d — 2-digit day (01–31)
• %H — 2-digit hour, 24h (00–23)
• %I — 2-digit hour, 12h (01–12)
• %p — AM or PM
• %M — 2-digit minute (00–59)
• %S — 2-digit second (00–59)
• %n — 9-digit nanoseconds
• %z — timezone offset (+HHMM or -HHMM)
• %Z — timezone name (alphabetic characters)
• %a — abbreviated weekday (parsed and discarded)
• %A — full weekday (parsed and discarded)
• %w — weekday number (parsed and discarded)
• %j — day of year (parsed and discarded)
• %U, %W, %V — week number (parsed and discarded)
• %G — ISO week-based year (parsed and discarded)
• %u — ISO weekday, 1–7 (parsed and discarded)
• %c — locale datetime (expands to %a %b %d %H:%M:%S %Y)
• %x — ISO date (expands to %Y-%m-%d)
• %X — ISO time (expands to %H:%M:%S)
• %F — ISO date (expands to %Y-%m-%d)
• %T — 24-hour time (expands to %H:%M:%S)
• %R — 24-hour time without seconds (expands to %H:%M)
• %D — US-style date (expands to %m/%d/%y)
• %r — 12-hour clock time (expands to %I:%M:%S %p)
• %h — abbreviated month name (alias of %b)

Reconstructing a date from the ISO week fields (%G/%V/%u) is not supported; they are consumed but do not set the date.

Example:

(Datetime.strptime "2024-03-15 14:30:00" "%Y-%m-%d %H:%M:%S")

(Fn [(Ref Datetime a)] Int)

                        (to-ordinal dt)
                    

converts a Datetime struct dt to a Gregorian ordinal.

(Fn [(Ref Datetime a)] Int)

                        (to-unix-timestamp dt)
                    

returns the representation of the Datetime dt as a UNIX timestamp, i.e. the number of seconds elapsed since the 1st of January, 1970.

(Fn [(Ref Datetime a)] Datetime)

                        (to-utc dt)
                    

returns the Datetime dt expressed in UTC.

The wall-clock fields are shifted by the timezone offset (delta) so they name the same instant in UTC, and the timezone is set to Timezone.utc. A Datetime that is already UTC — or that has no timezone, which the library treats as UTC (see utc?) — keeps its fields and is simply labelled UTC.

(Fn [(Ref Datetime a)] (Ref (Maybe Timezone) a))

gets the tz property of a Datetime.

(Fn [Datetime, (Ref (Fn [Int] Int a) b)] Datetime)

updates the day property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [(Maybe Int)] (Maybe Int) a) b)] Datetime)

updates the hours property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [(Maybe Int)] (Maybe Int) a) b)] Datetime)

updates the minutes property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [Int] Int a) b)] Datetime)

updates the month property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [(Maybe Int)] (Maybe Int) a) b)] Datetime)

updates the nanoseconds property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [(Maybe Int)] (Maybe Int) a) b)] Datetime)

updates the seconds property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [(Maybe Timezone)] (Maybe Timezone) a) b)] Datetime)

updates the tz property of a Datetime using a function f.

(Fn [Datetime, (Ref (Fn [Int] Int a) b)] Datetime)

updates the year property of a Datetime using a function f.

(Fn [(Ref Datetime a)] Bool)

                        (utc? dt)
                    

checks whether the timezone of the Datetime dt is UTC. The timezone name comparison is case-insensitive. It will also return true if the timezone is not set.

(Fn [(Ref Datetime a)] Int)

                        (weekday dt)
                    

returns the weekday of the Datetime dt as a number in the range of 0 to 6.

(Fn [(Ref Datetime a)] String)

                        (weekday-short-string dt)
                    

returns the abbreviated name of the weekday of the Datetime dt.

(Fn [(Ref Datetime a)] String)

                        (weekday-string dt)
                    

returns the name of the weekday of the Datetime dt.

(Fn [(Ref Datetime a)] (Ref Int a))

gets the year property of a Datetime.

(Fn [(Ref Datetime a)] Int)

                        (yearday dt)
                    

returns the day of the year of the Datetime dt as a number in the range of 1 to 365 or 366, depending on whether it’s a leap year.