Dates

Dates モジュールは日時を扱うための型を二つ提供します: 日単位の精度を持つ Date と、ミリ秒単位の精度を持つ DateTime です。この二つの型は両方とも抽象型 TimeType の部分型です。型を区別する理由は簡単で、精度の細かい値を無視できるとコードが書きやすく、理解も簡単になるためです。例えば Date は最小単位を一日とする (時・分・秒は考えない) ことが最初から決まっているので、タイムゾーン・夏時間・うるう秒は問題とならず、実装せずに済みます。

Date と DateTime はどちらも基本的に Int64 のラッパーです。二つの型が持つ唯一のフィールド instant は実際には UTInstant{P} という型であり、この型は世界時秒 (UT second) に基づいて途切れることなく増加するマシンの時間軸を表します¹。DateTime 型はタイムゾーンを認識しないので、Python の用語で言えば "ナイーブ" であり、Java 8 の LocalDateTime と同様です。タイムゾーンに関する機能が必要な場合は、IANA タイムゾーンデータベースを内蔵した TimeZones.jl パッケージを利用してください。

Date と DateTime はどちらも先発グレゴリオ暦 (proleptic Gregorian calendar) に従う ISO 8601 規格に基づいています。ISO 8601 規格は紀元前 (BC/BCE) の扱いが特殊なので注意が必要です。通常の暦では紀元前の最後の日 1-12-31 の次の日は紀元 1-1-1 であり、ゼロ年は存在しません。しかし ISO 8601 規格は紀元前元年をゼロ年と規定しているので、0001-01-01 の前の日は 0000-12-31 となります。また -0001 年 (負の 1 に対応する年) は紀元前二年であり、-0002 年が紀元前三年となります。

コンストラクタ

Date 型と DateTime 型は整数または Period 型から構築できます。文字列のパースやアジャスターを使った構築も可能です (詳しくは後述)。

julia> DateTime(2013)
2013-01-01T00:00:00

julia> DateTime(2013,7)
2013-07-01T00:00:00

julia> DateTime(2013,7,1)
2013-07-01T00:00:00

julia> DateTime(2013,7,1,12)
2013-07-01T12:00:00

julia> DateTime(2013,7,1,12,30)
2013-07-01T12:30:00

julia> DateTime(2013,7,1,12,30,59)
2013-07-01T12:30:59

julia> DateTime(2013,7,1,12,30,59,1)
2013-07-01T12:30:59.001

julia> Date(2013)
2013-01-01

julia> Date(2013,7)
2013-07-01

julia> Date(2013,7,1)
2013-07-01

julia> Date(Dates.Year(2013),Dates.Month(7),Dates.Day(1))
2013-07-01

julia> Date(Dates.Month(7),Dates.Year(2013))
2013-07-01

Date と DateTime のパースはフォーマット文字列を使って実現されます。フォーマット文字列は時刻要素を示す "スロット" をいくつか定義することで構築され、スロットには区切られたスロットと固定幅のスロットの二つがあります。パースする文字列とフォーマット文字列を Date("2015-01-01","y-m-d") や DateTime("20150101","yyyymmdd") などとして Date や DateTime のコンストラクタに渡すとオブジェクトが構築されます。

区切られたスロットを定義するには、隣り合う二つの時刻要素の区切り文字としてパーサーが認識すべき文字を指定します。例えば "y-m-d" というフォーマット文字列を与えると、パーサーは処理対象の文字列 (例えば "2014-07-16") に含まれる一つ目のスロットと二つ目のスロットの間には - が見つかるはずだと理解します。y, m, d は各スロットがどの時刻要素に対応するかをパーサーに伝えます。

固定幅のスロットを定義するには、時刻要素を表す文字を対応する幅と同じ個数だけ続けて書きます。例えば "yyyymmdd" というフォーマット文字列は "20140716" のような時刻を表す文字列に対応します。パーサーは区切り文字が無いときに固定幅スロットを認識します。

テキスト形式の月のパースも u と U でサポートされます。デフォルトでは英語の月の名前だけがサポートされ、u は "Jan", "Feb", "Mar" といった省略形を、U は "January", "February", "March" といった完全な形を表します。DateTime が使うロケールを変更するには、Dates.LOCALES という Dict{String,Dates.DateLocale} 型の辞書にロケールを登録した上で関数のキーワード引数 locale にそのロケールを指定します²。整数を文字列に対応付ける dayname や monthname といった関数でも同様です。

