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 aCompoundPeriod
. In fact, aCompoundPeriod
is automatically generated by addition of different period types, e.g.Year(1) + Day(1)
produces aCompoundPeriod
result.

Instant
¶ Instant
types represent integerbased, 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). TheT
is aPeriod
parameter that indicates the resolution or precision of the instant.

TimeType
¶ TimeType
types wrapInstant
machine instances to provide human representations of the machine instant. BothDateTime
andDate
are subtypes ofTimeType
.

DateTime
¶ DateTime
wraps aUTInstant{Millisecond}
and interprets it according to the proleptic Gregorian calendar.

Date
¶ Date
wraps aUTInstant{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 toInt64
.

DateTime
(periods::Period...) → DateTime Construct a
DateTime
type byPeriod
type parts. Arguments may be in any order. DateTime parts not provided will default to the value ofDates.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 providedy, m, d...
arguments, and will be adjusted untilf::Function
returnstrue
. The step size in adjusting can be provided manually through thestep
keyword. Ifnegate=true
, then the adjusting will stop whenf::Function
returnsfalse
instead oftrue
.limit
provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (in the case thatf::Function
is never satisfied).

DateTime
(dt::Date) → DateTime Converts a
Date
to aDateTime
. The hour, minute, second, and millisecond parts of the newDateTime
are assumed to be zero.

DateTime
(dt::AbstractString, format::AbstractString; locale="english") → DateTime Construct a
DateTime
by parsing thedt
date string following the pattern given in theformat
string. The following character codes can be used to construct theformat
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 2digit months u
Jan Matches abbreviated months according to the locale
keywordU
January Matches full month names according to the locale
keywordd
1, 01 Matches 1 or 2digit 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 fixedwidth year, month, and day Characters not listed above are normally treated as delimiters between date and time slots. For example a
dt
string of “19960115T00:00:00.0” would have aformat
string like “ymdTH: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 providedformat
. The following character codes can be used to construct theformat
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 3chars according to the locale
U
January Full month name according to the locale
keywordd
1, 31 Day of the month with a minimum width H
0, 23 Hour (24hour 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
yyyymm
specifies that the codey
should have a width of four whilem
a width of two. Codes that yield numeric digits have an associated mode: fixedwidth or minimumwidth. The fixedwidth mode leftpads the value with zeros when it is shorter than the specified width and truncates the value when longer. Minimumwidth mode works the same as fixedwidth except that it does not truncate values longer than the width.When creating a
format
you can use any noncode characters as a separator. For example to generate the string “19960115T00:00:00” you could useformat
: “yyyymmddTHH: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 thedt
date string following the pattern given in theDates.DateFormat()
object. Similar toDateTime(::AbstractString, ::AbstractString)
but more efficient when repeatedly parsing similarly formatted date strings with a precreatedDateFormat
object.

Date
(y[, m, d]) → Date Construct a
Date
type by parts. Arguments must be convertible toInt64
.

Date
(period::Period...) → Date Construct a
Date
type byPeriod
type parts. Arguments may be in any order.Date
parts not provided will default to the value ofDates.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 providedy, m, d
arguments, and will be adjusted untilf::Function
returnstrue
. The step size in adjusting can be provided manually through thestep
keyword. Ifnegate=true
, then the adjusting will stop whenf::Function
returnsfalse
instead oftrue
.limit
provides a limit to the max number of iterations the adjustment API will pursue before throwing an error (given thatf::Function
is never satisfied).

Date
(dt::DateTime) → Date Converts a
DateTime
to aDate
. The hour, minute, second, and millisecond parts of theDateTime
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 adt
date string following the pattern given in theformat
string. Follows the same conventions asDateTime(::AbstractString, ::AbstractString)
.

Date
(dt::AbstractString, df::DateFormat) → Date Parse a date from a date string
dt
using aDateFormat
objectdf
.

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)
forDateTime
values andDay(1)
forDate
values.
Accessor Functions¶

year
(dt::TimeType) → Int64¶ The year of a
Date
orDateTime
as anInt64
.

month
(dt::TimeType) → Int64¶ The month of a
Date
orDateTime
as anInt64
.

week
(dt::TimeType) → Int64¶ Return the ISO week date of a
Date
orDateTime
as anInt64
. 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 exampleweek(Date(2005,1,1))
is the 53rd week of 2004.

day
(dt::TimeType) → Int64¶ The day of month of a
Date
orDateTime
as anInt64
.

hour
(dt::DateTime) → Int64¶ The hour of day of a
DateTime
as anInt64
.

minute
(dt::DateTime) → Int64¶ The minute of a
DateTime
as anInt64
.

second
(dt::DateTime) → Int64¶ The second of a
DateTime
as anInt64
.

millisecond
(dt::DateTime) → Int64¶ The millisecond of a
DateTime
as anInt64
.

Year
(dt::TimeType) → Year The year part of a
Date
orDateTime
as aYear
.

Month
(dt::TimeType) → Month The month part of a
Date
orDateTime
as aMonth
.

Week
(dt::TimeType) → Week The week part of a
Date
orDateTime
as aWeek
. For details seeweek()
.

Day
(dt::TimeType) → Day The day part of a
Date
orDateTime
as aDay
.

Hour
(dt::DateTime) → Hour The hour part of a
DateTime
as aHour
.

Minute
(dt::DateTime) → Minute The minute part of a
DateTime
as aMinute
.

Second
(dt::DateTime) → Second The second part of a
DateTime
as aSecond
.

Millisecond
(dt::DateTime) → Millisecond The millisecond part of a
DateTime
as aMillisecond
.

yearmonth
(dt::TimeType) → (Int64, Int64)¶ Simultaneously return the year and month parts of a
Date
orDateTime
.

monthday
(dt::TimeType) → (Int64, Int64)¶ Simultaneously return the month and day parts of a
Date
orDateTime
.

yearmonthday
(dt::TimeType) → (Int64, Int64, Int64)¶ Simultaneously return the year, month and day parts of a
Date
orDateTime
.
Query Functions¶

dayname
(dt::TimeType; locale="english") → AbstractString¶ Return the full day name corresponding to the day of the week of the
Date
orDateTime
in the givenlocale
.

dayabbr
(dt::TimeType; locale="english") → AbstractString¶ Return the abbreviated name corresponding to the day of the week of the
Date
orDateTime
in the givenlocale
.

dayofweek
(dt::TimeType) → Int64¶ Returns the day of the week as an
Int64
with1 = Monday, 2 = Tuesday, etc.
.

dayofmonth
(dt::TimeType) → Int64¶ The day of month of a
Date
orDateTime
as anInt64
.

dayofweekofmonth
(dt::TimeType) → Int¶ For the day of week of
dt
, returns which number it is indt
‘s month. So if the day of the week ofdt
is Monday, then1 = 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 indt
‘s month. Returns 4 or 5. Useful in temporal expressions for specifying the last day of a week in a month by includingdayofweekofmonth(dt) == daysofweekinmonth(dt)
in the adjuster function.

monthname
(dt::TimeType; locale="english") → AbstractString¶ Return the full name of the month of the
Date
orDateTime
in the givenlocale
.

monthabbr
(dt::TimeType; locale="english") → AbstractString¶ Return the abbreviated month name of the
Date
orDateTime
in the givenlocale
.

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 ofdt
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 providedPeriod
type. E.g. ifdt
is19960101T12:30:00
, thentrunc(dt,Day) == 19960101T00: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 todow
with1 = Monday, 2 = Tuesday, etc
. Settingsame=true
allows the currentdt
to be considered as the nextdow
, allowing for no adjustment to occur.

toprev
(dt::TimeType, dow::Int;same::Bool=false) → TimeType¶ Adjusts
dt
to the previous day of week corresponding todow
with1 = Monday, 2 = Tuesday, etc
. Settingsame=true
allows the currentdt
to be considered as the previousdow
, allowing for no adjustment to occur.

tofirst
(dt::TimeType, dow::Int;of=Month) → TimeType¶ Adjusts
dt
to the firstdow
of its month. Alternatively,of=Year
will adjust to the firstdow
of the year.

tolast
(dt::TimeType, dow::Int;of=Month) → TimeType¶ Adjusts
dt
to the lastdow
of its month. Alternatively,of=Year
will adjust to the lastdow
of the year.

tonext
(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) → TimeType Adjusts
dt
by iterating at mostlimit
iterations bystep
increments untilfunc
returnstrue
.func
must take a singleTimeType
argument and return aBool
.same
allowsdt
to be considered in satisfyingfunc
.negate
will make the adjustment process terminate whenfunc
returnsfalse
instead oftrue
.

toprev
(func::Function, dt::TimeType;step=Day(1), negate=false, limit=10000, same=false) → TimeType Adjusts
dt
by iterating at mostlimit
iterations bystep
increments untilfunc
returnstrue
.func
must take a singleTimeType
argument and return aBool
.same
allowsdt
to be considered in satisfyingfunc
.negate
will make the adjustment process terminate whenfunc
returnsfalse
instead oftrue
.

recur{T<:TimeType}
(func::Function, dr::StepRange{T};negate=false, limit=10000) → Vector{T}¶ func
takes a single TimeType argument and returns aBool
indicating whether the input should be “included” in the final set.recur
appliesfunc
over each element in the range ofdr
, including those elements for whichfunc
returnstrue
in the resulting Array, unlessnegate=true
, then only elements wherefunc
returnsfalse
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 givenv
value. Input must be losslessly convertible to anInt64
.

CompoundPeriod
(periods) → CompoundPeriod Construct a
CompoundPeriod
from aVector
ofPeriod
s. The constructor will automatically simplify the periods into a canonical form according to the following rules: All
Period
s of the same type will be added together  Any
Period
large enough be partially representable by a coarserPeriod
will be broken into multiplePeriod
s (eg.Hour(30)
becomesDay(1) + Hour(6)
) Period
s with opposite signs will be combined when possible (eg.Hour(1)  Day(1)
becomesHour(23)
)
Due to the canonicalization,
CompoundPeriod
is also useful for converting time periods into more humancomprehensible 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
 All

default
(p::Period) → Period¶ Returns a sensible “default” value for the input Period by returning
one(p)
for Year, Month, and Day, andzero(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
orDateTime
less than or equal todt
at resolutionp
.For convenience,
p
may be a type instead of a value:floor(dt, Dates.Hour)
is a shortcut forfloor(dt, Dates.Hour(1))
.julia> floor(Date(1985, 8, 16), Dates.Month) 19850801 julia> floor(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15)) 20130213T00:30:00 julia> floor(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day) 20160806T00:00:00

ceil
(dt::TimeType, p::Period) → TimeType¶ Returns the nearest
Date
orDateTime
greater than or equal todt
at resolutionp
.For convenience,
p
may be a type instead of a value:ceil(dt, Dates.Hour)
is a shortcut forceil(dt, Dates.Hour(1))
.julia> ceil(Date(1985, 8, 16), Dates.Month) 19850901 julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15)) 20130213T00:45:00 julia> ceil(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day) 20160807T00:00:00

