Julia Dates and Times

Julia provides the following three functions to handle dates and times through the Dates module:

• Date: Represents a date, precise to the day, showing only the date.
• DateTime: Represents a date and time, precise to the millisecond.
• Time: Represents a specific moment within a 24-hour day, precise to the nanosecond.

Before using these functions, we need to import the Dates module:

import Dates

Date and DateTime types can be parsed using integers or Period types.

Period is based on date values, representing years, months, days, etc:

Period
Year
Quarter
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

Both Date and DateTime are subtypes of the abstract type TimeType.

The diagram below shows the relationship between date types; click the image to enlarge:

Examples

julia> import Dates

julia> rightnow = Dates.Time(Dates.now()) # Time
08:41:15.917

julia> theday = Dates.Date(2022,5,6) # Date
2022-05-06

julia> today_date = Dates.today() 
2022-05-11

julia> Dates.now(Dates.UTC)
2022-05-11T00:44:20.136

# Formatting time
julia> Dates.DateTime("20220429 120000", "yyyymmdd HHMMSS")
2022-04-29T12:00:00

julia> Dates.DateTime("19/04/2022 17:42", "dd/mm/yyyy HH:MM")
2022-04-19T17:42:00

The table below provides date format codes, which can be used to format our dates:

Examples

julia> Dates.Date("Sun, 27 Sep 2022", "e, d u y")
2022-09-27

julia> Dates.DateTime("Sun, 27 Sep 2022 10:25:10", "e, d u y H:M:S")
2022-09-27T10:25:10

From the above examples, we have created some date and time objects. Next, we can use these objects to retrieve data (including year, month, day, minute, second, hour, etc.):

Examples

julia> theday = Dates.Date(2022,5,6) # Create a date object
2022-05-06

# Retrieve data from theday
julia> Dates.year(theday)
2022

julia> Dates.month(theday)
5

# Retrieve data from the current time
julia> rightnow = Dates.now()
2022-05-11T08:51:45.342

julia> Dates.minute(rightnow)
51

julia> Dates.hour(rightnow)
8

julia> Dates.second(rightnow)
45

# Retrieve the month and day of the week
julia> Dates.dayofweek(theday)
5

julia> Dates.dayname(theday)
"Friday"

julia> Dates.yearmonthday(theday)
(2022, 5, 6)

julia> Dates.dayofweekofmonth(theday)
1

Date Arithmetic

We can perform arithmetic operations on date objects.

For example, we can calculate the difference in days between two dates:

Examples

julia> day1 = Dates.Date(2022,1,17)
2022-01-17

julia> day2 = Dates.Date(2022,3,23)
2022-03-23

julia> day2 - day1
65 days

# Using different time units
julia> Dates.canonicalize(Dates.CompoundPeriod(day2 - day1))
9 weeks, 2 days

We can also add dates, for example, to calculate the date 20 years and 6 months from now:

Example

julia> rightnow = Dates.now()
2022-05-11T09:01:07.946

julia> rightnow + Dates.Year(20) + Dates.Month(6)
2042-11-11T09:01:07.946

# Date 6 days from now
julia> rightnow + Dates.Day(6)
2022-05-17T09:01:07.946

Date Ranges

Julia can create date ranges using iterable range objects. In the example below, we will create an iterator that generates the first day of each month.

Example

date_range = Dates.Date(2011,1,1):Dates.Month(1):Dates.Date(2022,1,1)
Dates.Date("2011-01-01"):Dates.Month(1):Dates.Date("2022-01-01")

Within the range object, we can filter out which dates are weekdays. We need to create an anonymous function for filter() that checks if a given date is a weekday:

Example

julia> weekdaysfromrange = filter(dy -> Dates.dayname(dy) != "Saturday" && Dates.dayname(dy) != "Sunday" , date_range)
94-element Vector{Dates.Date}:
 2011-02-01
 2011-03-01
 2011-04-01
 2011-06-01
 2011-07-01
 2011-08-01
 2011-09-01
 2011-11-01
 2011-12-01
 2012-02-01
 ⋮
 2021-02-01
 2021-03-01
 2021-04-01
 2021-06-01
 2021-07-01
 2021-09-01
 2021-10-01
 2021-11-01
 2021-12-01