パースのパフォーマンスについて: コンストラクタを何度か呼ぶだけであれば Date(date_string, "format_string") の形式を使っても問題ありません。しかし同じフォーマット文字列を使って何度もパースをするときは、生のフォーマット文字列ではなく事前に作成した Dates.DateFormat をコンストラクタに渡すことで効率が大きく向上します。例えば次のようにします:

julia> df = DateFormat("y-m-d");

julia> dt = Date("2015-01-01",df)
2015-01-01

julia> dt2 = Date("2015-01-02",df)
2015-01-02

フォーマット文字列の作成では文字列マクロ dateformat"..." も利用できます。このマクロは展開されるときに DateFormat オブジェクトを一度だけ生成するので、このマクロを含むコードが複数回実行されても構築の手間がかさむことはありません:

julia> for i = 1:10^5
           Date("2015-01-01", dateformat"y-m-d")
       end

フォーマット文字列のパースに関するテストと例は stdlib/Dates/test/io.jl にあります。

期間/比較

Date と DateTime は内部でそれぞれ UTInstant{Day} と UTInstant{Millisecond} で表現されるので、同じ型を持つ二つの値の間の長さは容易に計算できます。二つの Date 間の間隔は Day の個数であり、二つの DateTime の間の間隔は Millisecond の個数です。同様に、抽象型 TimeType の部分型に対する比較は内部のマシン時刻 (Int64) を比較するだけで行えます:

julia> dt = Date(2012,2,29)
2012-02-29

julia> dt2 = Date(2000,2,1)
2000-02-01

julia> dump(dt)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 734562

julia> dump(dt2)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 730151

julia> dt > dt2
true

julia> dt != dt2
true

julia> dt + dt2
ERROR: MethodError: no method matching +(::Date, ::Date)
[...]

julia> dt * dt2
ERROR: MethodError: no method matching *(::Date, ::Date)
[...]

julia> dt / dt2
ERROR: MethodError: no method matching /(::Date, ::Date)

julia> dt - dt2
4411 days

julia> dt2 - dt
-4411 days

julia> dt = DateTime(2012,2,29)
2012-02-29T00:00:00

julia> dt2 = DateTime(2000,2,1)
2000-02-01T00:00:00

julia> dt - dt2
381110400000 milliseconds

アクセッサ関数

Date 型と DateTime 型は単一の Int64 として格納されるので、日時 (フィールド) はアクセッサ関数を通して取得します。小文字のアクセッサはフィールドを整数として返します:

julia> t = Date(2014, 1, 31)
2014-01-31

julia> Dates.year(t)
2014

julia> Dates.month(t)
1

julia> Dates.week(t)
5

julia> Dates.day(t)
31

大文字のアクセッサは対応する Period 型を返します:

julia> Dates.Year(t)
2014 years

julia> Dates.Day(t)
31 days

いくつかのフィールドの取得を合成したメソッドも提供されます。複数のフィールドが一度に必要な場合はこちらを使うと効率が向上します:

julia> Dates.yearmonth(t)
(2014, 1)

julia> Dates.monthday(t)
(1, 31)

julia> Dates.yearmonthday(t)
(2014, 1, 31)

内部の UTInstant および整数値へのアクセスも可能です:

julia> dump(t)
Date
  instant: Dates.UTInstant{Day}
    periods: Day
      value: Int64 735264

julia> t.instant
Dates.UTInstant{Day}(Day(735264))

julia> Dates.value(t)
735264

クエリ関数

クエリ関数は TimeType 型の値のカレンダーに関する情報を提供します。例えば曜日に関する情報を取得できます:

julia> t = Date(2014, 1, 31)
2014-01-31

julia> Dates.dayofweek(t)
5

julia> Dates.dayname(t)
"Friday"

julia> Dates.dayofweekofmonth(t) # 2014 年 1 月 31 日は第五金曜日
5

月に関する情報も取得できます:

julia> Dates.monthname(t)
"January"

julia> Dates.daysinmonth(t)
31

