Dates and Time

Dates and Time Types

Period

Year

Month

Week

Day

Hour

Minute

Second

Millisecond

Period types represent discrete, human representations of time.

CompoundPeriod

A CompoundPeriod is useful for expressing time periods that are not a fixed multiple of smaller periods. For example, “a year and a day” is not a fixed number of days, but can be expressed using a CompoundPeriod. In fact, a CompoundPeriod is automatically generated by addition of different period types, e.g. Year(1) + Day(1) produces a CompoundPeriod result.

Instant

Instant types represent integer-based, machine representations of time as continuous timelines starting from an epoch.

UTInstant{T}

The UTInstant represents a machine timeline based on UT time (1 day = one revolution of the earth). The T is a Period parameter that indicates the resolution or precision of the instant.

TimeType

TimeType types wrap Instant machine instances to provide human representations of the machine instant. Both DateTime and Date are subtypes of TimeType.

DateTime

DateTime wraps a UTInstant{Millisecond} and interprets it according to the proleptic Gregorian calendar.

Date

Date wraps a UTInstant{Day} and interprets it according to the proleptic Gregorian calendar.

Dates Functions

All Dates functions are defined in the Dates module; note that only the Date, DateTime, and now functions are exported; to use all other Dates functions, you’ll need to prefix each function call with an explicit Dates., e.g. Dates.dayofweek(dt). Alternatively, you can write using Base.Dates to bring all exported functions into Main to be used without the Dates. prefix.

DateTime(y[, m, d, h, mi, s, ms]) → DateTime

Construct a DateTime type by parts. Arguments must be convertible to Int64.

DateTime(periods::Period...) → DateTime

Construct a DateTime type by Period type parts. Arguments may be in any order. DateTime parts not provided will default to the value of Dates.default(period).

DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), negate=false, limit=10000) → DateTime

Create a DateTime through the adjuster API. The starting point will be constructed from the provided y, m, d... arguments, and will be adjusted until f::Function returns true. The step size in adjusting can be provided manually through the step keyword. If negate=true, then the adjusting will stop when f::Function returns false instead of true. limit provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case that f::Function is never satisfied).

DateTime(dt::Date) → DateTime

Converts a Date to a DateTime. The hour, minute, second, and millisecond parts of the new DateTime are assumed to be zero.

DateTime(dt::AbstractString, format::AbstractString; locale="english") → DateTime

Construct a DateTime by parsing the dt date string following the pattern given in the format string. The following character codes can be used to construct the format string:

Code	Matches	Comment
y	1996, 96	Returns year of 1996, 0096
Y	1996, 96	Returns year of 1996, 0096. Equivalent to y
m	1, 01	Matches 1 or 2-digit months
u	Jan	Matches abbreviated months according to the locale keyword
U	January	Matches full month names according to the locale keyword
d	1, 01	Matches 1 or 2-digit days
H	00	Matches hours
M	00	Matches minutes
S	00	Matches seconds
s	.500	Matches milliseconds
e	Mon, Tues	Matches abbreviated days of the week
E	Monday	Matches full name days of the week
yyyymmdd	19960101	Matches fixed-width year, month, and day

Characters not listed above are normally treated as delimiters between date and time slots. For example a dt string of “1996-01-15T00:00:00.0” would have a format string like “y-m-dTH:M:S.s”. If you need to use a code character as a delimiter you can escape it using backslash. The date “1995y01m” would have the format “y\ym\m”.

format(dt::TimeType, format::AbstractString; locale="english") → AbstractString

Construct a string by using a TimeType object and applying the provided format. The following character codes can be used to construct the format string:

Code	Examples	Comment
y	6	Numeric year with a fixed width
Y	1996	Numeric year with a minimum width
m	1, 12	Numeric month with a minimum width
u	Jan	Month name shortened to 3-chars according to the locale
U	January	Full month name according to the locale keyword
d	1, 31	Day of the month with a minimum width
H	0, 23	Hour (24-hour clock) with a minimum width
M	0, 59	Minute with a minimum width
S	0, 59	Second with a minimum width
s	000, 500	Millisecond with a minimum width of 3
e	Mon, Tue	Abbreviated days of the week
E	Monday	Full day of week name

The number of sequential code characters indicate the width of the code. A format of yyyy-mm specifies that the code y should have a width of four while m a width of two. Codes that yield numeric digits have an associated mode: fixed-width or minimum-width. The fixed-width mode left-pads the value with zeros when it is shorter than the specified width and truncates the value when longer. Minimum-width mode works the same as fixed-width except that it does not truncate values longer than the width.

When creating a format you can use any non-code characters as a separator. For example to generate the string “1996-01-15T00:00:00” you could use format: “yyyy-mm-ddTHH:MM:SS”. Note that if you need to use a code character as a literal you can use the escape character backslash. The string “1996y01m” can be produced with the format “yyyy\ymm\m”.

