Dates

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

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

DateDateTime はどちらも先発グレゴリオ暦 (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

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

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

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

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

パースのパフォーマンスについて: コンストラクタを何度か呼ぶだけであれば 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 にあります。

期間/比較

DateDateTime は内部でそれぞれ 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 もあります。

daynamemonthname に省略可能なキーワード引数 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"

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

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

TimeTypePeriod の算術

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

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 が続きます。DateFunctionTimeType を受け取って Bool を返すただの関数 (たいていは無名関数) であり、調整が完了しているかどうかを判定します。tonexttoprev の使用例を示します:

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 同士の算術は整数と同様に振る舞い、PeriodReal の間での算術も一部可能です。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 を使うと、DateDateTime を指定した分解能 (例えば一か月や十五分) で丸めることができます:

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 型に対する roundRoundNearestTiesUp の丸めモードを使います (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 の DateDateTime は 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 が定義するゼロ年が持つ最初の「週の最初の日」) が丸めの基準として使われます。

期待される振る舞いが必ずしも自明でない似たケースがもう一つあります: PPeriod 型のとき、最も近い 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 リファレンス

日時と時刻の型

Dates.Period ──
Period
Year
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

Period 型は人間が自然に扱える離散的な時間の範囲を表します。

CompoundPeriod

CompoundPeriod は小さい単位の定数倍でない期間を表すときに使われます。例えば「一年と一日」は一日の定数倍ではありませんが、CompoundPeriod を使えば表現できます。実は異なる期間型を足すと自動的に CompoundPeriod が生成されます。例えば Year(1) + Day(1) の結果は CompoundPeriod です。

Dates.Instant ──
Instant

Instant 型は整数ベースの時刻のマシン表現を表します。時刻はエポックから始まる連続的な時間軸として表されます。

Dates.UTInstant ──
UTInstant{T}

UTInstant は世界時に基づいたマシンの時間軸を表現します (一日 = 地球の自転一周)。T は時刻の分解能あるいは精度を表す Period 型のパラメータです。

Dates.TimeType ──
TimeType

TimeType 型は Instant 型のマシン時刻をラップして人間のための表現を提供できるようにしたものです。Time, DateTime, Date はどれも TimeType の部分型です。

Dates.DateTime ──
DateTime

DateTimeUTInstant{Millisecond} をラップし、その値を先発グレゴリオ暦に従って解釈します。

Dates.Date ──
Date

DateUTInstant{Day} をラップし、その値を先発グレゴリオ暦に従って解釈します。

Dates.Time ──
Time

TimeNanosecond をラップし、一日二十四時間における特定の瞬間を表します。

時刻に関する関数

Dates.DateTime ── メソッド
DateTime(y, [m, d, h, mi, s, ms]) -> DateTime

DateTime 型を部分ごとに構築します。引数は Int64 に変換できる必要があります。

Dates.DateTime ── メソッド
DateTime(periods::Period...) -> DateTime

Period 型の部分ごとに DateTime を構築します。引数はどんな順序でも構いません。与えられなかった DateTime の部分は Dates.default(period) が返すデフォルト値となります。

Dates.DateTime ── メソッド
DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), limit=10000) -> DateTime

アジャスター API を通して DateTime を作成します。与えられた引数 y, m, d から開始地点が構築され、f::Functiontrue を返すまで調整されます。調整におけるステップサイズはキーワード引数 step で指定できます。limit はアジャスター API が行う反復の回数の上限であり、この回数まで実行が続く (f::Functiontrue を返さない) とエラーが送出されます。

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:
[...]
Dates.DateTime ── メソッド
DateTime(dt::Date) -> DateTime

DateDateTime に変換します。新しい DateTime の時・分・秒・ミリ秒はゼロとみなされます。

Dates.DateTime ── メソッド
DateTime(dt::AbstractString, format::AbstractString; locale="english") -> DateTime

時刻を表す文字列 dt をフォーマット文字列 format で与えられるパターンに従ってパースし、DateTime を構築します。

このメソッドは呼ばれるたびに DateFormat オブジェクトを作成します。同じフォーマット文字列を使って時刻を表す文字列を大量にパースするなら、個別に作成した DateFormat オブジェクトを第二引数に渡すようにしてください。

