W3cubDocs

/Julia 0.6

Dates and Time

Dates and Time Types

Base.Dates.PeriodType

Period
Year
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

Period types represent discrete, human representations of time.

source

Base.Dates.CompoundPeriodType

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.

source

Base.Dates.InstantType

Instant

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

source

Base.Dates.UTInstantType

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.

source

Base.Dates.TimeTypeType

TimeType

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

source

Base.Dates.DateTimeType

DateTime

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

source

Base.Dates.DateType

Date

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

source

Base.Dates.TimeType

Time

Time wraps a Nanosecond and represents a specific moment in a 24-hour day.

source

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.

Base.Dates.DateTimeMethod

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

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

source

Base.Dates.DateTimeMethod

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

source

Base.Dates.DateTimeMethod

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

source

Base.Dates.DateTimeMethod

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.

source

Base.Dates.DateTimeMethod

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.

source

Base.Dates.formatFunction

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.

source

Base.Dates.DateFormatType

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

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.

source

Base.Dates.@dateformat_strMacro

dateformat"Y-m-d H:M:S"

Create a DateFormat object. Similar to DateFormat("Y-m-d H:M:S") but creates the DateFormat object once during macro expansion.

See DateFormat for details about format specifiers.

source

Base.Dates.DateTimeMethod

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 pre-created DateFormat object.

source

Base.Dates.DateMethod

Date(y, [m, d]) -> Date

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

source

Base.Dates.DateMethod

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

source

Base.Dates.DateMethod

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

source

Base.Dates.DateMethod

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.

source

Base.Dates.DateMethod

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

source

Base.Dates.DateMethod

Date(dt::AbstractString, df::DateFormat) -> Date

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

source

Base.Dates.TimeMethod

Time(h, [mi, s, ms, us, ns]) -> Time

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

source

Base.Dates.TimeMethod

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

source

Base.Dates.TimeMethod

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

source

Base.Dates.TimeMethod

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.

source

Base.Dates.nowMethod

now() -> DateTime

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

source

Base.Dates.nowMethod

now(::Type{UTC}) -> DateTime

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

source

Base.epsFunction

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.

source

Accessor Functions

Base.Dates.yearFunction

year(dt::TimeType) -> Int64

The year of a Date or DateTime as an Int64.

source

Base.Dates.monthFunction

month(dt::TimeType) -> Int64

The month of a Date or DateTime as an Int64.

source

Base.Dates.weekFunction

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.

source

Base.Dates.dayFunction

day(dt::TimeType) -> Int64

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

source

Base.Dates.hourFunction

hour(dt::DateTime) -> Int64

The hour of day of a DateTime as an Int64.

source
hour(t::Time) -> Int64

The hour of a Time as an Int64.

source

Base.Dates.minuteFunction

minute(dt::DateTime) -> Int64

The minute of a DateTime as an Int64.

source
minute(t::Time) -> Int64

The minute of a Time as an Int64.

source

Base.Dates.secondFunction

second(dt::DateTime) -> Int64

The second of a DateTime as an Int64.

source
second(t::Time) -> Int64

The second of a Time as an Int64.

source

Base.Dates.millisecondFunction

millisecond(dt::DateTime) -> Int64

The millisecond of a DateTime as an Int64.

source
millisecond(t::Time) -> Int64

The millisecond of a Time as an Int64.

source

Base.Dates.microsecondFunction

microsecond(t::Time) -> Int64

The microsecond of a Time as an Int64.

source

Base.Dates.nanosecondFunction

nanosecond(t::Time) -> Int64

The nanosecond of a Time as an Int64.

source

Base.Dates.YearMethod

Year(v)

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

source

Base.Dates.MonthMethod

Month(v)

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

source

Base.Dates.WeekMethod

Week(v)

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

source

Base.Dates.DayMethod

Day(v)

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

source

Base.Dates.HourMethod

Hour(dt::DateTime) -> Hour

The hour part of a DateTime as a Hour.

source

Base.Dates.MinuteMethod

Minute(dt::DateTime) -> Minute

The minute part of a DateTime as a Minute.

source

Base.Dates.SecondMethod

Second(dt::DateTime) -> Second

The second part of a DateTime as a Second.

source

Base.Dates.MillisecondMethod

Millisecond(dt::DateTime) -> Millisecond

The millisecond part of a DateTime as a Millisecond.

source

Base.Dates.MicrosecondMethod

Microsecond(dt::Time) -> Microsecond

The microsecond part of a Time as a Microsecond.

source

Base.Dates.NanosecondMethod

Nanosecond(dt::Time) -> Nanosecond

The nanosecond part of a Time as a Nanosecond.

source

Base.Dates.yearmonthFunction