TimeType 型の値の年や四半期に関する情報も取得可能です:

julia> Dates.isleapyear(t)
false

julia> Dates.dayofyear(t)
31

julia> Dates.quarterofyear(t)
1

julia> Dates.dayofquarter(t)
31

曜日や月の省略形を取得する関数 dayabbr, monthabbr もあります。

dayname や monthname に省略可能なキーワード引数 locale を渡すと、他の言語/ロケールにおける曜日と月の名前を使うことができます。ロケールを使うには、まず対応付けを変数 LOCALES に追加します:

julia> french_months = ["janvier", "février", "mars", "avril", "mai", "juin",
                        "juillet", "août", "septembre", "octobre", "novembre",
                        "décembre"];

julia> french_monts_abbrev = ["janv", "févr", "mars", "avril", "mai", "juin",
                              "juil", "août", "sept", "oct", "nov", "déc"];

julia> french_days = ["lundi", "mardi", "mercredi", "jeudi",
                      "vendredi", "samedi", "dimanche"];

julia> Dates.LOCALES["french"] =
           Dates.DateLocale(french_months, french_monts_abbrev, french_days, [""]);

こうすれば、上述の関数を使ってクエリを行えます:

julia> Dates.dayname(t;locale="french")
"vendredi"

julia> Dates.monthname(t;locale="french")
"janvier"

julia> Dates.monthabbr(t;locale="french")
"janv"

曜日の省略形は定義していないので、dayabbr で local を "french" とするとエラーになります:

julia> Dates.dayabbr(t;locale="french")
ERROR: BoundsError: attempt to access 1-element Array{String,1} at index [5]
Stacktrace:
[...]

TimeType と Period の算術

日時と期間の算術には注意を要する細かな点があるので、どんな言語や日時フレームワークを使うのであれ、この算術がどのように行われるのかを確認しておくべきです (ただ一日単位の精度を持つ型では扱いがずっと簡単になります)。

Julia の Dates モジュールは Period が絡む算術で「変更をなるべく小さくする」という単純な原則に従ったアプローチを採用します。これはカレンダー式算術 (calendrical arithmetic) と呼ばれる方法であり、普段の会話で行われる計算とだいたい同じです。

日付を使った計算の何がそんなに難しいのでしょうか？ 一つ簡単な例を考えましょう: 2014 年 1 月 31 日に一か月を足したとき、答えは？ JavaScript は 3 月 3 日 を答えます (つまり一か月を 31 日とした計算です)。また PHP によると3 月 2 日 です (一か月は 30 日とされます)。実を言えば、この問題に正しい答えはありません。Julia の Dates モジュールは 2 月 28 日を答えます。Dates がこの答えを計算する方法を説明するために、カジノにあるスロットマシンを考えます。

このスロットマシンには 1 から 9 の数字が三つ並ぶのではなく、年-月-日を表す三つの数字が並びます。上の例では 2014-01-31 です。この日付に一か月を足すときは、まず月の列を 1 進めて 2014-02-31 とします。そして日の値が新しい月の最後の日より大きくなっていないかどうかを判定します。もし (今考えている例のように) 大きくなっているなら、日を最後の正当な日 (28) に調整し、それを計算結果とします。

このやり方が予期しない結果を生むことはあるでしょうか？ さらに一か月を足してみてください: 2014-02-28 + Month(1) == 2014-03-28 です。三月の最後の日が得られるのが正しいのではないかと思ったなら、スロットマシンを思い出してください。変更される列の数はなるべく小さくなります。つまり月の列を一つ大きくした 2014-03-28 が正当な日付なので、計算はそこで終了します。一方で最初の日付 2014-01-31 に二か月を足すと、予想通り 2014-03-31 が計算されます。

このアプローチにはもう一つ分かりにくい振る舞いがあります。それは算術で特定の順序が強制されたときに連結性が無くなることです。例えば値を異なる順序で足すと結果が変わることがあります。例を示します:

julia> (Date(2014,1,29)+Dates.Day(1)) + Dates.Month(1)
2014-02-28

julia> (Date(2014,1,29)+Dates.Month(1)) + Dates.Day(1)
2014-03-01