DateFormat(format::AbstractString, locale::AbstractString="english") → DateFormat

Construct a date formatting object that can be used for parsing date strings or formatting a date object as a string. For details on the syntax for format see parsing and formatting.

DateTime(dt::AbstractString, df::DateFormat) → DateTime

Construct a DateTime by parsing the dt date string following the pattern given in the Dates.DateFormat() object. Similar to DateTime(::AbstractString, ::AbstractString) but more efficient when repeatedly parsing similarly formatted date strings with a pre-created DateFormat object.

Date(y[, m, d]) → Date

Construct a Date type by parts. Arguments must be convertible to Int64.

Date(period::Period...) → Date

Construct a Date type by Period type parts. Arguments may be in any order. Date parts not provided will default to the value of Dates.default(period).

Date(f::Function, y[, m, d]; step=Day(1), negate=false, limit=10000) → Date

Create a Date through the adjuster API. The starting point will be constructed from the provided y, m, d arguments, and will be adjusted until f::Function returns true. The step size in adjusting can be provided manually through the step keyword. If negate=true, then the adjusting will stop when f::Function returns false instead of true. limit provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given that f::Function is never satisfied).

Date(dt::DateTime) → Date

Converts a DateTime to a Date. The hour, minute, second, and millisecond parts of the DateTime are truncated, so only the year, month and day parts are used in construction.

Date(dt::AbstractString, format::AbstractString; locale="english") → Date

Construct a Date object by parsing a dt date string following the pattern given in the format string. Follows the same conventions as DateTime(::AbstractString, ::AbstractString).

Date(dt::AbstractString, df::DateFormat) → Date

Parse a date from a date string dt using a DateFormat object df.

now() → DateTime

Returns a DateTime corresponding to the user’s system time including the system timezone locale.

now(::Type{UTC}) → DateTime

Returns a DateTime corresponding to the user’s system time as UTC/GMT.

eps(::DateTime) → Millisecond

eps(::Date) → Day

Returns Millisecond(1) for DateTime values and Day(1) for Date values.

Accessor Functions

year(dt::TimeType) → Int64

The year of a Date or DateTime as an Int64.

month(dt::TimeType) → Int64

The month of a Date or DateTime as an Int64.

week(dt::TimeType) → Int64

Return the ISO week date of a Date or DateTime as an Int64. Note that the first week of a year is the week that contains the first Thursday of the year which can result in dates prior to January 4th being in the last week of the previous year. For example week(Date(2005,1,1)) is the 53rd week of 2004.

day(dt::TimeType) → Int64

The day of month of a Date or DateTime as an Int64.

hour(dt::DateTime) → Int64

The hour of day of a DateTime as an Int64.

minute(dt::DateTime) → Int64

The minute of a DateTime as an Int64.

second(dt::DateTime) → Int64

The second of a DateTime as an Int64.

millisecond(dt::DateTime) → Int64

The millisecond of a DateTime as an Int64.

Year(dt::TimeType) → Year

The year part of a Date or DateTime as a Year.

Month(dt::TimeType) → Month

The month part of a Date or DateTime as a Month.

Week(dt::TimeType) → Week

The week part of a Date or DateTime as a Week. For details see week().

Day(dt::TimeType) → Day

The day part of a Date or DateTime as a Day.

Hour(dt::DateTime) → Hour

The hour part of a DateTime as a Hour.

Minute(dt::DateTime) → Minute

The minute part of a DateTime as a Minute.

Second(dt::DateTime) → Second

The second part of a DateTime as a Second.

Millisecond(dt::DateTime) → Millisecond

The millisecond part of a DateTime as a Millisecond.

yearmonth(dt::TimeType) → (Int64, Int64)

Simultaneously return the year and month parts of a Date or DateTime.

monthday(dt::TimeType) → (Int64, Int64)

Simultaneously return the month and day parts of a Date or DateTime.

yearmonthday(dt::TimeType) → (Int64, Int64, Int64)

Simultaneously return the year, month and day parts of a Date or DateTime.

Query Functions

dayname(dt::TimeType; locale="english") → AbstractString

Return the full day name corresponding to the day of the week of the Date or DateTime in the given locale.

dayabbr(dt::TimeType; locale="english") → AbstractString

Return the abbreviated name corresponding to the day of the week of the Date or DateTime in the given locale.

dayofweek(dt::TimeType) → Int64

Returns the day of the week as an Int64 with 1 = Monday, 2 = Tuesday, etc..

dayofmonth(dt::TimeType) → Int64

The day of month of a Date or DateTime as an Int64.

dayofweekofmonth(dt::TimeType) → Int

For the day of week of dt, returns which number it is in dt‘s month. So if the day of the week of dt is Monday, then 1 = First Monday of the month, 2 = Second Monday of the month, etc. In the range 1:5.