yearmonth(dt::TimeType) -> (Int64, Int64)

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

source

Base.Dates.monthdayFunction

monthday(dt::TimeType) -> (Int64, Int64)

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

source

Base.Dates.yearmonthdayFunction

yearmonthday(dt::TimeType) -> (Int64, Int64, Int64)

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

source

Query Functions

Base.Dates.daynameFunction

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.

source

Base.Dates.dayabbrFunction

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.

source

Base.Dates.dayofweekFunction

dayofweek(dt::TimeType) -> Int64

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

source

Base.Dates.dayofmonthFunction

dayofmonth(dt::TimeType) -> Int64

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

source

Base.Dates.dayofweekofmonthFunction

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.

source

Base.Dates.daysofweekinmonthFunction

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.

source

Base.Dates.monthnameFunction

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

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

source

Base.Dates.monthabbrFunction

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

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

source

Base.Dates.daysinmonthFunction

daysinmonth(dt::TimeType) -> Int

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

source

Base.Dates.isleapyearFunction

isleapyear(dt::TimeType) -> Bool

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

source

Base.Dates.dayofyearFunction

dayofyear(dt::TimeType) -> Int

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

source

Base.Dates.daysinyearFunction

daysinyear(dt::TimeType) -> Int

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

source

Base.Dates.quarterofyearFunction

quarterofyear(dt::TimeType) -> Int

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

source

Base.Dates.dayofquarterFunction

dayofquarter(dt::TimeType) -> Int

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

source

Adjuster Functions

Base.truncMethod

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.

source

Base.Dates.firstdayofweekFunction

firstdayofweek(dt::TimeType) -> TimeType

Adjusts dt to the Monday of its week.

source

Base.Dates.lastdayofweekFunction

lastdayofweek(dt::TimeType) -> TimeType

Adjusts dt to the Sunday of its week.

source

Base.Dates.firstdayofmonthFunction

firstdayofmonth(dt::TimeType) -> TimeType

Adjusts dt to the first day of its month.

source

Base.Dates.lastdayofmonthFunction

lastdayofmonth(dt::TimeType) -> TimeType

Adjusts dt to the last day of its month.

source

Base.Dates.firstdayofyearFunction

firstdayofyear(dt::TimeType) -> TimeType

Adjusts dt to the first day of its year.

source

Base.Dates.lastdayofyearFunction

lastdayofyear(dt::TimeType) -> TimeType

Adjusts dt to the last day of its year.

source

Base.Dates.firstdayofquarterFunction

firstdayofquarter(dt::TimeType) -> TimeType

Adjusts dt to the first day of its quarter.

source

Base.Dates.lastdayofquarterFunction

lastdayofquarter(dt::TimeType) -> TimeType

Adjusts dt to the last day of its quarter.

source

Base.Dates.tonextMethod

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.

source

Base.Dates.toprevMethod

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.

source

Base.Dates.tofirstFunction

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.

source

Base.Dates.tolastFunction

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.

source

Base.Dates.tonextMethod

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.

source

Base.Dates.toprevMethod

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.

source

Periods

Base.Dates.PeriodMethod

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.

source

Base.Dates.CompoundPeriodMethod

CompoundPeriod(periods) -> CompoundPeriod

Construct a CompoundPeriod from a Vector of Periods. All Periods 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 minutes
source

Base.Dates.defaultFunction

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.

source

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.

Base.floorMethod

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
source

Base.ceilMethod

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
source

Base.roundMethod

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

source

The following functions are not exported:

Base.Dates.floorceilFunction

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.

source

Base.Dates.epochdays2dateFunction

epochdays2date(days) -> Date

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

source

Base.Dates.epochms2datetimeFunction

epochms2datetime(milliseconds) -> DateTime

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

source

Base.Dates.date2epochdaysFunction

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.

source

Base.Dates.datetime2epochmsFunction

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.

source

Conversion Functions

Base.Dates.todayFunction

today() -> Date

Returns the date portion of now().

source

Base.Dates.unix2datetimeFunction

unix2datetime(x) -> DateTime

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

source

Base.Dates.datetime2unixFunction

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.

source

Base.Dates.julian2datetimeFunction

julian2datetime(julian_days) -> DateTime

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

source

Base.Dates.datetime2julianFunction

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.

source

Base.Dates.rata2datetimeFunction

rata2datetime(days) -> DateTime

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

source

Base.Dates.datetime2rataFunction

datetime2rata(dt::TimeType) -> Int64

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

source

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

© 2009–2016 Jeff Bezanson, Stefan Karpinski, Viral B. Shah, and other contributors
Licensed under the MIT License.
https://docs.julialang.org/en/release-0.6/stdlib/dates/