round
(dt::TimeType, p::Period[, r::RoundingMode]) → TimeType¶ Returns the
Date
orDateTime
nearest todt
at resolutionp
. 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 forround(dt, Dates.Hour(1))
.julia> round(Date(1985, 8, 16), Dates.Month) 19850801 julia> round(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15)) 20130213T00:30:00 julia> round(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day) 20160807T00:00:00
Valid rounding modes for
round(::TimeType, ::Period, ::RoundingMode)
areRoundNearestTiesUp
(default),RoundDown
(floor
), andRoundUp
(ceil
).
The following functions are not exported:

floorceil
(dt::TimeType, p::Period) → (TimeType, TimeType)¶ Simultaneously return the
floor
andceil
of aDate
orDateTime
at resolutionp
. More efficient than calling bothfloor
andceil
individually.

epochdays2date
(days) → Date¶ Takes the number of days since the rounding epoch (
00000101T00:00:00
) and returns the correspondingDate
.

epochms2datetime
(milliseconds) → DateTime¶ Takes the number of milliseconds since the rounding epoch (
00000101T00:00:00
) and returns the correspondingDateTime
.

date2epochdays
(dt::Date) → Int64¶ Takes the given
Date
and returns the number of days since the rounding epoch (00000101T00:00:00
) as anInt64
.

datetime2epochms
(dt::DateTime) → Int64¶ Takes the given
DateTime
and returns the number of milliseconds since the rounding epoch (00000101T00:00:00
) as anInt64
.
Conversion Functions¶

today
() → Date¶ Returns the date portion of
now()
.

unix2datetime
(x) → DateTime¶ Takes the number of seconds since unix epoch
19700101T00:00:00
and converts to the correspondingDateTime
.

datetime2unix
(dt::DateTime) → Float64¶ Takes the given
DateTime
and returns the number of seconds since the unix epoch19700101T00:00:00
as aFloat64
.

julian2datetime
(julian_days) → DateTime¶ Takes the number of Julian calendar days since epoch
47131124T12:00:00
and returns the correspondingDateTime
.

datetime2julian
(dt::DateTime) → Float64¶ Takes the given
DateTime
and returns the number of Julian calendar days since the julian epoch47131124T12:00:00
as aFloat64
.

rata2datetime
(days) → DateTime¶ Takes the number of Rata Die days since epoch
00001231T00:00:00
and returns the correspondingDateTime
.

datetime2rata
(dt::TimeType) → Int64¶ Returns the number of Rata Die days since epoch from the given
Date
orDateTime
.
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 