From 88f56a09aa434c0bc6af374a16887e3d93070f30 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Mon, 4 Nov 2024 13:52:19 +0000 Subject: [PATCH] build based on f54f7fa --- dev/.documenter-siteinfo.json | 2 +- dev/index.html | 15 +++++++-------- dev/search_index.js | 2 +- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index c459370..74cc8e8 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-10-23T15:09:28","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.0","generation_timestamp":"2024-11-04T13:52:13","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 76fce56..8458da9 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,8 +1,7 @@ CFTime.jl · CFTime
GitHub

CFTime.jl

This package implements the calendar types from the CF convention, namely:

  • Mixed Gregorian/Julian calendar (DateTimeStandard)
  • Proleptic gregorian calendar (DateTimeProlepticGregorian)
  • Gregorian calendar without leap years (all years are 365 days long) (DateTimeNoLeap)
  • Gregorian calendar with only leap year (all years are 366 days long) (DateTimeAllLeap)
  • A calendar with every year being 360 days long (divided into 30 day months) (DateTime360Day)
  • Julian calendar (DateTimeJulian)

Note that time zones are not supported by CFTime.jl.

Installation

Inside the Julia shell, you can download and install the package by issuing:

using Pkg
 Pkg.add("CFTime")

Latest development version

If you want to try the latest development version, you can do this with the following commands:

using Pkg
-Pkg.add(PackageSpec(url="https://github.com/JuliaGeo/CFTime.jl", rev="master"))
-Pkg.build("CFTime")

Types