daysofweekinmonth(dt::TimeType) → Int

For the day of week of dt, returns the total number of that day of the week in dt‘s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by including dayofweekofmonth(dt) == daysofweekinmonth(dt) in the adjuster function.

monthname(dt::TimeType; locale="english") → AbstractString

Return the full name of the month of the Date or DateTime in the given locale.

monthabbr(dt::TimeType; locale="english") → AbstractString

Return the abbreviated month name of the Date or DateTime in the given locale.

daysinmonth(dt::TimeType) → Int

Returns the number of days in the month of dt. Value will be 28, 29, 30, or 31.

isleapyear(dt::TimeType) → Bool

Returns true if the year of dt is a leap year.

dayofyear(dt::TimeType) → Int

Returns the day of the year for dt with January 1st being day 1.

daysinyear(dt::TimeType) → Int

Returns 366 if the year of dt is a leap year, otherwise returns 365.

quarterofyear(dt::TimeType) → Int

Returns the quarter that dt resides in. Range of value is 1:4.

dayofquarter(dt::TimeType) → Int

Returns the day of the current quarter of dt. Range of value is 1:92.

Adjuster Functions

trunc(dt::TimeType, ::Type{Period}) → TimeType

Truncates the value of dt according to the provided Period type. E.g. if dt is 1996-01-01T12:30:00, then trunc(dt,Day) == 1996-01-01T00:00:00.

firstdayofweek(dt::TimeType) → TimeType

Adjusts dt to the Monday of its week.

lastdayofweek(dt::TimeType) → TimeType

Adjusts dt to the Sunday of its week.

firstdayofmonth(dt::TimeType) → TimeType

Adjusts dt to the first day of its month.

lastdayofmonth(dt::TimeType) → TimeType

Adjusts dt to the last day of its month.

firstdayofyear(dt::TimeType) → TimeType

Adjusts dt to the first day of its year.

lastdayofyear(dt::TimeType) → TimeType

Adjusts dt to the last day of its year.

firstdayofquarter(dt::TimeType) → TimeType

Adjusts dt to the first day of its quarter.

lastdayofquarter(dt::TimeType) → TimeType

Adjusts dt to the last day of its quarter.

tonext(dt::TimeType, dow::Int;same::Bool=false) → TimeType

Adjusts dt to the next day of week corresponding to dow with 1 = Monday, 2 = Tuesday, etc. Setting same=true allows the current dt to be considered as the next dow, allowing for no adjustment to occur.

toprev(dt::TimeType, dow::Int;same::Bool=false) → TimeType

Adjusts dt to the previous day of week corresponding to dow with 1 = Monday, 2 = Tuesday, etc. Setting same=true allows the current dt to be considered as the previous dow, allowing for no adjustment to occur.

tofirst(dt::TimeType, dow::Int;of=Month) → TimeType

Adjusts dt to the first dow of its month. Alternatively, of=Year will adjust to the first dow of the year.

tolast(dt::TimeType, dow::Int;of=Month) → TimeType

Adjusts dt to the last dow of its month. Alternatively, of=Year will adjust to the last dow of the year.

tonext(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) → TimeType

Adjusts dt by iterating at most limit iterations by step increments until func returns true. func must take a single TimeType argument and return a Bool. same allows dt to be considered in satisfying func. negate will make the adjustment process terminate when func returns false instead of true.

toprev(func::Function, dt::TimeType;step=Day(-1), negate=false, limit=10000, same=false) → TimeType

Adjusts dt by iterating at most limit iterations by step increments until func returns true. func must take a single TimeType argument and return a Bool. same allows dt to be considered in satisfying func. negate will make the adjustment process terminate when func returns false instead of true.

recur{T<:timetype dr::steprange limit="10000)" vector>

func takes a single TimeType argument and returns a Bool indicating whether the input should be “included” in the final set. recur applies func over each element in the range of dr, including those elements for which func returns true in the resulting Array, unless negate=true, then only elements where func returns false are included.

Periods

Year(v)

Month(v)

Week(v)

Day(v)

Hour(v)

Minute(v)

Second(v)

Millisecond(v)

Construct a Period type with the given v value. Input must be losslessly convertible to an Int64.

CompoundPeriod(periods) → CompoundPeriod

Construct a CompoundPeriod from a Vector of Periods. The constructor will automatically simplify the periods into a canonical form according to the following rules:

• All Periods of the same type will be added together
• Any Period large enough be partially representable by a coarser Period will be broken into multiple Periods (eg. Hour(30) becomes Day(1) + Hour(6))
• Periods with opposite signs will be combined when possible (eg. Hour(1) - Day(1) becomes -Hour(23))

Due to the canonicalization, CompoundPeriod is also useful for converting time periods into more human-comprehensible forms.

Examples

julia> Dates.CompoundPeriod([Dates.Hour(12), Dates.Hour(13)])
1 day, 1 hour

julia> Dates.CompoundPeriod([Dates.Hour(-1), Dates.Minute(1)])
-59 minutes

julia> Dates.CompoundPeriod([Dates.Month(1), Dates.Week(-2)])
1 month, -2 weeks

julia> Dates.CompoundPeriod(Dates.Minute(50000)))
4 weeks, 6 days, 17 hours, 20 minutes

