# 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 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 integer-based, 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.

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

`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 3-chars 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 (24-hour 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 `yyyy-mm` 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: fixed-width or minimum-width. The fixed-width mode left-pads the value with zeros when it is shorter than the specified width and truncates the value when longer. Minimum-width mode works the same as fixed-width except that it does not truncate values longer than the width.

  When creating a `format` you can use any non-code characters as a separator. For example to generate the string “1996-01-15T00:00:00” you could use `format`: “yyyy-mm-ddTHH: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 pre-created `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.

### Accessor Functions

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

### Query Functions

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

### Adjuster Functions

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

`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}`(func::Function, dr::StepRange{T};negate=false, limit=10000) → Vector{T}

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

### Periods

`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:

  - All `Period`s of the same type will be added together
  - Any `Period` 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 human-comprehensible 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.

### 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` 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

`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

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

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 (`0000-01-01T00:00:00`) and returns the corresponding `Date`.

`epochms2datetime`(milliseconds) → DateTime

  Takes the number of milliseconds since the rounding epoch (`0000-01-01T00: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 (`0000-01-01T00:00:00`) as an `Int64`.

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

### Conversion Functions

`today`() → Date

  Returns the date portion of `now()`.

`unix2datetime`(x) → DateTime

  Takes the number of seconds since unix epoch `1970-01-01T00: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 `1970-01-01T00:00:00` as a `Float64`.

`julian2datetime`(julian_days) → DateTime

  Takes the number of Julian calendar days since epoch `-4713-11-24T12: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 `-4713-11-24T12:00:00` as a `Float64`.

`rata2datetime`(days) → DateTime

  Takes the number of Rata Die days since epoch `0000-12-31T00: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`.

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