Dates and Time¶
Dates and Time Types¶

Period
¶ 
Year
¶ 
Month
¶ 
Week
¶ 
Day
¶ 
Hour
¶ 
Minute
¶ 
Second
¶ 
Millisecond
¶ Period
types represent discrete, human representations of time.

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.

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 Constuct 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
type 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
type by parsing thedt
date string following the pattern given in theformat
string. The following codes can be used for constructing format strings:Code Matches Comment y
1996, 96 Returns year of 1996, 0096 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 All characters not listed above are treated as delimiters between date and time slots. So a
dt
string of “19960115T00:00:00.0” would have aformat
string like “ymdTH:M:S.s”.

Dates.
DateFormat
(format::AbstractString) → DateFormat¶ Construct a date formatting object that can be passed repeatedly for parsing similarly formatted date strings.
format
is a format string in the form described above (e.g."yyyymmdd"
).

DateTime
(dt::AbstractString, df::DateFormat) → DateTime Similar form as above for parsing a
DateTime
, but passes aDateFormat
object instead of a raw formatting string. It is more efficient if similarly formatted date strings will be parsed repeatedly to first create aDateFormat
object then use this method for parsing.

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

Date
(period::Period...) → Date Constuct 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]; 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
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
type 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
type by parsing adt
date string following the pattern given in theformat
string. Follows the same conventions asDateTime
above.

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¶ 
month
(dt::TimeType) → Int64¶ 
week
(dt::TimeType) → Int64¶ 
day
(dt::TimeType) → Int64¶ 
hour
(dt::TimeType) → Int64¶ 
minute
(dt::TimeType) → Int64¶ 
second
(dt::TimeType) → Int64¶ 
millisecond
(dt::TimeType) → Int64¶ Return the field part of a
Date
orDateTime
as anInt64
.

Year
(dt::TimeType) → Year 
Month
(dt::TimeType) → Month 
Week
(dt::TimeType) → Week 
Day
(dt::TimeType) → Day 
Hour
(dt::TimeType) → Hour 
Minute
(dt::TimeType) → Minute 
Second
(dt::TimeType) → Second 
Millisecond
(dt::TimeType) → Millisecond Return the field part of a
Date
orDateTime
as aPeriod
type.

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

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
.

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