Dates.format ── メソッド
format(dt::TimeType, format::AbstractString; locale="english") -> AbstractString

与えられた formatTimeType オブジェクトに適用することで文字列を構築します。format 文字列で使えるコード文字は次の通りです:

コード コメント
y 6 年を数値として固定幅で表した文字列
Y 1996 年を数値として最小の幅で表した文字列
m 1, 12 月を数値として最小の幅で表した文字列
u Jan キーワード引数 locale が定める月の名前の省略形 (三文字)
U January キーワード引数 locale が定める完全な月の名前
d 1, 31 月における日を最小の幅で表した文字列
H 0, 23 時 (二十四時間表記) を最小の幅で表した文字列
M 0, 59 分を最小の幅で表した文字列
S 0, 59 秒を最小の幅で表した文字列
s 000, 500 ミリ秒を三文字以上の幅で表した文字列
e Mon, Tue 曜日の省略形
E Monday 曜日の完全な名前

文字列の幅はコード文字を連続させることで指定します。例えば yyyy-mm というフォーマットはコード y の幅が四文字でコード m に幅が二文字であることを示します。数字を出力するコードには固定幅モードと最小幅モードの二つがあります。固定幅モードでは文字列が短ければ数字の左側にゼロを詰めることで幅が揃えられ、文字列が長ければ切り捨てられます。最小幅モードは基本的に固定幅モードと同じですが、幅が足りないときに文字列を切り捨てません。

format を作成するときコードでない文字を区切り文字として利用できます。例えば "1996-01-15T00:00:00" のようなフォーマットを得るには "yyyy-mm-ddTHH:MM:SS" というフォーマット文字列を使います。コード文字をリテラルとして使うときはバックスラッシュでエスケープしてください。例えば "1996y01m""yyyy\ymm\m" というフォーマット文字列から得られます。

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

日時文字列のパースや日時オブジェクトの文字列化で使用する日時フォーマットオブジェクトを構築します。文字列 format では次のコード文字が利用できます:

コード マッチ コメント
y 1996, 96 1996, 0096 を返す
Y 1996, 96 1996, 0096 を返す (y と等価)
m 1, 01 月を表す一桁または二桁の数字とマッチする
u Jan キーワード引数 locale が定める月の名前の省略形とマッチする
U January キーワード引数 locale が定める月の完全な名前とマッチする
d 1, 01 日を表す一桁または二桁の数字とマッチする
H 00 時 (二十四時間表記) とマッチする
I 00 時を十二時間表記で出力する
M 00 分とマッチする
S 00 秒とマッチする
s .500 ミリ秒とマッチする
e Mon, Tues 曜日の名前の省略形とマッチする
E Monday 曜日の完全な名前とマッチする
p AM AM/PM とマッチする (大文字と小文字は区別される)
yyyymmdd 19960101 固定幅の年・月・日とマッチする

この表に載っていない文字は日時のスロットを区切る文字として扱われます。例えばマッチさせたい文字列が "1996-01-15T00:00:00.0" なら、フォーマット文字列は "y-m-dTH:M:S.s" とできます。コード文字を区切り文字として使うときはバックスラッシュでエスケープしてください。例えば "1995y01m""y\ym\m" というフォーマットを持ちます。

12:00AM は 00:00 (午前 0 時) であり、12:00PM は 12:00 (正午) を表すことに注意してください。p 指定子の付いた時刻をパースするとき時要素 (H または I) は必ず十二時間表記として扱われるので、I は主に出力で利用されます。

DateFormat オブジェクトの作成は時間のかかる処理です。可能な場合は必ず、オブジェクトを一度だけ作成して使い回すか文字列マクロ dateformat"" を使ってください。dateformat"" マクロを使うとマクロ展開時に DateFormat オブジェクトが一度だけ作成され、後の実行ではそのオブジェクトが再利用されます。詳細は @dateformat_str を参照してください。

DateFormat オブジェクトを使った日時を表す文字列のパースについては DateTime を、日時を表す文字列の出力については format をそれぞれ参照してください。