default(p::Period) → Period

Returns a sensible “default” value for the input Period by returning one(p) for Year, Month, and Day, and zero(p) for Hour, Minute, Second, and Millisecond.

Rounding Functions

Date and DateTime values can be rounded to a specified resolution (e.g., 1 month or 15 minutes) with floor, ceil, or round.

floor(dt::TimeType, p::Period) → TimeType

Returns the nearest Date or DateTime less than or equal to dt at resolution p.

For convenience, p may be a type instead of a value: floor(dt, Dates.Hour) is a shortcut for floor(dt, Dates.Hour(1)).

julia> floor(Date(1985, 8, 16), Dates.Month)
1985-08-01

julia> floor(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
2013-02-13T00:30:00

julia> floor(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day)
2016-08-06T00:00:00

ceil(dt::TimeType, p::Period) → TimeType

Returns the nearest Date or DateTime greater than or equal to dt at resolution p.

For convenience, p may be a type instead of a value: ceil(dt, Dates.Hour) is a shortcut for ceil(dt, Dates.Hour(1)).

julia> ceil(Date(1985, 8, 16), Dates.Month)
1985-09-01

julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
2013-02-13T00:45:00

julia> ceil(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day)
2016-08-07T00:00:00

round(dt::TimeType, p::Period[, r::RoundingMode]) → TimeType

Returns the Date or DateTime nearest to dt at resolution p. By default (RoundNearestTiesUp), ties (e.g., rounding 9:30 to the nearest hour) will be rounded up.

For convenience, p may be a type instead of a value: round(dt, Dates.Hour) is a shortcut for round(dt, Dates.Hour(1)).

julia> round(Date(1985, 8, 16), Dates.Month)
1985-08-01

julia> round(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
2013-02-13T00:30:00

julia> round(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day)
2016-08-07T00:00:00

Valid rounding modes for round(::TimeType, ::Period, ::RoundingMode) are RoundNearestTiesUp (default), RoundDown (floor), and RoundUp (ceil).

The following functions are not exported:

floorceil(dt::TimeType, p::Period) → (TimeType, TimeType)

Simultaneously return the floor and ceil of a Date or DateTime at resolution p. More efficient than calling both floor and ceil individually.

epochdays2date(days) → Date

Takes the number of days since the rounding epoch (0000-01-01T00:00:00) and returns the corresponding Date.

epochms2datetime(milliseconds) → DateTime

Takes the number of milliseconds since the rounding epoch (0000-01-01T00:00:00) and returns the corresponding DateTime.

date2epochdays(dt::Date) → Int64

Takes the given Date and returns the number of days since the rounding epoch (0000-01-01T00:00:00) as an Int64.

datetime2epochms(dt::DateTime) → Int64

Takes the given DateTime and returns the number of milliseconds since the rounding epoch (0000-01-01T00:00:00) as an Int64.

Conversion Functions

today() → Date

Returns the date portion of now().

unix2datetime(x) → DateTime

Takes the number of seconds since unix epoch 1970-01-01T00:00:00 and converts to the corresponding DateTime.

datetime2unix(dt::DateTime) → Float64

Takes the given DateTime and returns the number of seconds since the unix epoch 1970-01-01T00:00:00 as a Float64.

julian2datetime(julian_days) → DateTime

Takes the number of Julian calendar days since epoch -4713-11-24T12:00:00 and returns the corresponding DateTime.

datetime2julian(dt::DateTime) → Float64

Takes the given DateTime and returns the number of Julian calendar days since the julian epoch -4713-11-24T12:00:00 as a Float64.

rata2datetime(days) → DateTime

Takes the number of Rata Die days since epoch 0000-12-31T00:00:00 and returns the corresponding DateTime.

datetime2rata(dt::TimeType) → Int64

Returns the number of Rata Die days since epoch from the given Date or DateTime.

Constants

Days of the Week:

Variable	Abbr.	Value (Int)
Monday	Mon	1
Tuesday	Tue	2
Wednesday	Wed	3
Thursday	Thu	4
Friday	Fri	5
Saturday	Sat	6
Sunday	Sun	7

Months of the Year:

Variable	Abbr.	Value (Int)
January	Jan	1
February	Feb	2
March	Mar	3
April	Apr	4
May	May	5
June	Jun	6
July	Jul	7
August	Aug	8
September	Sep	9
October	Oct	10
November	Nov	11
December	Dec	12