何が起こっているのでしょうか？ 一つ目の例では 1 月 29 日に一日を足されて 2014-01-30 となり、それから一か月が足されて 2014-02-30 となり、これが調整されて 2014-02-28 となります。二つ目の例では一か月が最初に足されることで 2014-02-29 となり、これが 2014-02-28 に調整され、それから一日が足されて 2014-03-01 となります。この問題に対応するために用意されている設計が、算術に複数の Period が含まれる場合は、Period の位置ではなく型に基づいて演算が並べられるというものです。つまり Year は必ず最初に足され、それから Month, Week の順に足されます。そのため次の二つの式は結合性を持ち、"そのまま" 動作します。

julia> Date(2014,1,29) + Dates.Day(1) + Dates.Month(1)
2014-03-01

julia> Date(2014,1,29) + Dates.Month(1) + Dates.Day(1)
2014-03-01

扱いにくいでしょうか？ もしかしたらそうかもしれません。Dates を初めて使うユーザーが知っておく必要があるのは「月を扱うときに明示的に連結性を指定すると予期せぬ結果が生じる可能性がある」ことだけであり、それ以外は全て期待通りに動作します。幸いなことに、世界時を使った日時と期間の算術で生じる奇妙なケースはこれでほぼ全てです (うるう秒や夏時間といった "お楽しみ" はありません)。

この設計のボーナスとして、期間の算術で使えるオブジェクトは区間に対しても全てそのまま動作します:

julia> dr = Date(2014,1,29):Day(1):Date(2014,2,3)
Date("2014-01-29"):Day(1):Date("2014-02-03")

julia> collect(dr)
6-element Array{Date,1}:
 2014-01-29
 2014-01-30
 2014-01-31
 2014-02-01
 2014-02-02
 2014-02-03

julia> dr = Date(2014,1,29):Dates.Month(1):Date(2014,07,29)
Date("2014-01-29"):Month(1):Date("2014-07-29")

julia> collect(dr)
7-element Array{Date,1}:
 2014-01-29
 2014-02-28
 2014-03-29
 2014-04-29
 2014-05-29
 2014-06-29
 2014-07-29

アジャスター関数

日時と期間の算術は便利ですが、日時に対して行いたい計算が固定された期間ではなく "カレンダーを使った" あるいは "時間的な" 性質を持つこともあります。祝日はこのような計算の完璧な例です: 多くの祝日は「戦没将兵追悼記念日 = 五月の最終月曜日」や「感謝祭 = 十一月の第四木曜日」といった規則を持ちます。こういった時間的な表現では「月の最初/最後の日」「次の木曜日」「第一/第三水曜日」といったカレンダーを基準とした相対的な規則が使われています。

Dates モジュールは時間的な規則を簡単かつ十分に表現するための便利なメソッドを通してアジャスター (adjuster) API を提供します。アジャスター関数の一つ目のグループは、週・月・四半期の最初および最後を扱うものです。それぞれ単一の TimeType を受け取り、それが属する指定された期間における最初もしくは最後の日 (調整adjustされた日付) を返します:

julia> # 入力を同じ週の月曜日に調整する。
       Dates.firstdayofweek(Date(2014,7,16))
2014-07-14

julia> # 入力を同じ月の最後の日に調整する。
       Dates.lastdayofmonth(Date(2014,7,16))
2014-07-31

julia> # 入力を同じ四半期の最後の日に調整する。
       Dates.lastdayofquarter(Date(2014,7,16))
2014-09-30

二つ目のグループに属する二つの高階関数 tonext, toprev は時間的な表現の扱いを一般化します。これらの関数は DateFunction を第一引数に受け取り、その次に調整を行う TimeType が続きます。DateFunction は TimeType を受け取って Bool を返すただの関数 (たいていは無名関数) であり、調整が完了しているかどうかを判定します。tonext と toprev の使用例を示します:

julia> # x が火曜日なら true を返す。
       istuesday = x->Dates.dayofweek(x) == Dates.Tuesday;

julia> Dates.tonext(istuesday, Date(2014,7,13)) # 2014-07-13 は日曜日
2014-07-15

julia> # 利便性のため、曜日に対するメソッドは提供される。
       Dates.tonext(Date(2014,7,13), Dates.Tuesday)