[email protected]_str ── マクロ
dateformat"Y-m-d H:M:S"

DateFormat オブジェクトを作成します。基本的に DateFormat("Y-m-d H:M:S") と同様ですが、DateFormat オブジェクトはマクロ展開時に一度だけ作成されます。

フォーマット指定子について詳しくは DateFormat を参照してください。

Dates.DateTime ── メソッド
DateTime(dt::AbstractString, df::DateFormat) -> DateTime

DateFormat オブジェクト df が指定するパターンに従って、日時を表す文字列 dt をパースして DateTime を構築します。動作は DateTime(::AbstractString, ::AbstractString) と同様ですが、同じフォーマットをした文字列を何度もパースするときにこのメソッドを使って事前に作成された DateFormat オブジェクトを使い回すと効率が大きく向上します。

Dates.Date ── メソッド
Date(y, [m, d]) -> Date

Date 型を部分ごとに構築します。引数は Int64 に変換できる必要があります。

Dates.Date ── メソッド
Date(period::Period...) -> Date

Period 型の部分ごとに Date 型を構築します。引数はどんな順序でも構いません。与えられなかった Date の部分は Dates.default(period) が返すデフォルト値となります。

Dates.Date ── メソッド
Date(f::Function, y[, m, d]; step=Day(1), limit=10000) -> Date

アジャスター API を通して Date を作成します。与えられた引数 y, m, d... から開始地点が構築され、f::Functiontrue を返すまで調整されます。調整におけるステップサイズはキーワード引数 step で指定できます。limit はアジャスター API が行う反復の回数の上限であり、この回数まで実行が続く (f::Functiontrue を返さない) とエラーが送出されます。

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:
[...]
Dates.Date ── メソッド
Date(dt::DateTime) -> Date

DateTimeDate に変換します。DateTime の時・分・秒・ミリ秒の部分は切り捨てられ、年・月・日の部分だけが使われます。

Dates.Date ── メソッド
Date(d::AbstractString, format::AbstractString; locale="english") -> Date

フォーマット文字列 format で与えられるパターンに従って日付を表す文字列 dt をパースし、Date を構築します。

このメソッドは呼ばれるたびに DateFormat を作成します。もし同じフォーマットを使って日付を表す文字列を大量にパースするなら、個別に作成した DateFormat を第二引数に渡すようにしてください。

Dates.Date ── メソッド
Date(d::AbstractString, df::DateFormat) -> Date

DateFormat オブジェクト df を使って日付を表す文字列 d をパースし、Date オブジェクトを作成します。

Dates.Time ── メソッド
Time(h, [mi, s, ms, us, ns]) -> Time

Time を部分ごとに構築します。引数は Int64 に変換できる必要があります。

Dates.Time ── メソッド
Time(period::TimePeriod...) -> Time

Period 型の部分ごとに Time を構築します。引数はどんな順序でも構いません。与えられなかった Time の部分は Dates.default(period) が返すデフォルト値となります。

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

アジャスター API を通して Time を作成します。与えられた引数 y, m, d... から開始地点が構築され、f::Functiontrue を返すまで調整されます。調整におけるステップサイズはキーワード引数 step で指定できます。limit はアジャスター API が行う反復の回数の上限であり、この回数まで実行が続く (f::Functiontrue を返さない) とエラーが送出されます。デフォルトのステップは与えられた引数より高い精度になるように選ばれます: 例えば引数で時・分・秒を指定すると、デフォルトステップは Second(1) ではなく Millisecond(1) となります。

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:
[...]
Dates.Time ── メソッド
Time(dt::DateTime) -> Time

DateTimeTime に変換します。DateTime の時・分・秒・ミリ秒が新しい Time の作成に使われます。マイクロ秒とナノ秒はデフォルトでゼロです。

Dates.now ── メソッド
now() -> DateTime

ユーザーのシステム時間に対応する DateTime を返します。システムのタイムゾーンロケールが考慮されます。

Dates.now ── メソッド
now(::Type{UTC}) -> DateTime

ユーザーのシステム時間を UTC/GMT とした DateTime を返します。