Rounding Dates and Times

We commonly use round(), floor(), and ceil() functions to round parameters up or down. Similarly, these functions can be used to round dates to adjust them forward or backward in time.

Example

julia> Dates.now()
2022-05-11T09:17:49.824

julia> Dates.format(round(Dates.DateTime(Dates.now()), Dates.Minute(15)), Dates.RFC1123Format)
"Wed, 11 May 2022 09:15:00"

The ceil() function adjusts the date/time forward, as shown below:

Example

julia> theday = Dates.Date(2022,5,6)
2022-05-06

# Next month
julia> ceil(theday, Dates.Month)
2022-06-01

# Next year
julia> ceil(theday, Dates.Year)
2023-01-01

# Next week
julia> ceil(theday, Dates.Week)
2022-05-09

Repeating Dates

We can find repeating dates within a range, such as every Sunday:

Example

# Create a date range
julia> date_range = Dates.Date(2011,1,1):Dates.Month(1):Dates.Date(2022,1,1)
Dates.Date("2011-01-01"):Dates.Month(1):Dates.Date("2022-01-01")
# Filter out every Sunday using the filter() function
julia> filter(d -> Dates.dayname(d) == "Sunday", date_range)
20-element Vector{Dates.Date}:
 2011-05-01
 2012-01-01
 2012-04-01
 2012-07-01
 2013-09-01
 2013-12-01
 2014-06-01
 2015-02-01
 2015-03-01
 2015-11-01
 2016-05-01
 2017-01-01
 2017-10-01
 2018-04-01
 2018-07-01

2019-09-01 2019-12-01 2020-03-01 2020-11-01 2021-08-01

UNIX time, also known as POSIX time, is the time format used by UNIX or UNIX-like systems: the total number of seconds since 00:00:00 UTC on January 1, 1970, not including leap seconds.

The time() function returns the Unix time value:

Example

julia> time()
1.652232489777e9

The unix2datetime() function converts Unix time to a date/time object:

Example

julia> Dates.unix2datetime(time())
2022-05-11T01:28:23.493

Current Moment

DateTimes are measured in milliseconds, and we can use the Dates.value function to get the time in milliseconds:

Example

julia> moment = Dates.now()
2022-05-11T09:31:31.037

julia> Dates.value(moment)
63787944691037

julia> moment.instant
Dates.UTInstant{Millisecond}(Millisecond(63787944691037))

Time and Monitoring

Julia provides the @elapsed macro, which returns the time in seconds required to execute an expression.

Calculate the execution time of the following code:

Example

julia> function foo(n)
           for i in 1:n
               x = sin(rand())
           end
       end
foo (generic function with 1 method)

julia> @elapsed foo(100000000)
1.360567967

julia> @time foo(100000000)
1.363258 seconds

More Examples

Example

julia> DateTime(2013)
2013-01-01T00:00:00

julia> DateTime(2013,7)
2013-07-01T00:00:00

julia> DateTime(2013,7,1)
2013-07-01T00:00:00

julia> DateTime(2013,7,1,12)
2013-07-01T12:00:00

julia> DateTime(2013,7,1,12,30)
2013-07-01T12:30:00

julia> DateTime(2013,7,1,12,30,59)
2013-07-01T12:30:59

julia> DateTime(2013,7,1,12,30,59,1)
2013-07-01T12:30:59.001

julia> Date(2013)
2013-01-01

julia> Date(2013,7)
2013-07-01

julia> Date(2013,7,1)
2013-07-01

julia> Date(Dates.Year(2013),Dates.Month(7),Dates.Day(1))
2013-07-01

julia> Date(Dates.Month(7),Dates.Year(2013))
2013-07-01