Base.Dates.Period
Type
Period Year Month Week Day Hour Minute Second Millisecond Microsecond Nanosecond
Period
types represent discrete, human representations of time.
Base.Dates.CompoundPeriod
Type
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.
Base.Dates.Instant
Type
Instant
Instant
types represent integerbased, machine representations of time as continuous timelines starting from an epoch.
Base.Dates.UTInstant
Type
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.
Base.Dates.TimeType
Type
TimeType
TimeType
types wrap Instant
machine instances to provide human representations of the machine instant. Time
, DateTime
and Date
are subtypes of TimeType
.
Base.Dates.DateTime
Type
DateTime
DateTime
wraps a UTInstant{Millisecond}
and interprets it according to the proleptic Gregorian calendar.
Base.Dates.Date
Type
Date
Date
wraps a UTInstant{Day}
and interprets it according to the proleptic Gregorian calendar.
Base.Dates.Time
Type
Time
Time
wraps a Nanosecond
and represents a specific moment in a 24hour day.
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.
Base.Dates.DateTime
Method
DateTime(y, [m, d, h, mi, s, ms]) > DateTime
Construct a DateTime
type by parts. Arguments must be convertible to Int64
.
Base.Dates.DateTime
Method
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)
.
Base.Dates.DateTime
Method
DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), 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. 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).
Base.Dates.DateTime
Method
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.
Base.Dates.DateTime
Method
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.
This method creates a DateFormat
object each time it is called. If you are parsing many date strings of the same format, consider creating a DateFormat
object once and using that as the second argument instead.
Base.Dates.format
Function
format(io::IO, tok::AbstractDateToken, dt::TimeType, locale)
Format the tok
token from dt
and write it to io
. The formatting can be based on locale
.
All subtypes of AbstractDateToken
must define this method in order to be able to print a Date / DateTime object according to a DateFormat
containing that token.
Base.Dates.DateFormat
Type
DateFormat(format::AbstractString, locale="english") > DateFormat
Construct a date formatting object that can be used for parsing date strings or formatting a date object as a 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".
Creating a DateFormat object is expensive. Whenever possible, create it once and use it many times or try the dateformat""
string macro. Using this macro creates the DateFormat object once at macro expansion time and reuses it later. see @dateformat_str
.
See DateTime
and format
for how to use a DateFormat object to parse and write Date strings respectively.
Base.Dates.@dateformat_str
Macro
dateformat"Ymd H:M:S"
Create a DateFormat
object. Similar to DateFormat("Ymd H:M:S")
but creates the DateFormat object once during macro expansion.
See DateFormat
for details about format specifiers.
Base.Dates.DateTime
Method
DateTime(dt::AbstractString, df::DateFormat) > DateTime
Construct a DateTime
by parsing the dt
date string following the pattern given in the DateFormat
object. Similar to DateTime(::AbstractString, ::AbstractString)
but more efficient when repeatedly parsing similarly formatted date strings with a precreated DateFormat
object.
Base.Dates.Date
Method
Date(y, [m, d]) > Date
Construct a Date
type by parts. Arguments must be convertible to Int64
.
Base.Dates.Date
Method
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)
.
Base.Dates.Date
Method
Date(f::Function, y[, m, d]; step=Day(1), 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. 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).
Base.Dates.Date
Method
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.
Base.Dates.Date
Method
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)
.
Base.Dates.Date
Method
Date(dt::AbstractString, df::DateFormat) > Date
Parse a date from a date string dt
using a DateFormat
object df
.
Base.Dates.Time
Method
Time(h, [mi, s, ms, us, ns]) > Time
Construct a Time
type by parts. Arguments must be convertible to Int64
.
Base.Dates.Time
Method
Time(period::TimePeriod...) > Time
Construct a Time
type by Period
type parts. Arguments may be in any order. Time
parts not provided will default to the value of Dates.default(period)
.
Base.Dates.Time
Method
Time(f::Function, h, mi=0; step::Period=Second(1), limit::Int=10000) Time(f::Function, h, mi, s; step::Period=Millisecond(1), limit::Int=10000) Time(f::Function, h, mi, s, ms; step::Period=Microsecond(1), limit::Int=10000) Time(f::Function, h, mi, s, ms, us; step::Period=Nanosecond(1), limit::Int=10000)
Create a Time
through the adjuster API. The starting point will be constructed from the provided h, mi, s, ms, us
arguments, and will be adjusted until f::Function
returns true
. The step size in adjusting can be provided manually through the step
keyword. 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). Note that the default step will adjust to allow for greater precision for the given arguments; i.e. if hour, minute, and second arguments are provided, the default step will be Millisecond(1)
instead of Second(1)
.
Base.Dates.Time
Method
Time(dt::DateTime) > Time
Converts a DateTime
to a Time
. The hour, minute, second, and millisecond parts of the DateTime
are used to create the new Time
. Microsecond and nanoseconds are zero by default.
Base.Dates.now
Method
now() > DateTime
Returns a DateTime
corresponding to the user's system time including the system timezone locale.
Base.Dates.now
Method
now(::Type{UTC}) > DateTime
Returns a DateTime
corresponding to the user's system time as UTC/GMT.
Base.eps
Function
eps(::DateTime) > Millisecond eps(::Date) > Day eps(::Time) > Nanosecond
Returns Millisecond(1)
for DateTime
values, Day(1)
for Date
values, and Nanosecond(1)
for Time
values.
Base.Dates.year
Function
year(dt::TimeType) > Int64
The year of a Date
or DateTime
as an Int64
.
Base.Dates.month
Function
month(dt::TimeType) > Int64
The month of a Date
or DateTime
as an Int64
.
Base.Dates.week
Function
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.
Base.Dates.day
Function
day(dt::TimeType) > Int64
The day of month of a Date
or DateTime
as an Int64
.
Base.Dates.hour
Function
hour(dt::DateTime) > Int64
The hour of day of a DateTime
as an Int64
.
hour(t::Time) > Int64
The hour of a Time
as an Int64
.
Base.Dates.minute
Function
minute(dt::DateTime) > Int64
The minute of a DateTime
as an Int64
.
minute(t::Time) > Int64
The minute of a Time
as an Int64
.
Base.Dates.second
Function
second(dt::DateTime) > Int64
The second of a DateTime
as an Int64
.
second(t::Time) > Int64
The second of a Time
as an Int64
.
Base.Dates.millisecond
Function
millisecond(dt::DateTime) > Int64
The millisecond of a DateTime
as an Int64
.
millisecond(t::Time) > Int64
The millisecond of a Time
as an Int64
.
Base.Dates.microsecond
Function
microsecond(t::Time) > Int64
The microsecond of a Time
as an Int64
.
Base.Dates.nanosecond
Function
nanosecond(t::Time) > Int64
The nanosecond of a Time
as an Int64
.
Base.Dates.Year
Method
Year(v)
Construct a Year
object with the given v
value. Input must be losslessly convertible to an Int64
.
Base.Dates.Month
Method
Month(v)
Construct a Month
object with the given v
value. Input must be losslessly convertible to an Int64
.
Base.Dates.Week
Method
Week(v)
Construct a Week
object with the given v
value. Input must be losslessly convertible to an Int64
.
Base.Dates.Day
Method
Day(v)
Construct a Day
object with the given v
value. Input must be losslessly convertible to an Int64
.
Base.Dates.Hour
Method
Hour(dt::DateTime) > Hour
The hour part of a DateTime as a Hour
.
Base.Dates.Minute
Method
Minute(dt::DateTime) > Minute
The minute part of a DateTime as a Minute
.
Base.Dates.Second
Method
Second(dt::DateTime) > Second
The second part of a DateTime as a Second
.
Base.Dates.Millisecond
Method
Millisecond(dt::DateTime) > Millisecond
The millisecond part of a DateTime as a Millisecond
.
Base.Dates.Microsecond
Method
Microsecond(dt::Time) > Microsecond
The microsecond part of a Time as a Microsecond
.
Base.Dates.Nanosecond
Method
Nanosecond(dt::Time) > Nanosecond
The nanosecond part of a Time as a Nanosecond
.
Base.Dates.yearmonth
Function
yearmonth(dt::TimeType) > (Int64, Int64)
Simultaneously return the year and month parts of a Date
or DateTime
.
Base.Dates.monthday
Function
monthday(dt::TimeType) > (Int64, Int64)
Simultaneously return the month and day parts of a Date
or DateTime
.
Base.Dates.yearmonthday
Function
yearmonthday(dt::TimeType) > (Int64, Int64, Int64)
Simultaneously return the year, month and day parts of a Date
or DateTime
.
Base.Dates.dayname
Function
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
.
Base.Dates.dayabbr
Function
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
.
Base.Dates.dayofweek
Function
dayofweek(dt::TimeType) > Int64
Returns the day of the week as an Int64
with 1 = Monday, 2 = Tuesday, etc.
.
Base.Dates.dayofmonth
Function
dayofmonth(dt::TimeType) > Int64
The day of month of a Date
or DateTime
as an Int64
.
Base.Dates.dayofweekofmonth
Function
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.
Base.Dates.daysofweekinmonth
Function
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.
Base.Dates.monthname
Function
monthname(dt::TimeType; locale="english") > AbstractString
Return the full name of the month of the Date
or DateTime
in the given locale
.
Base.Dates.monthabbr
Function
monthabbr(dt::TimeType; locale="english") > AbstractString
Return the abbreviated month name of the Date
or DateTime
in the given locale
.
Base.Dates.daysinmonth
Function
daysinmonth(dt::TimeType) > Int
Returns the number of days in the month of dt
. Value will be 28, 29, 30, or 31.
Base.Dates.isleapyear
Function
isleapyear(dt::TimeType) > Bool
Returns true
if the year of dt
is a leap year.
Base.Dates.dayofyear
Function
dayofyear(dt::TimeType) > Int
Returns the day of the year for dt
with January 1st being day 1.
Base.Dates.daysinyear
Function
daysinyear(dt::TimeType) > Int
Returns 366 if the year of dt
is a leap year, otherwise returns 365.
Base.Dates.quarterofyear
Function
quarterofyear(dt::TimeType) > Int
Returns the quarter that dt
resides in. Range of value is 1:4.
Base.Dates.dayofquarter
Function
dayofquarter(dt::TimeType) > Int
Returns the day of the current quarter of dt
. Range of value is 1:92.
Base.trunc
Method
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
.
Base.Dates.firstdayofweek
Function
firstdayofweek(dt::TimeType) > TimeType
Adjusts dt
to the Monday of its week.
Base.Dates.lastdayofweek
Function
lastdayofweek(dt::TimeType) > TimeType
Adjusts dt
to the Sunday of its week.
Base.Dates.firstdayofmonth
Function
firstdayofmonth(dt::TimeType) > TimeType
Adjusts dt
to the first day of its month.
Base.Dates.lastdayofmonth
Function
lastdayofmonth(dt::TimeType) > TimeType
Adjusts dt
to the last day of its month.
Base.Dates.firstdayofyear
Function
firstdayofyear(dt::TimeType) > TimeType
Adjusts dt
to the first day of its year.
Base.Dates.lastdayofyear
Function
lastdayofyear(dt::TimeType) > TimeType
Adjusts dt
to the last day of its year.
Base.Dates.firstdayofquarter
Function
firstdayofquarter(dt::TimeType) > TimeType
Adjusts dt
to the first day of its quarter.
Base.Dates.lastdayofquarter
Function
lastdayofquarter(dt::TimeType) > TimeType
Adjusts dt
to the last day of its quarter.
Base.Dates.tonext
Method
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.
Base.Dates.toprev
Method
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.
Base.Dates.tofirst
Function
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.
Base.Dates.tolast
Function
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.
Base.Dates.tonext
Method
tonext(func::Function, dt::TimeType; step=Day(1), 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
.
Base.Dates.toprev
Method
toprev(func::Function, dt::TimeType; step=Day(1), 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
.
Base.Dates.Period
Method
Year(v) Month(v) Week(v) Day(v) Hour(v) Minute(v) Second(v) Millisecond(v) Microsecond(v) Nanosecond(v)
Construct a Period
type with the given v
value. Input must be losslessly convertible to an Int64
.
Base.Dates.CompoundPeriod
Method
CompoundPeriod(periods) > CompoundPeriod
Construct a CompoundPeriod
from a Vector
of Period
s. All Period
s of the same type will be added together.
Examples
julia> Dates.CompoundPeriod(Dates.Hour(12), Dates.Hour(13)) 25 hours julia> Dates.CompoundPeriod(Dates.Hour(1), Dates.Minute(1)) 1 hour, 1 minute julia> Dates.CompoundPeriod(Dates.Month(1), Dates.Week(2)) 1 month, 2 weeks julia> Dates.CompoundPeriod(Dates.Minute(50000)) 50000 minutessource
Base.Dates.default
Function
default(p::Period) > Period
Returns a sensible "default" value for the input Period by returning T(1)
for Year, Month, and Day, and T(0)
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
.
Base.floor
Method
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:00source
Base.ceil
Method
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:00source
Base.round
Method
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:
Base.Dates.floorceil
Function
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.
Base.Dates.epochdays2date
Function
epochdays2date(days) > Date
Takes the number of days since the rounding epoch (00000101T00:00:00
) and returns the corresponding Date
.
Base.Dates.epochms2datetime
Function
epochms2datetime(milliseconds) > DateTime
Takes the number of milliseconds since the rounding epoch (00000101T00:00:00
) and returns the corresponding DateTime
.
Base.Dates.date2epochdays
Function
date2epochdays(dt::Date) > Int64
Takes the given Date
and returns the number of days since the rounding epoch (00000101T00:00:00
) as an Int64
.
Base.Dates.datetime2epochms
Function
datetime2epochms(dt::DateTime) > Int64
Takes the given DateTime
and returns the number of milliseconds since the rounding epoch (00000101T00:00:00
) as an Int64
.
Base.Dates.today
Function
today() > Date
Returns the date portion of now()
.
Base.Dates.unix2datetime
Function
unix2datetime(x) > DateTime
Takes the number of seconds since unix epoch 19700101T00:00:00
and converts to the corresponding DateTime
.
Base.Dates.datetime2unix
Function
datetime2unix(dt::DateTime) > Float64
Takes the given DateTime
and returns the number of seconds since the unix epoch 19700101T00:00:00
as a Float64
.
Base.Dates.julian2datetime
Function
julian2datetime(julian_days) > DateTime
Takes the number of Julian calendar days since epoch 47131124T12:00:00
and returns the corresponding DateTime
.
Base.Dates.datetime2julian
Function
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
.
Base.Dates.rata2datetime
Function
rata2datetime(days) > DateTime
Takes the number of Rata Die days since epoch 00001231T00:00:00
and returns the corresponding DateTime
.
Base.Dates.datetime2rata
Function
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.
https://docs.julialang.org/en/release0.6/stdlib/dates/