Base.eps ── 関数
eps(::Type{DateTime}) -> Millisecond
eps(::Type{Date}) -> Day
eps(::Type{Time}) -> Nanosecond
eps(::TimeType) -> Period

TimeType がサポートする最小単位を返します。

julia> eps(DateTime)
1 millisecond

julia> eps(Date)
1 day

julia> eps(Time)
1 nanosecond

アクセッサ関数

Dates.year ── 関数
year(dt::TimeType) -> Int64

Date あるいは DateTime の年を Int64 として返します。

Dates.month ── 関数
month(dt::TimeType) -> Int64

Date あるいは DateTime の月を Int64 として返します。

Dates.week ── 関数
week(dt::TimeType) -> Int64

Date あるいは DateTimeISO 週番号 (ISO week number) を Int64 として返します。一年で最初の週はその年最初の木曜日が含まれる週であることに注意してください。このため一月四日より前の日付が前年の週となる可能性があります。例えば 2005 年 1 月 1 日土曜日は 2004 年の 53 番目の週に含まれます。

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

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

julia> Dates.week(Date(2004, 12, 31))
53
Dates.day ── 関数
day(dt::TimeType) -> Int64

Date あるいは DateTime の月における日付を Int64 として返します。

Dates.hour ── 関数
hour(dt::DateTime) -> Int64

DateTime の時要素を Int64 として返します。

hour(t::Time) -> Int64

Time の時要素を Int64 として返します。

Dates.minute ── 関数
minute(dt::DateTime) -> Int64

DateTime の分要素を Int64 として返します。

minute(t::Time) -> Int64

Time の分要素を Int64 として返します。

Dates.second ── 関数
second(dt::DateTime) -> Int64

DateTime の秒要素を Int64 として返します。

second(t::Time) -> Int64

Time の秒要素を Int64 として返します。

Dates.millisecond ── 関数
millisecond(dt::DateTime) -> Int64

DateTime のミリ秒要素を Int64 として返します。

millisecond(t::Time) -> Int64

Time のミリ秒要素を Int64 として返します。

Dates.microsecond ── 関数
microsecond(t::Time) -> Int64

DateTime のマイクロ秒要素を Int64 として返します。

Dates.nanosecond ── 関数
nanosecond(t::Time) -> Int64

Time のナノ秒要素を Int64 として返します。

Dates.Year ── メソッド
Year(v)

与えられた値 v から Year オブジェクトを構築します。入力 v は情報を失うことなく Int64 に変換できる必要があります。

Dates.Month ── メソッド
Month(v)

与えられた値 v から Month オブジェクトを構築します。入力 v は情報を失うことなく Int64 に変換できる必要があります。

Dates.Week ── メソッド
Week(v)

与えられた値 v から Week オブジェクトを構築します。入力 v は情報を失うことなく Int64 に変換できる必要があります。

Dates.Day ── メソッド
Day(v)

与えられた値 v から Day オブジェクトを構築します。入力 v は情報を失うことなく Int64 に変換できる必要があります。

Dates.Hour ── メソッド
Hour(dt::DateTime) -> Hour

DateTime の時要素を Hour として返します。

Dates.Minute ── メソッド
Minute(dt::DateTime) -> Minute

DateTime の分要素を Minute として返します。

Dates.Second ── メソッド
Second(dt::DateTime) -> Second

DateTime の秒要素を Second として返します。

Dates.Millisecond ── メソッド
Millisecond(dt::DateTime) -> Millisecond

DateTime のミリ秒要素を Millisecond として返します。

Dates.Microsecond ── メソッド
Microsecond(dt::Time) -> Microsecond

Time のマイクロ秒要素を Microsecond として返します。

Dates.Nanosecond ── メソッド
Nanosecond(dt::Time) -> Nanosecond

Time のナノ秒要素を Nanosecond として返します。

Dates.yearmonth ── 関数
yearmonth(dt::TimeType) -> (Int64, Int64)

Date または DateTime の年要素と月要素をまとめて返します。

Dates.monthday ── 関数
monthday(dt::TimeType) -> (Int64, Int64)

Date または DateTime の月要素と日要素をまとめて返します。

Dates.yearmonthday ── 関数
yearmonthday(dt::TimeType) -> (Int64, Int64, Int64)