CFTime.DateTimeStandard — Type
DateTimeStandard([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeStandard

Construct a DateTimeStandard type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeStandard is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "standard".

source
DateTimeStandard(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeStandard

Construct a DateTimeStandard by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeJulian — Type
DateTimeJulian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeJulian

Construct a DateTimeJulian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeJulian is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "julian".

source
DateTimeJulian(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeJulian

Construct a DateTimeJulian by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeProlepticGregorian — Type
DateTimeProlepticGregorian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeProlepticGregorian

Construct a DateTimeProlepticGregorian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeProlepticGregorian is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "prolepticgregorian".

source
DateTimeProlepticGregorian(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeProlepticGregorian

Construct a DateTimeProlepticGregorian by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeAllLeap — Type
DateTimeAllLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeAllLeap

Construct a DateTimeAllLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeAllLeap is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "allleap".

source
DateTimeAllLeap(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeAllLeap

Construct a DateTimeAllLeap by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeNoLeap — Type
DateTimeNoLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeNoLeap

Construct a DateTimeNoLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeNoLeap is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "noleap".

source
DateTimeNoLeap(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeNoLeap

Construct a DateTimeNoLeap by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTime360Day — Type
DateTime360Day([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTime360Day

Construct a DateTime360Day type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTime360Day is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "360day".

source
DateTime360Day(dt::AbstractString, format::AbstractString; locale="english") -> DateTime360Day

Construct a DateTime360Day by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source

Time encoding and decoding

CFTime.timedecode — Function
dt = timedecode(data,units,calendar = "standard"; prefer_datetime = true)

Decode the time information in data as given by the units units according to the specified calendar. Valid values for calendar are "standard", "gregorian", "proleptic_gregorian", "julian", "noleap", "365_day", "all_leap", "366_day" and "360_day".

If prefer_datetime is true (default), dates are converted to the DateTime type (for the calendars "standard", "gregorian", "proleptic_gregorian" and "julian") unless the time unit is expressed in microseconds or smaller. Such conversion is not possible for the other calendars.

CalendarType (prefer_datetime=true)Type (prefer_datetime=false)
standard, gregorianDateTimeDateTimeStandard
proleptic_gregorianDateTimeDateTimeProlepticGregorian
julianDateTimeDateTimeJulian
noleap, 365_dayDateTimeNoLeapDateTimeNoLeap
all_leap, 366_dayDateTimeAllLeapDateTimeAllLeap
360_dayDateTime360DayDateTime360Day

Example:

using CFTime, Dates
+Pkg.add(PackageSpec(url="https://github.com/JuliaGeo/CFTime.jl", rev="master"))

Types

CFTime.DateTimeStandard — Type
DateTimeStandard([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeStandard

Construct a DateTimeStandard type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeStandard is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "standard".

source
DateTimeStandard(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeStandard

Construct a DateTimeStandard by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeJulian — Type
DateTimeJulian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeJulian

Construct a DateTimeJulian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeJulian is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "julian".

source
DateTimeJulian(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeJulian

Construct a DateTimeJulian by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeProlepticGregorian — Type
DateTimeProlepticGregorian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeProlepticGregorian

Construct a DateTimeProlepticGregorian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeProlepticGregorian is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "prolepticgregorian".

source
DateTimeProlepticGregorian(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeProlepticGregorian

Construct a DateTimeProlepticGregorian by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeAllLeap — Type
DateTimeAllLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeAllLeap

Construct a DateTimeAllLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeAllLeap is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "allleap".

source
DateTimeAllLeap(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeAllLeap

Construct a DateTimeAllLeap by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTimeNoLeap — Type
DateTimeNoLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeNoLeap

Construct a DateTimeNoLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeNoLeap is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "noleap".

source
DateTimeNoLeap(dt::AbstractString, format::AbstractString; locale="english") -> DateTimeNoLeap

Construct a DateTimeNoLeap by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source
CFTime.DateTime360Day — Type
DateTime360Day([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTime360Day

Construct a DateTime360Day type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTime360Day is a subtype of AbstractCFDateTime.

The netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as "360day".

source
DateTime360Day(dt::AbstractString, format::AbstractString; locale="english") -> DateTime360Day

Construct a DateTime360Day by parsing the dt date time string following the pattern given in the format string.

Note

This function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.

source

Time encoding and decoding

CFTime.timedecode — Function
dt = timedecode(data,units,calendar = "standard"; prefer_datetime = true)

Decode the time information in data as given by the units units according to the specified calendar. Valid values for calendar are "standard", "gregorian", "proleptic_gregorian", "julian", "noleap", "365_day", "all_leap", "366_day" and "360_day".

If prefer_datetime is true (default), dates are converted to the DateTime type (for the calendars "standard", "gregorian", "proleptic_gregorian" and "julian") unless the time unit is expressed in microseconds or smaller. Such conversion is not possible for the other calendars.

CalendarType (prefer_datetime=true)Type (prefer_datetime=false)
standard, gregorianDateTimeDateTimeStandard
proleptic_gregorianDateTimeDateTimeProlepticGregorian
julianDateTimeDateTimeJulian
noleap, 365_dayDateTimeNoLeapDateTimeNoLeap
all_leap, 366_dayDateTimeAllLeapDateTimeAllLeap
360_dayDateTime360DayDateTime360Day

Example:

using CFTime, Dates
 # standard calendar
 dt = CFTime.timedecode([0,1,2,3],"days since 2000-01-01 00:00:00")
 # 4-element Array{Dates.DateTime,1}:
@@ -16,11 +15,11 @@
 #  DateTime360Day(2000-01-01T00:00:00)
 #  DateTime360Day(2000-01-02T00:00:00)
 #  DateTime360Day(2000-01-03T00:00:00)
-#  DateTime360Day(2000-01-04T00:00:00)
source
CFTime.timeencode — Function
data = timeencode(dt,units,calendar = "standard")

Convert a vector or array of DateTime (or DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian, DateTimeNoLeap, DateTimeAllLeap, DateTime360Day) according to the specified units (e.g. "days since 2000-01-01 00:00:00") using the calendar calendar. Valid values for calendar are: "standard", "gregorian", "proleptic_gregorian", "julian", "noleap", "365_day", "all_leap", "366_day", "360_day".

source

Accessor Functions

Dates.year — Method
Dates.year(dt::AbstractCFDateTime) -> Int64

Extract the year part of an AbstractCFDateTime as an Int64.

source
Dates.month — Method
Dates.month(dt::AbstractCFDateTime) -> Int64

Extract the month part of an AbstractCFDateTime as an Int64.

source
Dates.day — Method
Dates.day(dt::AbstractCFDateTime) -> Int64

Extract the day part of an AbstractCFDateTime as an Int64.

source
Dates.hour — Method
Dates.hour(dt::AbstractCFDateTime) -> Int64

Extract the hour part of an AbstractCFDateTime as an Int64.

source
Dates.minute — Method
Dates.minute(dt::AbstractCFDateTime) -> Int64

Extract the minute part of an AbstractCFDateTime as an Int64.

source
Dates.second — Method
Dates.second(dt::AbstractCFDateTime) -> Int64

Extract the second part of an AbstractCFDateTime as an Int64.

source
Dates.millisecond — Method
Dates.millisecond(dt::AbstractCFDateTime) -> Int64

Extract the millisecond part of an AbstractCFDateTime as an Int64.

source
Dates.microsecond — Method
Dates.microsecond(dt::AbstractCFDateTime) -> Int64

Extract the microsecond part of an AbstractCFDateTime as an Int64.

source
Dates.nanosecond — Method
Dates.nanosecond(dt::AbstractCFDateTime) -> Int64

Extract the nanosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.picosecond — Method
CFTime.picosecond(dt::AbstractCFDateTime) -> Int64

Extract the picosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.femtosecond — Method
CFTime.femtosecond(dt::AbstractCFDateTime) -> Int64

Extract the femtosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.attosecond — Method
CFTime.attosecond(dt::AbstractCFDateTime) -> Int64

Extract the attosecond part of an AbstractCFDateTime as an Int64.

source

Query Functions

Dates.daysinmonth — Function
monthlength = daysinmonth(::Type{DT},y,m)

Returns the number of days in a month for the year y and the month m according to the calendar given by the type DT.

Example

julia> daysinmonth(DateTimeAllLeap,2001,2)
-29
source
monthlength = daysinmonth(t)

Returns the number of days in a month containing the date t

Example

julia> daysinmonth(DateTimeAllLeap(2001,2,1))
-29
source
Dates.daysinyear — Function
yearlength = daysinyear(::Type{DT},y)

Returns the number of days in a year for the year y according to the calendar given by the type DT.

Example

julia> daysinyear(DateTimeAllLeap,2001,2)
-366
source
yearlength = daysinyear(t)

Returns the number of days in a year containing the date t

Example

julia> daysinyear(DateTimeAllLeap(2001,2,1))
-366
source
Dates.yearmonthday — Function
yearmonthday(dt::AbstractCFDateTime) -> (Int64, Int64, Int64)

Simultaneously return the year, month and day parts of dt.

source
Dates.yearmonth — Function
yearmonth(dt::AbstractCFDateTime) -> (Int64, Int64)

Simultaneously return the year and month parts of dt.

source
Dates.monthday — Function
monthday(dt::AbstractCFDateTime) -> (Int64, Int64)

Simultaneously return the month and day parts of dt.

source
Dates.firstdayofyear — Function
firstdayofyear(dt::AbstractCFDateTime) -> Int

Return the first day of the year including the date dt

source
Dates.dayofyear — Function
dayofyear(dt::AbstractCFDateTime) -> Int

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

source

Convertion Functions

Base.convert — Function
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
Base.reinterpret — Function
dt2 = reinterpret(::Type{T}, dt)

Convert a variable dt of type DateTime, DateTimeStandard, DateTimeJulian, DateTimeProlepticGregorian, DateTimeAllLeap, DateTimeNoLeap or DateTime360Day into the date time type T using the same values for year, month, day, minute, second and millisecond. The conversion might fail if a particular date does not exist in the target calendar.

source

Arithmetic

Adding and subtracting time periods is supported:

DateTimeStandard(1582,10,4) + Dates.Day(1)
+#  DateTime360Day(2000-01-04T00:00:00)
source
CFTime.timeencode — Function
data = timeencode(dt,units,calendar = "standard")

Convert a vector or array of DateTime (or DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian, DateTimeNoLeap, DateTimeAllLeap, DateTime360Day) according to the specified units (e.g. "days since 2000-01-01 00:00:00") using the calendar calendar. Valid values for calendar are: "standard", "gregorian", "proleptic_gregorian", "julian", "noleap", "365_day", "all_leap", "366_day", "360_day".

source

Accessor Functions

Dates.year — Method
Dates.year(dt::AbstractCFDateTime) -> Int64

Extract the year part of an AbstractCFDateTime as an Int64.

source
Dates.month — Method
Dates.month(dt::AbstractCFDateTime) -> Int64

Extract the month part of an AbstractCFDateTime as an Int64.

source
Dates.day — Method
Dates.day(dt::AbstractCFDateTime) -> Int64

Extract the day part of an AbstractCFDateTime as an Int64.

source
Dates.hour — Method
Dates.hour(dt::AbstractCFDateTime) -> Int64

Extract the hour part of an AbstractCFDateTime as an Int64.

source
Dates.minute — Method
Dates.minute(dt::AbstractCFDateTime) -> Int64

Extract the minute part of an AbstractCFDateTime as an Int64.

source
Dates.second — Method
Dates.second(dt::AbstractCFDateTime) -> Int64

Extract the second part of an AbstractCFDateTime as an Int64.

source
Dates.millisecond — Method
Dates.millisecond(dt::AbstractCFDateTime) -> Int64

Extract the millisecond part of an AbstractCFDateTime as an Int64.

source
Dates.microsecond — Method
Dates.microsecond(dt::AbstractCFDateTime) -> Int64

Extract the microsecond part of an AbstractCFDateTime as an Int64.

source
Dates.nanosecond — Method
Dates.nanosecond(dt::AbstractCFDateTime) -> Int64

Extract the nanosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.picosecond — Method
CFTime.picosecond(dt::AbstractCFDateTime) -> Int64

Extract the picosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.femtosecond — Method
CFTime.femtosecond(dt::AbstractCFDateTime) -> Int64

Extract the femtosecond part of an AbstractCFDateTime as an Int64.

source
CFTime.attosecond — Method
CFTime.attosecond(dt::AbstractCFDateTime) -> Int64

Extract the attosecond part of an AbstractCFDateTime as an Int64.

source

Query Functions

Dates.daysinmonth — Function
monthlength = daysinmonth(::Type{DT},y,m)

Returns the number of days in a month for the year y and the month m according to the calendar given by the type DT.

Example

julia> daysinmonth(DateTimeAllLeap,2001,2)
+29
source
monthlength = daysinmonth(t)

Returns the number of days in a month containing the date t

Example

julia> daysinmonth(DateTimeAllLeap(2001,2,1))
+29
source
Dates.daysinyear — Function
yearlength = daysinyear(::Type{DT},y)

Returns the number of days in a year for the year y according to the calendar given by the type DT.

Example

julia> daysinyear(DateTimeAllLeap,2001,2)
+366
source
yearlength = daysinyear(t)

Returns the number of days in a year containing the date t

Example

julia> daysinyear(DateTimeAllLeap(2001,2,1))
+366
source
Dates.yearmonthday — Function
yearmonthday(dt::AbstractCFDateTime) -> (Int64, Int64, Int64)

Simultaneously return the year, month and day parts of dt.

source
Dates.yearmonth — Function
yearmonth(dt::AbstractCFDateTime) -> (Int64, Int64)

Simultaneously return the year and month parts of dt.

source
Dates.monthday — Function
monthday(dt::AbstractCFDateTime) -> (Int64, Int64)

Simultaneously return the month and day parts of dt.

source
Dates.firstdayofyear — Function
firstdayofyear(dt::AbstractCFDateTime) -> Int

Return the first day of the year including the date dt

source
Dates.dayofyear — Function
dayofyear(dt::AbstractCFDateTime) -> Int

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

source

Convertion Functions

Base.convert — Function
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
dt2 = convert(::Type{T}, dt)

Convert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.

Conversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.

For dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.

source
Base.reinterpret — Function
dt2 = reinterpret(::Type{T}, dt)

Convert a variable dt of type DateTime, DateTimeStandard, DateTimeJulian, DateTimeProlepticGregorian, DateTimeAllLeap, DateTimeNoLeap or DateTime360Day into the date time type T using the same values for year, month, day, minute, second and millisecond. The conversion might fail if a particular date does not exist in the target calendar.

source

Arithmetic

Adding and subtracting time periods is supported:

DateTimeStandard(1582,10,4) + Dates.Day(1)
 # returns DateTimeStandard(1582-10-15T00:00:00)

1582-10-15 is the adoption of the Gregorian Calendar.

Comparision operator can be used to check if a date is before or after another date.

DateTimeStandard(2000,01,01) < DateTimeStandard(2000,01,02)
 # returns true

Time ranges can be constructed using a start date, end date and a time increment, for example: DateTimeStandard(2000,1,1):Dates.Day(1):DateTimeStandard(2000,12,31)

Rounding

using CFTime: DateTimeStandard
 
@@ -66,4 +65,4 @@
 @btime difference_numbers($v0,$v1)
 
 # output (minimum of 5 @btime trails)
-# 1.683 ns (0 allocations: 0 bytes)

The information in this section and any other information marked as internal or experimental is not part of the public API and not covered by the semantic versioning. Future version of CFTime might add or changing the meaning of type parameters as patch-level changes. However removing a type parameter would be considered as a breaking change.

+# 1.683 ns (0 allocations: 0 bytes)

The information in this section and any other information marked as internal or experimental is not part of the public API and not covered by the semantic versioning. Future version of CFTime might add or changing the meaning of type parameters as patch-level changes. However removing a type parameter would be considered as a breaking change.

diff --git a/dev/search_index.js b/dev/search_index.js index 0da9cd7..02651fe 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"#CFTime.jl","page":"CFTime.jl","title":"CFTime.jl","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"This package implements the calendar types from the CF convention, namely:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Mixed Gregorian/Julian calendar (DateTimeStandard)\nProleptic gregorian calendar (DateTimeProlepticGregorian)\nGregorian calendar without leap years (all years are 365 days long) (DateTimeNoLeap)\nGregorian calendar with only leap year (all years are 366 days long) (DateTimeAllLeap)\nA calendar with every year being 360 days long (divided into 30 day months) (DateTime360Day)\nJulian calendar (DateTimeJulian)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Note that time zones are not supported by CFTime.jl.","category":"page"},{"location":"#Installation","page":"CFTime.jl","title":"Installation","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Inside the Julia shell, you can download and install the package by issuing:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using Pkg\nPkg.add(\"CFTime\")","category":"page"},{"location":"#Latest-development-version","page":"CFTime.jl","title":"Latest development version","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"If you want to try the latest development version, you can do this with the following commands:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using Pkg\nPkg.add(PackageSpec(url=\"https://github.com/JuliaGeo/CFTime.jl\", rev=\"master\"))\nPkg.build(\"CFTime\")","category":"page"},{"location":"#Types","page":"CFTime.jl","title":"Types","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard\nDateTimeJulian\nDateTimeProlepticGregorian\nDateTimeAllLeap\nDateTimeNoLeap\nDateTime360Day","category":"page"},{"location":"#CFTime.DateTimeStandard","page":"CFTime.jl","title":"CFTime.DateTimeStandard","text":"DateTimeStandard([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeStandard\n\nConstruct a DateTimeStandard type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeStandard is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"standard\".\n\n\n\n\n\nDateTimeStandard(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeStandard\n\nConstruct a DateTimeStandard by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeJulian","page":"CFTime.jl","title":"CFTime.DateTimeJulian","text":"DateTimeJulian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeJulian\n\nConstruct a DateTimeJulian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeJulian is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"julian\".\n\n\n\n\n\nDateTimeJulian(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeJulian\n\nConstruct a DateTimeJulian by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeProlepticGregorian","page":"CFTime.jl","title":"CFTime.DateTimeProlepticGregorian","text":"DateTimeProlepticGregorian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeProlepticGregorian\n\nConstruct a DateTimeProlepticGregorian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeProlepticGregorian is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"prolepticgregorian\".\n\n\n\n\n\nDateTimeProlepticGregorian(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeProlepticGregorian\n\nConstruct a DateTimeProlepticGregorian by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeAllLeap","page":"CFTime.jl","title":"CFTime.DateTimeAllLeap","text":"DateTimeAllLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeAllLeap\n\nConstruct a DateTimeAllLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeAllLeap is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"allleap\".\n\n\n\n\n\nDateTimeAllLeap(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeAllLeap\n\nConstruct a DateTimeAllLeap by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeNoLeap","page":"CFTime.jl","title":"CFTime.DateTimeNoLeap","text":"DateTimeNoLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeNoLeap\n\nConstruct a DateTimeNoLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeNoLeap is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"noleap\".\n\n\n\n\n\nDateTimeNoLeap(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeNoLeap\n\nConstruct a DateTimeNoLeap by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTime360Day","page":"CFTime.jl","title":"CFTime.DateTime360Day","text":"DateTime360Day([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTime360Day\n\nConstruct a DateTime360Day type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTime360Day is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"360day\".\n\n\n\n\n\nDateTime360Day(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime360Day\n\nConstruct a DateTime360Day by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#Time-encoding-and-decoding","page":"CFTime.jl","title":"Time encoding and decoding","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"CFTime.timedecode\nCFTime.timeencode","category":"page"},{"location":"#CFTime.timedecode","page":"CFTime.jl","title":"CFTime.timedecode","text":"dt = timedecode(data,units,calendar = \"standard\"; prefer_datetime = true)\n\nDecode the time information in data as given by the units units according to the specified calendar. Valid values for calendar are \"standard\", \"gregorian\", \"proleptic_gregorian\", \"julian\", \"noleap\", \"365_day\", \"all_leap\", \"366_day\" and \"360_day\".\n\nIf prefer_datetime is true (default), dates are converted to the DateTime type (for the calendars \"standard\", \"gregorian\", \"proleptic_gregorian\" and \"julian\") unless the time unit is expressed in microseconds or smaller. Such conversion is not possible for the other calendars.\n\nCalendar Type (prefer_datetime=true) Type (prefer_datetime=false)\nstandard, gregorian DateTime DateTimeStandard\nproleptic_gregorian DateTime DateTimeProlepticGregorian\njulian DateTime DateTimeJulian\nnoleap, 365_day DateTimeNoLeap DateTimeNoLeap\nall_leap, 366_day DateTimeAllLeap DateTimeAllLeap\n360_day DateTime360Day DateTime360Day\n\nExample:\n\nusing CFTime, Dates\n# standard calendar\ndt = CFTime.timedecode([0,1,2,3],\"days since 2000-01-01 00:00:00\")\n# 4-element Array{Dates.DateTime,1}:\n# 2000-01-01T00:00:00\n# 2000-01-02T00:00:00\n# 2000-01-03T00:00:00\n# 2000-01-04T00:00:00\n\ndt = CFTime.timedecode([0,1,2,3],\"days since 2000-01-01 00:00:00\",\"360_day\")\n# 4-element Array{DateTime360Day,1}:\n# DateTime360Day(2000-01-01T00:00:00)\n# DateTime360Day(2000-01-02T00:00:00)\n# DateTime360Day(2000-01-03T00:00:00)\n# DateTime360Day(2000-01-04T00:00:00)\n\n\n\n\n\n","category":"function"},{"location":"#CFTime.timeencode","page":"CFTime.jl","title":"CFTime.timeencode","text":"data = timeencode(dt,units,calendar = \"standard\")\n\nConvert a vector or array of DateTime (or DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian, DateTimeNoLeap, DateTimeAllLeap, DateTime360Day) according to the specified units (e.g. \"days since 2000-01-01 00:00:00\") using the calendar calendar. Valid values for calendar are: \"standard\", \"gregorian\", \"proleptic_gregorian\", \"julian\", \"noleap\", \"365_day\", \"all_leap\", \"366_day\", \"360_day\".\n\n\n\n\n\n","category":"function"},{"location":"#Accessor-Functions","page":"CFTime.jl","title":"Accessor Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"CFTime.year(dt::AbstractCFDateTime)\nCFTime.month(dt::AbstractCFDateTime)\nCFTime.day(dt::AbstractCFDateTime)\nCFTime.hour(dt::AbstractCFDateTime)\nCFTime.minute(dt::AbstractCFDateTime)\nCFTime.second(dt::AbstractCFDateTime)\nCFTime.millisecond(dt::AbstractCFDateTime)\nCFTime.microsecond(dt::AbstractCFDateTime)\nCFTime.nanosecond(dt::AbstractCFDateTime)\nCFTime.picosecond(dt::AbstractCFDateTime)\nCFTime.femtosecond(dt::AbstractCFDateTime)\nCFTime.attosecond(dt::AbstractCFDateTime)","category":"page"},{"location":"#Dates.year-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.year","text":"Dates.year(dt::AbstractCFDateTime) -> Int64\n\nExtract the year part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.month-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.month","text":"Dates.month(dt::AbstractCFDateTime) -> Int64\n\nExtract the month part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.day-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.day","text":"Dates.day(dt::AbstractCFDateTime) -> Int64\n\nExtract the day part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.hour-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.hour","text":"Dates.hour(dt::AbstractCFDateTime) -> Int64\n\nExtract the hour part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.minute-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.minute","text":"Dates.minute(dt::AbstractCFDateTime) -> Int64\n\nExtract the minute part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.second-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.second","text":"Dates.second(dt::AbstractCFDateTime) -> Int64\n\nExtract the second part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.millisecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.millisecond","text":"Dates.millisecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the millisecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.microsecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.microsecond","text":"Dates.microsecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the microsecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.nanosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.nanosecond","text":"Dates.nanosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the nanosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.picosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.picosecond","text":"CFTime.picosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the picosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.femtosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.femtosecond","text":"CFTime.femtosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the femtosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.attosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.attosecond","text":"CFTime.attosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the attosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Query-Functions","page":"CFTime.jl","title":"Query Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"daysinmonth\ndaysinyear\nyearmonthday\nyearmonth\nmonthday\nfirstdayofyear\ndayofyear","category":"page"},{"location":"#Dates.daysinmonth","page":"CFTime.jl","title":"Dates.daysinmonth","text":"monthlength = daysinmonth(::Type{DT},y,m)\n\nReturns the number of days in a month for the year y and the month m according to the calendar given by the type DT.\n\nExample\n\njulia> daysinmonth(DateTimeAllLeap,2001,2)\n29\n\n\n\n\n\nmonthlength = daysinmonth(t)\n\nReturns the number of days in a month containing the date t\n\nExample\n\njulia> daysinmonth(DateTimeAllLeap(2001,2,1))\n29\n\n\n\n\n\n","category":"function"},{"location":"#Dates.daysinyear","page":"CFTime.jl","title":"Dates.daysinyear","text":"yearlength = daysinyear(::Type{DT},y)\n\nReturns the number of days in a year for the year y according to the calendar given by the type DT.\n\nExample\n\njulia> daysinyear(DateTimeAllLeap,2001,2)\n366\n\n\n\n\n\nyearlength = daysinyear(t)\n\nReturns the number of days in a year containing the date t\n\nExample\n\njulia> daysinyear(DateTimeAllLeap(2001,2,1))\n366\n\n\n\n\n\n","category":"function"},{"location":"#Dates.yearmonthday","page":"CFTime.jl","title":"Dates.yearmonthday","text":"yearmonthday(dt::AbstractCFDateTime) -> (Int64, Int64, Int64)\n\nSimultaneously return the year, month and day parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.yearmonth","page":"CFTime.jl","title":"Dates.yearmonth","text":"yearmonth(dt::AbstractCFDateTime) -> (Int64, Int64)\n\nSimultaneously return the year and month parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.monthday","page":"CFTime.jl","title":"Dates.monthday","text":"monthday(dt::AbstractCFDateTime) -> (Int64, Int64)\n\nSimultaneously return the month and day parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.firstdayofyear","page":"CFTime.jl","title":"Dates.firstdayofyear","text":"firstdayofyear(dt::AbstractCFDateTime) -> Int\n\nReturn the first day of the year including the date dt\n\n\n\n\n\n","category":"function"},{"location":"#Dates.dayofyear","page":"CFTime.jl","title":"Dates.dayofyear","text":"dayofyear(dt::AbstractCFDateTime) -> Int\n\nReturn the day of the year for dt with January 1st being day 1.\n\n\n\n\n\n","category":"function"},{"location":"#Convertion-Functions","page":"CFTime.jl","title":"Convertion Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"convert\nreinterpret","category":"page"},{"location":"#Base.convert","page":"CFTime.jl","title":"Base.convert","text":"dt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\ndt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\ndt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\n","category":"function"},{"location":"#Base.reinterpret","page":"CFTime.jl","title":"Base.reinterpret","text":"dt2 = reinterpret(::Type{T}, dt)\n\nConvert a variable dt of type DateTime, DateTimeStandard, DateTimeJulian, DateTimeProlepticGregorian, DateTimeAllLeap, DateTimeNoLeap or DateTime360Day into the date time type T using the same values for year, month, day, minute, second and millisecond. The conversion might fail if a particular date does not exist in the target calendar.\n\n\n\n\n\n","category":"function"},{"location":"#Arithmetic","page":"CFTime.jl","title":"Arithmetic","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Adding and subtracting time periods is supported:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard(1582,10,4) + Dates.Day(1)\n# returns DateTimeStandard(1582-10-15T00:00:00)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"1582-10-15 is the adoption of the Gregorian Calendar.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Comparision operator can be used to check if a date is before or after another date.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard(2000,01,01) < DateTimeStandard(2000,01,02)\n# returns true","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Time ranges can be constructed using a start date, end date and a time increment, for example: DateTimeStandard(2000,1,1):Dates.Day(1):DateTimeStandard(2000,12,31)","category":"page"},{"location":"#Rounding","page":"CFTime.jl","title":"Rounding","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using CFTime: DateTimeStandard\n\ndt = DateTimeStandard(24*60*60,\"second since 2000-01-01\")\n\nfloor(dt+Second(9),Second(10)) == dt\n# output\n\ntrue\n\nceil(dt+Second(9),Second(10)) == dt + Second(10)\n# output\n\ntrue\n\nround(dt+Second(9),Second(10)) == dt + Second(10)\n# output\n\ntrue","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Julia's DateTime records the time relative to a time orgin (January 1st, 1 BC or 0000-01-01 in ISO_8601) with a millisecond accuracy. Converting CFTime date time structures to Julia's DateTime (using convert(DateTime,dt)) can trigger an inexact exception if the convertion cannot be done without loss of precision. One can use the round function in order to round to the nearest time represenatable by DateTime:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using CFTime: DateTimeStandard\nusing Dates: DateTime\ndt = DateTimeStandard(24*60*60*1000*1000 + 123,\"microsecond since 2000-01-01\")\nround(DateTime,dt)\n# output\n\n2000-01-02T00:00:00","category":"page"},{"location":"#Internal-API","page":"CFTime.jl","title":"Internal API","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"For CFTime 0.1.3 and before all date-times are encoded using internally milliseconds since a fixed time origin and stored as an Int64 similar to julia's Dates.DateTime. However, this approach does not allow to encode time with a sub-millisecond precision allowed by the CF convention and supported by e.g. numpy. While numpy allows attosecond precision, it can only encode a time span of ±9.2 around the date 00:00:00 UTC on 1 January 1970. In CFTime the time origin and the number containing the duration and the time precision are now encoded as two additional type parameters.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"When wrapping a CFTime date-time type, it is recommended for performance reasons to make the containg structure also parametric, for example","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"struct MyStuct{T1,T2}\n dt::DateTimeStandard{T1,T2}\nend","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Future version of CFTime might add other type parameters. Internally, T1 corresponds to a CFTime.Period{T,Tfactor,Texponent} structure wrapping a number type T representing the duration expressed in seconds as:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"duration * factor * 10^exponent","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"where Tfactor and Texponent are value types of factor and exponent respectively. T2 is a value type of the date origin tuple represented as (year, month, day,...).","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"For example, duration 3600000 milliseconds is represented as duration = 3600000, Tfactor = Val(1), Texponent = Val(-3), as","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"3600000 milliseconds = 3600000 * 1 * 10⁻³ seconds","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"or the durtion 1 hours is duration = 1, Tfactor = Val(3600) and Texponent = Val(0) since:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"1 hour = 3600 * 1 * 10⁰ seconds","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"There is no normalization of the time duration per default as it could lead to under-/overflow.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"The type parameter T2 of DateTimeStandard encodes the time origin as a tuple of integers starting with the year (year,month,day,hour,minute,seconds,milliseconds,microseconds,...). Only the year, month and day need specified; all other default to zero. For example T2 would be Val((1970,1,1)) if the time origin is the 1st January 1970).","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"By using value types as type parametes, the time origin, time resolution... are known to the compiler. For example computing the difference between between two date time expressed in as the same time origin and units as a si","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using BenchmarkTools\nusing Dates\n\ndt0 = DateTimeStandard(1,\"days since 2000-01-01\")\ndt1 = DateTimeStandard(1000,\"days since 2000-01-01\")\n\ndifference_datetime(dt0,dt1) = Dates.Millisecond(dt1 - dt0).value\n@btime difference_datetime($dt0,$dt1)\n\n# output (minimum of 5 @btime trails)\n# 1.689 ns (0 allocations: 0 bytes)\n\nv0 = 1\nv1 = 1000\n\ndifference_numbers(v0,v1) = (v1-v0)*(86_400_000)\n@btime difference_numbers($v0,$v1)\n\n# output (minimum of 5 @btime trails)\n# 1.683 ns (0 allocations: 0 bytes)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"The information in this section and any other information marked as internal or experimental is not part of the public API and not covered by the semantic versioning. Future version of CFTime might add or changing the meaning of type parameters as patch-level changes. However removing a type parameter would be considered as a breaking change.","category":"page"}] +[{"location":"#CFTime.jl","page":"CFTime.jl","title":"CFTime.jl","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"This package implements the calendar types from the CF convention, namely:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Mixed Gregorian/Julian calendar (DateTimeStandard)\nProleptic gregorian calendar (DateTimeProlepticGregorian)\nGregorian calendar without leap years (all years are 365 days long) (DateTimeNoLeap)\nGregorian calendar with only leap year (all years are 366 days long) (DateTimeAllLeap)\nA calendar with every year being 360 days long (divided into 30 day months) (DateTime360Day)\nJulian calendar (DateTimeJulian)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Note that time zones are not supported by CFTime.jl.","category":"page"},{"location":"#Installation","page":"CFTime.jl","title":"Installation","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Inside the Julia shell, you can download and install the package by issuing:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using Pkg\nPkg.add(\"CFTime\")","category":"page"},{"location":"#Latest-development-version","page":"CFTime.jl","title":"Latest development version","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"If you want to try the latest development version, you can do this with the following commands:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using Pkg\nPkg.add(PackageSpec(url=\"https://github.com/JuliaGeo/CFTime.jl\", rev=\"master\"))","category":"page"},{"location":"#Types","page":"CFTime.jl","title":"Types","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard\nDateTimeJulian\nDateTimeProlepticGregorian\nDateTimeAllLeap\nDateTimeNoLeap\nDateTime360Day","category":"page"},{"location":"#CFTime.DateTimeStandard","page":"CFTime.jl","title":"CFTime.DateTimeStandard","text":"DateTimeStandard([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeStandard\n\nConstruct a DateTimeStandard type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeStandard is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"standard\".\n\n\n\n\n\nDateTimeStandard(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeStandard\n\nConstruct a DateTimeStandard by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeJulian","page":"CFTime.jl","title":"CFTime.DateTimeJulian","text":"DateTimeJulian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeJulian\n\nConstruct a DateTimeJulian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeJulian is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"julian\".\n\n\n\n\n\nDateTimeJulian(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeJulian\n\nConstruct a DateTimeJulian by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeProlepticGregorian","page":"CFTime.jl","title":"CFTime.DateTimeProlepticGregorian","text":"DateTimeProlepticGregorian([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeProlepticGregorian\n\nConstruct a DateTimeProlepticGregorian type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeProlepticGregorian is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"prolepticgregorian\".\n\n\n\n\n\nDateTimeProlepticGregorian(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeProlepticGregorian\n\nConstruct a DateTimeProlepticGregorian by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeAllLeap","page":"CFTime.jl","title":"CFTime.DateTimeAllLeap","text":"DateTimeAllLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeAllLeap\n\nConstruct a DateTimeAllLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeAllLeap is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"allleap\".\n\n\n\n\n\nDateTimeAllLeap(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeAllLeap\n\nConstruct a DateTimeAllLeap by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTimeNoLeap","page":"CFTime.jl","title":"CFTime.DateTimeNoLeap","text":"DateTimeNoLeap([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTimeNoLeap\n\nConstruct a DateTimeNoLeap type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTimeNoLeap is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"noleap\".\n\n\n\n\n\nDateTimeNoLeap(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTimeNoLeap\n\nConstruct a DateTimeNoLeap by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#CFTime.DateTime360Day","page":"CFTime.jl","title":"CFTime.DateTime360Day","text":"DateTime360Day([Ti::DataType], y, [m, d, h, mi, s, ms]) -> DateTime360Day\n\nConstruct a DateTime360Day type by year (y), month (m, default 1), day (d, default 1), hour (h, default 0), minute (mi, default 0), second (s, default 0), millisecond (ms, default 0). All arguments must be convertible to Int64. DateTime360Day is a subtype of AbstractCFDateTime.\n\nThe netCDF CF calendars are defined in the CF Standard. This type implements the calendar defined as \"360day\".\n\n\n\n\n\nDateTime360Day(dt::AbstractString, format::AbstractString; locale=\"english\") -> DateTime360Day\n\nConstruct a DateTime360Day by parsing the dt date time string following the pattern given in the format string.\n\nnote: Note\nThis function is experimental and might be removed in the future. It relies on some internal function of Dates for parsing the format.\n\n\n\n\n\n","category":"type"},{"location":"#Time-encoding-and-decoding","page":"CFTime.jl","title":"Time encoding and decoding","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"CFTime.timedecode\nCFTime.timeencode","category":"page"},{"location":"#CFTime.timedecode","page":"CFTime.jl","title":"CFTime.timedecode","text":"dt = timedecode(data,units,calendar = \"standard\"; prefer_datetime = true)\n\nDecode the time information in data as given by the units units according to the specified calendar. Valid values for calendar are \"standard\", \"gregorian\", \"proleptic_gregorian\", \"julian\", \"noleap\", \"365_day\", \"all_leap\", \"366_day\" and \"360_day\".\n\nIf prefer_datetime is true (default), dates are converted to the DateTime type (for the calendars \"standard\", \"gregorian\", \"proleptic_gregorian\" and \"julian\") unless the time unit is expressed in microseconds or smaller. Such conversion is not possible for the other calendars.\n\nCalendar Type (prefer_datetime=true) Type (prefer_datetime=false)\nstandard, gregorian DateTime DateTimeStandard\nproleptic_gregorian DateTime DateTimeProlepticGregorian\njulian DateTime DateTimeJulian\nnoleap, 365_day DateTimeNoLeap DateTimeNoLeap\nall_leap, 366_day DateTimeAllLeap DateTimeAllLeap\n360_day DateTime360Day DateTime360Day\n\nExample:\n\nusing CFTime, Dates\n# standard calendar\ndt = CFTime.timedecode([0,1,2,3],\"days since 2000-01-01 00:00:00\")\n# 4-element Array{Dates.DateTime,1}:\n# 2000-01-01T00:00:00\n# 2000-01-02T00:00:00\n# 2000-01-03T00:00:00\n# 2000-01-04T00:00:00\n\ndt = CFTime.timedecode([0,1,2,3],\"days since 2000-01-01 00:00:00\",\"360_day\")\n# 4-element Array{DateTime360Day,1}:\n# DateTime360Day(2000-01-01T00:00:00)\n# DateTime360Day(2000-01-02T00:00:00)\n# DateTime360Day(2000-01-03T00:00:00)\n# DateTime360Day(2000-01-04T00:00:00)\n\n\n\n\n\n","category":"function"},{"location":"#CFTime.timeencode","page":"CFTime.jl","title":"CFTime.timeencode","text":"data = timeencode(dt,units,calendar = \"standard\")\n\nConvert a vector or array of DateTime (or DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian, DateTimeNoLeap, DateTimeAllLeap, DateTime360Day) according to the specified units (e.g. \"days since 2000-01-01 00:00:00\") using the calendar calendar. Valid values for calendar are: \"standard\", \"gregorian\", \"proleptic_gregorian\", \"julian\", \"noleap\", \"365_day\", \"all_leap\", \"366_day\", \"360_day\".\n\n\n\n\n\n","category":"function"},{"location":"#Accessor-Functions","page":"CFTime.jl","title":"Accessor Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"CFTime.year(dt::AbstractCFDateTime)\nCFTime.month(dt::AbstractCFDateTime)\nCFTime.day(dt::AbstractCFDateTime)\nCFTime.hour(dt::AbstractCFDateTime)\nCFTime.minute(dt::AbstractCFDateTime)\nCFTime.second(dt::AbstractCFDateTime)\nCFTime.millisecond(dt::AbstractCFDateTime)\nCFTime.microsecond(dt::AbstractCFDateTime)\nCFTime.nanosecond(dt::AbstractCFDateTime)\nCFTime.picosecond(dt::AbstractCFDateTime)\nCFTime.femtosecond(dt::AbstractCFDateTime)\nCFTime.attosecond(dt::AbstractCFDateTime)","category":"page"},{"location":"#Dates.year-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.year","text":"Dates.year(dt::AbstractCFDateTime) -> Int64\n\nExtract the year part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.month-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.month","text":"Dates.month(dt::AbstractCFDateTime) -> Int64\n\nExtract the month part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.day-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.day","text":"Dates.day(dt::AbstractCFDateTime) -> Int64\n\nExtract the day part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.hour-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.hour","text":"Dates.hour(dt::AbstractCFDateTime) -> Int64\n\nExtract the hour part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.minute-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.minute","text":"Dates.minute(dt::AbstractCFDateTime) -> Int64\n\nExtract the minute part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.second-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.second","text":"Dates.second(dt::AbstractCFDateTime) -> Int64\n\nExtract the second part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.millisecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.millisecond","text":"Dates.millisecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the millisecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.microsecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.microsecond","text":"Dates.microsecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the microsecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Dates.nanosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"Dates.nanosecond","text":"Dates.nanosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the nanosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.picosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.picosecond","text":"CFTime.picosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the picosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.femtosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.femtosecond","text":"CFTime.femtosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the femtosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#CFTime.attosecond-Tuple{AbstractCFDateTime}","page":"CFTime.jl","title":"CFTime.attosecond","text":"CFTime.attosecond(dt::AbstractCFDateTime) -> Int64\n\nExtract the attosecond part of an AbstractCFDateTime as an Int64.\n\n\n\n\n\n","category":"method"},{"location":"#Query-Functions","page":"CFTime.jl","title":"Query Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"daysinmonth\ndaysinyear\nyearmonthday\nyearmonth\nmonthday\nfirstdayofyear\ndayofyear","category":"page"},{"location":"#Dates.daysinmonth","page":"CFTime.jl","title":"Dates.daysinmonth","text":"monthlength = daysinmonth(::Type{DT},y,m)\n\nReturns the number of days in a month for the year y and the month m according to the calendar given by the type DT.\n\nExample\n\njulia> daysinmonth(DateTimeAllLeap,2001,2)\n29\n\n\n\n\n\nmonthlength = daysinmonth(t)\n\nReturns the number of days in a month containing the date t\n\nExample\n\njulia> daysinmonth(DateTimeAllLeap(2001,2,1))\n29\n\n\n\n\n\n","category":"function"},{"location":"#Dates.daysinyear","page":"CFTime.jl","title":"Dates.daysinyear","text":"yearlength = daysinyear(::Type{DT},y)\n\nReturns the number of days in a year for the year y according to the calendar given by the type DT.\n\nExample\n\njulia> daysinyear(DateTimeAllLeap,2001,2)\n366\n\n\n\n\n\nyearlength = daysinyear(t)\n\nReturns the number of days in a year containing the date t\n\nExample\n\njulia> daysinyear(DateTimeAllLeap(2001,2,1))\n366\n\n\n\n\n\n","category":"function"},{"location":"#Dates.yearmonthday","page":"CFTime.jl","title":"Dates.yearmonthday","text":"yearmonthday(dt::AbstractCFDateTime) -> (Int64, Int64, Int64)\n\nSimultaneously return the year, month and day parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.yearmonth","page":"CFTime.jl","title":"Dates.yearmonth","text":"yearmonth(dt::AbstractCFDateTime) -> (Int64, Int64)\n\nSimultaneously return the year and month parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.monthday","page":"CFTime.jl","title":"Dates.monthday","text":"monthday(dt::AbstractCFDateTime) -> (Int64, Int64)\n\nSimultaneously return the month and day parts of dt.\n\n\n\n\n\n","category":"function"},{"location":"#Dates.firstdayofyear","page":"CFTime.jl","title":"Dates.firstdayofyear","text":"firstdayofyear(dt::AbstractCFDateTime) -> Int\n\nReturn the first day of the year including the date dt\n\n\n\n\n\n","category":"function"},{"location":"#Dates.dayofyear","page":"CFTime.jl","title":"Dates.dayofyear","text":"dayofyear(dt::AbstractCFDateTime) -> Int\n\nReturn the day of the year for dt with January 1st being day 1.\n\n\n\n\n\n","category":"function"},{"location":"#Convertion-Functions","page":"CFTime.jl","title":"Convertion Functions","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"convert\nreinterpret","category":"page"},{"location":"#Base.convert","page":"CFTime.jl","title":"Base.convert","text":"dt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\ndt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\ndt2 = convert(::Type{T}, dt)\n\nConvert a DateTime of type DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime into the type T which can also be either DateTimeStandard, DateTimeProlepticGregorian, DateTimeJulian or DateTime.\n\nConversion is done such that duration (difference of DateTime types) are preserved. For dates on and after 1582-10-15, the year, month and days are the same for the types DateTimeStandard, DateTimeProlepticGregorian and DateTime.\n\nFor dates before 1582-10-15, the year, month and days are the same for the types DateTimeStandard and DateTimeJulian.\n\n\n\n\n\n","category":"function"},{"location":"#Base.reinterpret","page":"CFTime.jl","title":"Base.reinterpret","text":"dt2 = reinterpret(::Type{T}, dt)\n\nConvert a variable dt of type DateTime, DateTimeStandard, DateTimeJulian, DateTimeProlepticGregorian, DateTimeAllLeap, DateTimeNoLeap or DateTime360Day into the date time type T using the same values for year, month, day, minute, second and millisecond. The conversion might fail if a particular date does not exist in the target calendar.\n\n\n\n\n\n","category":"function"},{"location":"#Arithmetic","page":"CFTime.jl","title":"Arithmetic","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Adding and subtracting time periods is supported:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard(1582,10,4) + Dates.Day(1)\n# returns DateTimeStandard(1582-10-15T00:00:00)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"1582-10-15 is the adoption of the Gregorian Calendar.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Comparision operator can be used to check if a date is before or after another date.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"DateTimeStandard(2000,01,01) < DateTimeStandard(2000,01,02)\n# returns true","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Time ranges can be constructed using a start date, end date and a time increment, for example: DateTimeStandard(2000,1,1):Dates.Day(1):DateTimeStandard(2000,12,31)","category":"page"},{"location":"#Rounding","page":"CFTime.jl","title":"Rounding","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using CFTime: DateTimeStandard\n\ndt = DateTimeStandard(24*60*60,\"second since 2000-01-01\")\n\nfloor(dt+Second(9),Second(10)) == dt\n# output\n\ntrue\n\nceil(dt+Second(9),Second(10)) == dt + Second(10)\n# output\n\ntrue\n\nround(dt+Second(9),Second(10)) == dt + Second(10)\n# output\n\ntrue","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Julia's DateTime records the time relative to a time orgin (January 1st, 1 BC or 0000-01-01 in ISO_8601) with a millisecond accuracy. Converting CFTime date time structures to Julia's DateTime (using convert(DateTime,dt)) can trigger an inexact exception if the convertion cannot be done without loss of precision. One can use the round function in order to round to the nearest time represenatable by DateTime:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using CFTime: DateTimeStandard\nusing Dates: DateTime\ndt = DateTimeStandard(24*60*60*1000*1000 + 123,\"microsecond since 2000-01-01\")\nround(DateTime,dt)\n# output\n\n2000-01-02T00:00:00","category":"page"},{"location":"#Internal-API","page":"CFTime.jl","title":"Internal API","text":"","category":"section"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"For CFTime 0.1.3 and before all date-times are encoded using internally milliseconds since a fixed time origin and stored as an Int64 similar to julia's Dates.DateTime. However, this approach does not allow to encode time with a sub-millisecond precision allowed by the CF convention and supported by e.g. numpy. While numpy allows attosecond precision, it can only encode a time span of ±9.2 around the date 00:00:00 UTC on 1 January 1970. In CFTime the time origin and the number containing the duration and the time precision are now encoded as two additional type parameters.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"When wrapping a CFTime date-time type, it is recommended for performance reasons to make the containg structure also parametric, for example","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"struct MyStuct{T1,T2}\n dt::DateTimeStandard{T1,T2}\nend","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"Future version of CFTime might add other type parameters. Internally, T1 corresponds to a CFTime.Period{T,Tfactor,Texponent} structure wrapping a number type T representing the duration expressed in seconds as:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"duration * factor * 10^exponent","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"where Tfactor and Texponent are value types of factor and exponent respectively. T2 is a value type of the date origin tuple represented as (year, month, day,...).","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"For example, duration 3600000 milliseconds is represented as duration = 3600000, Tfactor = Val(1), Texponent = Val(-3), as","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"3600000 milliseconds = 3600000 * 1 * 10⁻³ seconds","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"or the durtion 1 hours is duration = 1, Tfactor = Val(3600) and Texponent = Val(0) since:","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"1 hour = 3600 * 1 * 10⁰ seconds","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"There is no normalization of the time duration per default as it could lead to under-/overflow.","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"The type parameter T2 of DateTimeStandard encodes the time origin as a tuple of integers starting with the year (year,month,day,hour,minute,seconds,milliseconds,microseconds,...). Only the year, month and day need specified; all other default to zero. For example T2 would be Val((1970,1,1)) if the time origin is the 1st January 1970).","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"By using value types as type parametes, the time origin, time resolution... are known to the compiler. For example computing the difference between between two date time expressed in as the same time origin and units as a si","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"using BenchmarkTools\nusing Dates\n\ndt0 = DateTimeStandard(1,\"days since 2000-01-01\")\ndt1 = DateTimeStandard(1000,\"days since 2000-01-01\")\n\ndifference_datetime(dt0,dt1) = Dates.Millisecond(dt1 - dt0).value\n@btime difference_datetime($dt0,$dt1)\n\n# output (minimum of 5 @btime trails)\n# 1.689 ns (0 allocations: 0 bytes)\n\nv0 = 1\nv1 = 1000\n\ndifference_numbers(v0,v1) = (v1-v0)*(86_400_000)\n@btime difference_numbers($v0,$v1)\n\n# output (minimum of 5 @btime trails)\n# 1.683 ns (0 allocations: 0 bytes)","category":"page"},{"location":"","page":"CFTime.jl","title":"CFTime.jl","text":"The information in this section and any other information marked as internal or experimental is not part of the public API and not covered by the semantic versioning. Future version of CFTime might add or changing the meaning of type parameters as patch-level changes. However removing a type parameter would be considered as a breaking change.","category":"page"}] }