2014-07-15

時間的な表現がもっと複雑なときは、do ブロックを使った記法が便利です:

julia> Dates.tonext(Date(2014,7,13)) do x
           # 11月の第四木曜日 (感謝祭の日) に対して true を返す。
           Dates.dayofweek(x) == Dates.Thursday &&
           Dates.dayofweekofmonth(x) == 4 &&
           Dates.month(x) == Dates.November
       end
2014-11-27

Base.filter メソッドを使えば、特定の範囲に含まれる正当な日時/瞬間を全て取得できます:

# ピッツバーグの道路清掃: 四月から十一月までの毎月第二火曜日
# 日付の範囲は 2014 年 1 月 1 日から 2015 年 1 月 1 日まで
julia> dr = Dates.Date(2014):Day(1):Dates.Date(2015);

julia> filter(dr) do x
           Dates.dayofweek(x) == Dates.Tue &&
           Dates.April <= Dates.month(x) <= Dates.Nov &&
           Dates.dayofweekofmonth(x) == 2
       end
8-element Array{Date,1}:
 2014-04-08
 2014-05-13
 2014-06-10
 2014-07-08
 2014-08-12
 2014-09-09
 2014-10-14
 2014-11-11

これ以外のテストや例は stdlib/Dates/test/adjusters.jl にあります。

Period 型

期間 (period) は人間の視点で区切られた時間の区間であり、期間が表す範囲がいつも同じとは限りません。例えば一か月という期間が表す日数は、年と月に応じて 28, 29, 30, 31 のいずれかとなります。また一年という期間はうるう年かどうかに応じて 365 日もしくは 366 日を表します。Period 型は Int64 の単純なラッパーであり、Int64 に変換可能な任意の型から構築できます。例えば Year(1) や Month(3.0) とします。同じ Period 同士の算術は整数と同様に振る舞い、Period と Real の間での算術も一部可能です。Dates.value を使えば内部に保持される整数を取り出せます:

julia> y1 = Dates.Year(1)
1 year

julia> y2 = Dates.Year(2)
2 years

julia> y3 = Dates.Year(10)
10 years

julia> y1 + y2
3 years

julia> div(y3,y2)
5

julia> y3 - y2
8 years

julia> y3 % y2
0 years

julia> div(y3,3) # 整数の除算と同様
3 years

julia> Dates.value(Dates.Millisecond(10))
10

丸め

floor, ceil, round を使うと、Date と DateTime を指定した分解能 (例えば一か月や十五分) で丸めることができます:

julia> floor(Date(1985, 8, 16), Dates.Month)
1985-08-01

julia> ceil(DateTime(2013, 2, 13, 0, 31, 20), Dates.Minute(15))
2013-02-13T00:45:00

julia> round(DateTime(2016, 8, 6, 20, 15), Dates.Day)
2016-08-07T00:00:00

数値型に対する round メソッドは丸めの候補が同着で二つあるときデフォルトで偶数に丸めますが、TimeType 型に対する round は RoundNearestTiesUp の丸めモードを使います (TimeType 型の "偶数" が何を意味するのかを決定するのは困難です)。RoundingMode に関する詳細は API リファレンスにあります。

丸めは基本的に予想通りの振る舞いをするはずですが、期待される振る舞いが自明でない場合がいくつかあります。

丸めエポック

多くの場合、丸めの分解能に指定される値 (例えば Dates.Second(30)) はその次に大きな期間 (Dates.Minute(1)) を等分します。しかしこの条件が成り立たないと、丸めで混乱が生じます。例えば DateTime を最も近い十時間の倍数に丸めた値とは何を意味するのでしょうか？ 試してみましょう:

julia> round(DateTime(2016, 7, 17, 11, 55), Dates.Hour(10))
2016-07-17T12:00:00

返り値の時要素 (12) が 10 で割り切れないので、なぜこうなるのかと困惑するかもしれません。返り値に 2016-07-17T12:00:00 が選ばれた理由は、この時刻が基準となる時刻 0000-01-01T00:00:00 から 17,676,660 時間後であり、17,676,660 が 10 で割り切れるためです。