Date または DateTime の年・月・日の要素をまとめて返します。

クエリ関数

Dates.dayname ── 関数
dayname(dt::TimeType; locale="english") -> String
dayname(day::Integer; locale="english") -> String

Date あるいは DateTime が表す曜日の locale における完全な名前を返します。Integer も受け付けます。

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

julia> Dates.dayname(4)
"Thursday"
Dates.dayabbr ── 関数
dayabbr(dt::TimeType; locale="english") -> String
dayabbr(day::Integer; locale="english") -> String

Date あるいは DateTime が表す曜日の locale における名前の省略形を返します。Integer も受け付けます。

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

julia> Dates.dayabbr(3)
"Wed"
Dates.dayofweek ── 関数
dayofweek(dt::TimeType) -> Int64

曜日を Int64 として返します。返り値 1 は月曜日、返り値 2 は火曜日、などとなります。

julia> Dates.dayofweek(Date("2000-01-01"))
6
Dates.dayofmonth ── 関数
dayofmonth(dt::TimeType) -> Int64

Date あるいは DateTime の月における日付を Int64 として返します。

Dates.dayofweekofmonth ── 関数
dayofweekofmonth(dt::TimeType) -> Int

dt の月で dt の曜日が何回目かを返します。例えば dt が月曜日なら、返り値 1dt が第一月曜日であることを示し、返り値 2dt が第二月曜日であることを示します。返り値は 1:5 の区間に含まれます。

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

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

julia> Dates.dayofweekofmonth(Date("2000-02-15"))
3
Dates.daysofweekinmonth ── 関数
daysofweekinmonth(dt::TimeType) -> Int

dt の曜日が dt の月に何回あるかを返します。返り値は 4 または 5 です。アジャスター関数で dayofweekofmonth(dt) == daysofweekinmonth(dt) とすれば月の最後の曜日を指定できるので、この関数は時間的な表現で有用です。

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

julia> Dates.daysofweekinmonth(Date("2005-01-04"))
4
Dates.monthname ── 関数
monthname(dt::TimeType; locale="english") -> String
monthname(month::Integer, locale="english") -> String

Date/DateTime/Integer が表す月の locale における完全な名前を返します。

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

julia> Dates.monthname(2)
"February"
Dates.monthabbr ── 関数
monthabbr(dt::TimeType; locale="english") -> String
monthabbr(month::Integer, locale="english") -> String

Date/DateTime/Integer が表す月の locale における名前の省略形を返します。

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

julia> monthabbr(2)
"Feb"
Dates.daysinmonth ── 関数
daysinmonth(dt::TimeType) -> Int

dt が属する月の日数を返します。返り値は 28, 29, 30, 31 のどれかです。

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

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

julia> Dates.daysinmonth(Date("2000-02"))
29
Dates.isleapyear ── 関数
isleapyear(dt::TimeType) -> Bool

dt が属する年がうるう年なら true を返します。

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

julia> Dates.isleapyear(Date("2005"))
false
Dates.dayofyear ── 関数
dayofyear(dt::TimeType) -> Int

dt の年における日付を返します。1 月 1 日が 1 です。

Dates.daysinyear ── 関数
daysinyear(dt::TimeType) -> Int

dt がうるう年に属するなら 366 を、そうでなければ 365 を返します。

julia> Dates.daysinyear(1999)
365

julia> Dates.daysinyear(2000)
366
Dates.quarterofyear ── 関数
quarterofyear(dt::TimeType) -> Int

dt の属する四半期を返します。返り値は 1, 2, 3, 4 のいずれかです。

Dates.dayofquarter ── 関数
dayofquarter(dt::TimeType) -> Int

dt が属する四半期における日付を返します。返り値の範囲は 1:92 です。

アジャスター関数

Base.trunc ── メソッド
trunc(dt::TimeType, ::Type{Period}) -> TimeType

与えられた Period 型の値を使って dt を切り捨てます。

julia> trunc(Dates.DateTime("1996-01-01T12:30:00"), Dates.Day)
1996-01-01T00:00:00
Dates.firstdayofweek ── 関数
firstdayofweek(dt::TimeType) -> TimeType

