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 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). 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.
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 2digit 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 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 a format
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 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 3chars 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 (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 code y
should have a width of four while m
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 use format
: “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 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 precreated 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.
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
.
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.
trunc(dt::TimeType, ::Type{Period}) → TimeType
Truncates the value of dt
according to the provided Period
type. E.g. if dt
is 19960101T12:30:00
, then trunc(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 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.
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 Period
s. The constructor will automatically simplify the periods into a canonical form according to the following rules:
Period
s of the same type will be added togetherPeriod
large enough be partially representable by a coarser Period
will be broken into multiple Period
s (eg. Hour(30)
becomes Day(1) + Hour(6)
)Period
s 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 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
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.
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) 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
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) 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
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) 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)
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 (00000101T00:00:00
) and returns the corresponding Date
.
epochms2datetime(milliseconds) → DateTime
Takes the number of milliseconds since the rounding epoch (00000101T00: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 (00000101T00:00:00
) as an Int64
.
datetime2epochms(dt::DateTime) → Int64
Takes the given DateTime
and returns the number of milliseconds since the rounding epoch (00000101T00:00:00
) as an Int64
.
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 corresponding DateTime
.
datetime2unix(dt::DateTime) → Float64
Takes the given DateTime
and returns the number of seconds since the unix epoch 19700101T00:00:00
as a Float64
.
julian2datetime(julian_days) → DateTime
Takes the number of Julian calendar days since epoch 47131124T12: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 47131124T12:00:00
as a Float64
.
rata2datetime(days) → DateTime
Takes the number of Rata Die days since epoch 00001231T00: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
.
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 
© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
http://docs.julialang.org/en/release0.5/stdlib/dates/