Julia の Date と DateTime は ISO 8601 規格に従って表現されるので、0000-01-01T00:00:00 が丸め演算で日数/ミリ秒を数える基準 (「丸めエポック」) として選択されています。(Julia の Date の内部表現は Rata Die を使っているので、実際はこの説明と少し異なります。ただエンドユーザーは ISO 8601 を最も頻繁に目にするので、混乱を最小限にするために 0000-12-31T00:00:00 ではなく 0000-01-01T00:00:00 が丸めエポックとして選択されました。)

丸めエポックに唯一 0000-01-01T00:00:00 が使われないのが週単位の丸めです。最も近い週への丸めは必ず月曜日 (ISO 8601 が定める週の最初の日) を返します。このため、週単位の丸めでは 0000-01-03T00:00:00 (ISO 8601 が定義するゼロ年が持つ最初の「週の最初の日」) が丸めの基準として使われます。

期待される振る舞いが必ずしも自明でない似たケースがもう一つあります: P が Period 型のとき、最も近い P(2) へ丸めると何が起こるでしょうか？ 一部のケース (具体的には P <: Dates.TimePeriod の場合) では答えは明らかです:

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Hour(2))
2016-07-17T08:00:00

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Minute(2))
2016-07-17T08:56:00

Hour(2) と Minute(2) はそれぞれ一つ大きい単位を等分するので、丸めの結果は明らかに分かります。しかし Month(2) を使った場合には、これも一つ大きな単位を等分するにもかかわらず、驚くような結果が得られます:

julia> round(DateTime(2016, 7, 17, 8, 55, 30), Dates.Month(2))
2016-07-01T00:00:00

7 は奇数なのに、どうして七番目の月 July へ丸められたのでしょうか？ ここでの鍵は、0 から始まる時・分・秒・ミリ秒とは異なり、月が 1 始まりであるという事実です (最初の月は 1 月です)。

これは、偶数の秒・分・時・年 (ISO 8601 規格はゼロ年を含むため) への DateTime の丸めが、そのフィールドが偶数の DateTime を生成することを意味します。これに対して偶数の月への DateTime の丸めは月のフィールドが奇数の DateTime を生成します。月と年に含まれる日の個数は一定でないので、偶数の日へ丸めたときに結果の日のフィールドが偶数になるか奇数になるかは定まりません。

Dates モジュールがエクスポートするメソッドに関する追加の情報は API リファレンスを参照してください。

API リファレンス

日時と時刻の型

Period
Year
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

CompoundPeriod

Instant

UTInstant{T}

TimeType

DateTime

Date

Time

時刻に関する関数

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

DateTime(periods::Period...) -> DateTime

DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), limit=10000) -> DateTime

julia> DateTime(dt -> Dates.second(dt) == 40, 2010, 10, 20, 10;
                step = Dates.Second(1))
2010-10-20T10:00:40

