Datetime

This module is primarily concerned with date and time. The Datetime type can be converted from and to various other types and formats, and formatted using strftime, which mimics the C formatting API.

Example:

(load "git@github.com:carpentry-org/time.carp@0.1.0")

(defn main []
  (println* &(Datetime.strftime &(Datetime.now) "%Y-%m-%d %I:%M:%S.%n %p %z")))

<

defn

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

                        (< a b)
                    

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

=

defn

(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.

>

defn

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

                        (> a b)
                    

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

add-seconds

defn

(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.

copy

instantiate

(Fn [(Ref Datetime a)] Datetime)

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

date

defn

(Fn [Int, Int, Int] Datetime)

                        (date y m d)
                    

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

day

instantiate

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

gets the day property of a Datetime.

delete

instantiate

(Fn [Datetime] ())

deletes a Datetime. Should usually not be called manually.

format

defn

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

                        (format s dt)
                    

The interface implementation of format for Datetime values.

It mimics the C interface.

from-ordinal

defn

(Fn [a] Datetime)

                        (from-ordinal ord)
                    

converts a Gregorian ordinal ord to a Datetime.

from-unix-timestamp

defn

(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.

hours

instantiate

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

gets the hours property of a Datetime.

init

instantiate

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

creates a Datetime.

isoformat

defn

(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.

isotime

defn

(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.

isoweekday

defn

(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.

leap?

defn

(Fn [(Ref Datetime a)] Bool)

                        (leap? dt)
                    

checks whether the Datetime dt is a leap year.

minutes

instantiate

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

gets the minutes property of a Datetime.

month

instantiate

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

gets the month property of a Datetime.

month-short-string

defn

(Fn [(Ref Datetime a)] String)

                        (month-short-string dt)
                    

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

month-string

defn

(Fn [(Ref Datetime a)] String)

                        (month-string dt)
                    

returns the name of the month of the Datetime dt.

nanoseconds

instantiate

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

gets the nanoseconds property of a Datetime.

now

defn

(Fn [] Datetime)

                        (now)
                    

returns the Datetime representing the current time.

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

prn

instantiate

(Fn [(Ref Datetime a)] String)

converts a Datetime to a string.

seconds

instantiate

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

gets the seconds property of a Datetime.

set-day

instantiate

(Fn [Datetime, Int] Datetime)

sets the day property of a Datetime.

set-day!

instantiate

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

sets the day property of a Datetime in place.

set-hours

instantiate

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

sets the hours property of a Datetime.

set-hours!

instantiate

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

sets the hours property of a Datetime in place.

set-minutes

instantiate

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

sets the minutes property of a Datetime.

set-minutes!

instantiate

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

sets the minutes property of a Datetime in place.

set-month

instantiate

(Fn [Datetime, Int] Datetime)

sets the month property of a Datetime.

set-month!

instantiate

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

sets the month property of a Datetime in place.

set-nanoseconds

instantiate

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

sets the nanoseconds property of a Datetime.

set-nanoseconds!

instantiate

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

sets the nanoseconds property of a Datetime in place.

set-seconds

instantiate

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

sets the seconds property of a Datetime.

set-seconds!

instantiate

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

sets the seconds property of a Datetime in place.

set-tz

instantiate

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

sets the tz property of a Datetime.

set-tz!

instantiate

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

sets the tz property of a Datetime in place.

set-year

instantiate

(Fn [Datetime, Int] Datetime)

sets the year property of a Datetime.

set-year!

instantiate

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

sets the year property of a Datetime in place.

str

instantiate

(Fn [(Ref Datetime a)] String)

converts a Datetime to a string.

strftime

defn

(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")

to-ordinal

defn

(Fn [(Ref Datetime a)] Int)

                        (to-ordinal dt)
                    

converts a Datetime struct dt to a Gregorian ordinal.

to-unix-timestamp

defn

(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.

tz

instantiate

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

gets the tz property of a Datetime.

update-day

instantiate

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

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

update-hours

instantiate

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

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

update-minutes

instantiate

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

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

update-month

instantiate

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

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

update-nanoseconds

instantiate

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

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

update-seconds

instantiate

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

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

update-tz

instantiate

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

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

update-year

instantiate

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

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

utc?

defn

(Fn [(Ref Datetime a)] Bool)

                        (utc? dt)
                    

checks whether the timezone of the Datetime dt is UTC. It will also return true if the timezone is not set.

weekday

defn

(Fn [(Ref Datetime a)] Int)

                        (weekday dt)
                    

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

weekday-short-string

defn

(Fn [(Ref Datetime a)] String)

                        (weekday-short-string dt)
                    

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

weekday-string

defn

(Fn [(Ref Datetime a)] String)

                        (weekday-string dt)
                    

returns the name of the weekday of the Datetime dt.

year

instantiate

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

gets the year property of a Datetime.

yearday

defn

(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.