dt を同じ週の月曜日に調整します。

julia> Dates.firstdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-01T00:00:00
Dates.lastdayofweek ── 関数
lastdayofweek(dt::TimeType) -> TimeType

dt を同じ週の日曜日に調整します。

julia> Dates.lastdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-07T00:00:00
Dates.firstdayofmonth ── 関数
firstdayofmonth(dt::TimeType) -> TimeType

dt を同じ月の最初の日に調整します。

julia> Dates.firstdayofmonth(DateTime("1996-05-20"))
1996-05-01T00:00:00
Dates.lastdayofmonth ── 関数
lastdayofmonth(dt::TimeType) -> TimeType

dt を同じ月の最後の日に調整します。

julia> Dates.lastdayofmonth(DateTime("1996-05-20"))
1996-05-31T00:00:00
Dates.firstdayofyear ── 関数
firstdayofyear(dt::TimeType) -> TimeType

dt を同じ年の最初の日に調整します。

julia> Dates.firstdayofyear(DateTime("1996-05-20"))
1996-01-01T00:00:00
Dates.lastdayofyear ── 関数
lastdayofyear(dt::TimeType) -> TimeType

dt を同じ年の最後の日に調整します。

julia> Dates.lastdayofyear(DateTime("1996-05-20"))
1996-12-31T00:00:00
Dates.firstdayofquarter ── 関数
firstdayofquarter(dt::TimeType) -> TimeType

dt を同じ四半期の最初の日に調整します。

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

julia> Dates.firstdayofquarter(DateTime("1996-08-20"))
1996-07-01T00:00:00
Dates.lastdayofquarter ── 関数
lastdayofquarter(dt::TimeType) -> TimeType

dt を同じ四半期の最後の日に調整します。

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

julia> Dates.lastdayofquarter(DateTime("1996-08-20"))
1996-09-30T00:00:00
Dates.tonext ── メソッド
tonext(dt::TimeType, dow::Int;
       same::Bool=false) -> TimeType

dt を次の dow 曜日に調整します。曜日は 1 = 月曜日, 2 = 火曜日, ... のように指定されます。same=true とすると現在の dt が次の dow 曜日とみなされ、調整せずに dt をそのまま返すことが許可されます。

Dates.toprev ── メソッド
toprev(dt::TimeType, dow::Int;
       same::Bool=false) -> TimeType

dt を前の dow 曜日とします。曜日は 1 = 月曜日, 2 = 火曜日, ... のように指定されます。same=true とすると現在の dt が前の dow 曜日とみなされ、調整せずに dt をそのまま返すことが許可されます。

Dates.tofirst ── 関数
tofirst(dt::TimeType, dow::Int; of=Month) -> TimeType

dt を同じ月の最初の dow 曜日に調整します。of=Year とすると同じ年の最初の dow 曜日に調整します。

Dates.tolast ── 関数
tolast(dt::TimeType, dow::Int; of=Month) -> TimeType

dt を同じ月の最後の dow 曜日に調整します。of=Year とすると同じ年の最後の dow 曜日に調整します。

Dates.tonext ── メソッド
tonext(func::Function, dt::TimeType; step=Day(1), limit=10000, same=false) -> TimeType

dtstep だけ大きくする処理を functrue を返すまで繰り返すことで dt を調整します。limit は反復回数の上限です。func は単一の TimeType を引数に受け取り Bool を返す必要があります。samedt 自身を func に入力するかどうかを制御します。

Dates.toprev ── メソッド
toprev(func::Function, dt::TimeType; step=Day(-1), limit=10000, same=false) -> TimeType

dtstep だけ小さくする処理を functrue を返すまで繰り返すことで dt を調整します。limit は反復回数の上限です。func は単一の TimeType を引数に受け取り Bool を返す必要があります。samedt 自身を func に入力するかどうかを制御します。

期間

Dates.Period ── メソッド
Year(v)
Month(v)
Week(v)
Day(v)
Hour(v)
Minute(v)
Second(v)
Millisecond(v)
Microsecond(v)
Nanosecond(v)