julia> DateTime(dt -> Dates.hour(dt) == 20, 2010, 10, 20, 10;
                step = Dates.Hour(1), limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

DateTime(dt::Date) -> DateTime

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

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

DateFormat(format::AbstractString, locale="english") -> DateFormat

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

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

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

Date(period::Period...) -> Date

Date(f::Function, y[, m, d]; step=Day(1), limit=10000) -> Date

julia> Date(date -> Dates.week(date) == 20, 2010, 01, 01)
2010-05-17

julia> Date(date -> Dates.year(date) == 2010, 2000, 01, 01)
2010-01-01

julia> Date(date -> Dates.month(date) == 10, 2000, 01, 01; limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

Date(dt::DateTime) -> Date

Date(d::AbstractString, format::AbstractString; locale="english") -> Date

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

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

Time(period::TimePeriod...) -> Time

Time(f::Function, h, mi=0; step::Period=Second(1), limit::Int=10000)
Time(f::Function, h, mi, s; step::Period=Millisecond(1), limit::Int=10000)
Time(f::Function, h, mi, s, ms; step::Period=Microsecond(1), limit::Int=10000)
Time(f::Function, h, mi, s, ms, us; step::Period=Nanosecond(1), limit::Int=10000)

julia> Dates.Time(t -> Dates.minute(t) == 30, 20)
20:30:00

julia> Dates.Time(t -> Dates.minute(t) == 0, 20)
20:00:00

julia> Dates.Time(t -> Dates.hour(t) == 10, 3; limit = 5)
ERROR: ArgumentError: Adjustment limit reached: 5 iterations
Stacktrace:
[...]

Time(dt::DateTime) -> Time

now() -> DateTime

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

eps(::Type{DateTime}) -> Millisecond
eps(::Type{Date}) -> Day
eps(::Type{Time}) -> Nanosecond
eps(::TimeType) -> Period

julia> eps(DateTime)
1 millisecond

julia> eps(Date)
1 day

julia> eps(Time)
1 nanosecond

year(dt::TimeType) -> Int64

month(dt::TimeType) -> Int64

week(dt::TimeType) -> Int64

julia> Dates.week(Date(1989, 6, 22))
25

julia> Dates.week(Date(2005, 1, 1))
53

julia> Dates.week(Date(2004, 12, 31))
53

day(dt::TimeType) -> Int64

hour(dt::DateTime) -> Int64

hour(t::Time) -> Int64

minute(dt::DateTime) -> Int64

minute(t::Time) -> Int64

second(dt::DateTime) -> Int64

second(t::Time) -> Int64

millisecond(dt::DateTime) -> Int64

millisecond(t::Time) -> Int64

microsecond(t::Time) -> Int64

nanosecond(t::Time) -> Int64

Year(v)

Month(v)

Week(v)

Day(v)

Hour(dt::DateTime) -> Hour

Minute(dt::DateTime) -> Minute

Second(dt::DateTime) -> Second

Millisecond(dt::DateTime) -> Millisecond

Microsecond(dt::Time) -> Microsecond

Nanosecond(dt::Time) -> Nanosecond

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

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

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

dayname(dt::TimeType; locale="english") -> String
dayname(day::Integer; locale="english") -> String

julia> Dates.dayname(Date("2000-01-01"))
"Saturday"

julia> Dates.dayname(4)
"Thursday"

dayabbr(dt::TimeType; locale="english") -> String
dayabbr(day::Integer; locale="english") -> String

julia> Dates.dayabbr(Date("2000-01-01"))
"Sat"

julia> Dates.dayabbr(3)
"Wed"

dayofweek(dt::TimeType) -> Int64

julia> Dates.dayofweek(Date("2000-01-01"))
6

dayofmonth(dt::TimeType) -> Int64

dayofweekofmonth(dt::TimeType) -> Int

julia> Dates.dayofweekofmonth(Date("2000-02-01"))
1

julia> Dates.dayofweekofmonth(Date("2000-02-08"))
2

julia> Dates.dayofweekofmonth(Date("2000-02-15"))
3

daysofweekinmonth(dt::TimeType) -> Int

julia> Dates.daysofweekinmonth(Date("2005-01-01"))
5

julia> Dates.daysofweekinmonth(Date("2005-01-04"))
4

monthname(dt::TimeType; locale="english") -> String
monthname(month::Integer, locale="english") -> String

julia> Dates.monthname(Date("2005-01-04"))
"January"

julia> Dates.monthname(2)
"February"

monthabbr(dt::TimeType; locale="english") -> String
monthabbr(month::Integer, locale="english") -> String

julia> Dates.monthabbr(Date("2005-01-04"))
"Jan"

julia> monthabbr(2)
"Feb"

daysinmonth(dt::TimeType) -> Int

julia> Dates.daysinmonth(Date("2000-01"))
31

julia> Dates.daysinmonth(Date("2001-02"))
28

julia> Dates.daysinmonth(Date("2000-02"))
29

isleapyear(dt::TimeType) -> Bool

julia> Dates.isleapyear(Date("2004"))
true

julia> Dates.isleapyear(Date("2005"))
false

dayofyear(dt::TimeType) -> Int

daysinyear(dt::TimeType) -> Int

julia> Dates.daysinyear(1999)
365

julia> Dates.daysinyear(2000)
366

quarterofyear(dt::TimeType) -> Int

dayofquarter(dt::TimeType) -> Int

trunc(dt::TimeType, ::Type{Period}) -> TimeType

julia> trunc(Dates.DateTime("1996-01-01T12:30:00"), Dates.Day)
1996-01-01T00:00:00

firstdayofweek(dt::TimeType) -> TimeType

julia> Dates.firstdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-01T00:00:00

lastdayofweek(dt::TimeType) -> TimeType

julia> Dates.lastdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-07T00:00:00

firstdayofmonth(dt::TimeType) -> TimeType

julia> Dates.firstdayofmonth(DateTime("1996-05-20"))
1996-05-01T00:00:00

lastdayofmonth(dt::TimeType) -> TimeType

julia> Dates.lastdayofmonth(DateTime("1996-05-20"))
1996-05-31T00:00:00

firstdayofyear(dt::TimeType) -> TimeType

julia> Dates.firstdayofyear(DateTime("1996-05-20"))
1996-01-01T00:00:00

lastdayofyear(dt::TimeType) -> TimeType

julia> Dates.lastdayofyear(DateTime("1996-05-20"))
1996-12-31T00:00:00

firstdayofquarter(dt::TimeType) -> TimeType

julia> Dates.firstdayofquarter(DateTime("1996-05-20"))
1996-04-01T00:00:00

julia> Dates.firstdayofquarter(DateTime("1996-08-20"))
1996-07-01T00:00:00

lastdayofquarter(dt::TimeType) -> TimeType

julia> Dates.lastdayofquarter(DateTime("1996-05-20"))
1996-06-30T00:00:00

julia> Dates.lastdayofquarter(DateTime("1996-08-20"))
1996-09-30T00:00:00

tonext(dt::TimeType, dow::Int;
       same::Bool=false) -> TimeType

toprev(dt::TimeType, dow::Int;
       same::Bool=false) -> TimeType

tofirst(dt::TimeType, dow::Int; of=Month) -> TimeType

tolast(dt::TimeType, dow::Int; of=Month) -> TimeType

tonext(func::Function, dt::TimeType; step=Day(1), limit=10000, same=false) -> TimeType

toprev(func::Function, dt::TimeType; step=Day(-1), limit=10000, same=false) -> TimeType

Year(v)
Month(v)
Week(v)
Day(v)
Hour(v)
Minute(v)
Second(v)
Millisecond(v)
Microsecond(v)
Nanosecond(v)

CompoundPeriod(periods) -> CompoundPeriod

julia> Dates.CompoundPeriod(Dates.Hour(12), Dates.Hour(13))
25 hours

julia> Dates.CompoundPeriod(Dates.Hour(-1), Dates.Minute(1))
-1 hour, 1 minute

julia> Dates.CompoundPeriod(Dates.Month(1), Dates.Week(-2))
1 month, -2 weeks

julia> Dates.CompoundPeriod(Dates.Minute(50000))
50000 minutes

Dates.value(x::Period) -> Int64

default(p::Period) -> Period

floor(dt::TimeType, p::Period) -> TimeType

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

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

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

floor(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

julia> floor(Dates.Day(16), Dates.Week)
2 weeks

julia> floor(Dates.Minute(44), Dates.Minute(15))
30 minutes

julia> floor(Dates.Hour(36), Dates.Day)
1 day

ceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

julia> ceil(Dates.Day(16), Dates.Week)
3 weeks

julia> ceil(Dates.Minute(44), Dates.Minute(15))
45 minutes

julia> ceil(Dates.Hour(36), Dates.Day)
2 days

round(x::Period,
      precision::T,
      [r::RoundingMode]) where T <: Union{TimePeriod, Week, Day} -> T

julia> round(Dates.Day(16), Dates.Week)
2 weeks

julia> round(Dates.Minute(44), Dates.Minute(15))
45 minutes

julia> round(Dates.Hour(36), Dates.Day)
2 days

floorceil(dt::TimeType, p::Period) -> (TimeType, TimeType)

floorceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> (T, T)

epochdays2date(days) -> Date

epochms2datetime(milliseconds) -> DateTime

date2epochdays(dt::Date) -> Int64

datetime2epochms(dt::DateTime) -> Int64

today() -> Date

unix2datetime(x) -> DateTime

datetime2unix(dt::DateTime) -> Float64

julian2datetime(julian_days) -> DateTime

datetime2julian(dt::DateTime) -> Float64

rata2datetime(days) -> DateTime

datetime2rata(dt::TimeType) -> Int64