与えられた v を値に持つ Period を構築します。入力 v は情報を失うことなく Int64 に変換できる必要があります。

Dates.CompoundPeriod ── メソッド
CompoundPeriod(periods) -> CompoundPeriod

PeriodVector から CompoundPeriod を構築します。同じ型の Period は足されます。

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 ── 関数
Dates.value(x::Period) -> Int64

与えられた期間に関連付いた値を返します。例えば value(Millisecond(10)) は整数 10 を返します。

Dates.default ── 関数
default(p::Period) -> Period

入力された Period の型に対する常識的な “デフォルト” 値を返します。Year, Month, Day では T(1) が返り、Hour, Minute, Second, Millisecond では T(0) が返ります。

丸め関数

DateDateTime に対する分解能 (例えば一か月や十五分) を指定した丸めは floor, ceil, round で行います。

Base.floor ── メソッド
floor(dt::TimeType, p::Period) -> TimeType

分解能が p のとき dt 以下の最も近い Date または DateTime を返します。

利便性のため、p には値だけではなく型も指定できます: floor(dt, Dates.Hour)floor(dt, Dates.Hour(1)) の省略形です。

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

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

julia> floor(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day)
2016-08-06T00:00:00
Base.ceil ── メソッド
ceil(dt::TimeType, p::Period) -> TimeType

分解能が p のとき dt 以上の最も近い Date または DateTime を返します。

利便性のため、p には値だけではなく型も指定できます: ceil(dt, Dates.Hour)ceil(dt, Dates.Hour(1)) の省略形です。

julia> ceil(Date(1985, 8, 16), Dates.Month)
1985-09-01

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

julia> ceil(DateTime(2016, 8, 6, 12, 0, 0), Dates.Day)
2016-08-07T00:00:00
Base.round ── メソッド
round(dt::TimeType, p::Period, [r::RoundingMode]) -> TimeType

分解能が p のとき dt に最も近い Date または DateTime を返します。デフォルトの丸めモードは RoundNearestTiesUp であり、同着のとき (例えば 9:30 を一時間で丸めるとき) 上へ丸めます。

利便性のため、p には値だけではなく型も指定できます: round(dt, Dates.Hour)round(dt, Dates.Hour(1)) の省略形です。

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

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

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

round(::TimeType, ::Period, ::RoundingMode) で利用できる正当な丸めモードは次の通りです:

  • RoundNearestTiesUp (デフォルト)
  • RoundDown (floor)
  • RoundUp (ceil)

たいていの Period 型の値も指定した分解能に丸められます:

Base.floor ── メソッド
floor(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

x を最も近い precision の倍数へ切り捨てます。xprecision が異なる Period の部分型である場合には、返り値は precision と同じ型になります。

利便性のため、p には値だけではなく型も指定できます: floor(dt, Dates.Hour)floor(dt, Dates.Hour(1)) の省略形です。

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

precisionMonth および Year とした丸めはサポートされません。そういった Period は長さが一定でないためです。

Base.ceil ── メソッド
ceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

x を最も近い precision の倍数へ切り上げます。xprecision が異なる Period の部分型である場合には、返り値は precision と同じ型になります。

利便性のため、p には値だけではなく型も指定できます: ceil(dt, Dates.Hour)ceil(dt, Dates.Hour(1)) の省略形です。

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

precisionMonth および Year とした丸めはサポートされません。そういった Period は長さが一定でないためです。

Base.round ── メソッド
round(x::Period,
      precision::T,
      [r::RoundingMode]) where T <: Union{TimePeriod, Week, Day} -> T

x を最も近い precision の倍数へ丸めます。xprecision が異なる Period の部分型である場合には、返り値は precision と同じ型になります。デフォルトの丸めモードは RoundNearestTiesUp であり、同着のとき (例えば 90 分を最も近い一時間で丸めるとき) 切り上げます。

利便性のため、p には値だけではなく型も指定できます: round(dt, Dates.Hour)round(dt, Dates.Hour(1)) の省略形です。

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

round(::Period, ::T, ::RoundingMode) に対する正当な丸めモードは次の通りです:

  • RoundNearestTiesUp (デフォルト)
  • RoundDown (floor)
  • RoundUp (ceil)

precisionMonth および Year とした丸めはサポートされません。そういった Period は長さが一定でないためです。

これ以降の関数はエクスポートされません:

Dates.floorceil ── 関数
floorceil(dt::TimeType, p::Period) -> (TimeType, TimeType)

Date または DateTime に対する分解能 pfloorceil をまとめて返します。floorceil を別々に呼び出すより高速です。

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

Period に対する分解能 pfloorceil を同時に返します。floorceil を別々に呼び出すより高速です。

Dates.epochdays2date ── 関数
epochdays2date(days) -> Date

丸めエポック (0000-01-01T00:00:00) からの日数を受け取り、それに対応する Date を返します。

Dates.epochms2datetime ── 関数
epochms2datetime(milliseconds) -> DateTime

丸めエポック (0000-01-01T00:00:00) からの経過ミリ秒数を受け取り、それに対応する DateTime を返します。

Dates.date2epochdays ── 関数
date2epochdays(dt::Date) -> Int64

Date を受け取り、丸めエポック (0000-01-01T00:00:00) からの日数を Int64 で返します。

Dates.datetime2epochms ── 関数
datetime2epochms(dt::DateTime) -> Int64

Date を受け取り、丸めエポック (0000-01-01T00:00:00) からの経過ミリ秒を Int64 で返します。

変換関数

Dates.today ── 関数
today() -> Date

now() の日要素を返します。

Dates.unix2datetime ── 関数
unix2datetime(x) -> DateTime

Unix エポック 1970-01-01T00:00:00 からの経過秒数を受け取り、それを DateTime に変換します。

Dates.datetime2unix ── 関数
datetime2unix(dt::DateTime) -> Float64

DateTime を受け取り、Unix エポック 1970-01-01T00:00:00 からの経過秒数を Float64 として返します。

Dates.julian2datetime ── 関数
julian2datetime(julian_days) -> DateTime

ユリウス暦におけるエポック -4713-11-24T12:00:00 からの経過日数を受け取り、対応する DateTime を返します。

Dates.datetime2julian ── 関数
datetime2julian(dt::DateTime) -> Float64

DateTime を受け取り、ユリウス暦のエポック -4713-11-24T12:00:00 からの経過日数を Float64 として返します。

Dates.rata2datetime ── 関数
rata2datetime(days) -> DateTime

Rata Die におけるエポック 0000-12-31T00:00:00 からの経過日数を受け取り、対応する DateTime を返します。

Dates.datetime2rata ── 関数
datetime2rata(dt::TimeType) -> Int64

Rata Die におけるエポック 0000-12-31T00:00:00 から与えられた Date あるいは DateTime までの日数を返します。

定数

曜日:

変数 省略形 値 (Int)
Monday Mon 1
Tuesday Tue 2
Wednesday Wed 3
Thursday Thu 4
Friday Fri 5
Saturday Sat 6
Sunday Sun 7

月:

変数 省略形 値 (Int)
January Jan 1
February Feb 2
March Mar 3
April Apr 4
May May 5
June Jun 6
July Jul 7
August Aug 8
September Sep 9
October Oct 10
November Nov 11
December Dec 12

  1. 世界時秒 (UT second) という概念は非常に重要です。一般に二つの異なる概念が時刻として受け入れられています: 一つは物理的な地球の自転に基づく時刻 (一周 = 一日) で、もう一つは SI 秒 (固定された定数) に基づく時刻です。この二つは大きく異なります! 考えてみてください、地球の自転を使って相対的に定義される「世界時秒」は、日によって長さが異なる可能性があるのです! まぁとにかく、DateDateTime が世界時秒に基づいているという事実もまた、うるう秒やそれに付随する複雑な問題を避けるための仮定です。この時刻の基準はかつて UT あるいは UT1 と呼ばれました。世界時秒に基づいて型を作ることで、全ての分は 60 秒、全ての日は 24 時間となり、日付を使う計算がより自然に行えます。[return]

  2. 訳注: 英語版の表現を修正した。英語版にある MONTHTOVALUEABBR, MONTHTOVALUE という変数は現在のバージョンに存在しない。[return]