Dates

Dates モジュールは、日付を扱うための2つの型、Date と DateTime を提供します。それぞれ日単位とミリ秒単位の精度を表し、どちらも抽象型 TimeType のサブタイプです。型を分ける理由は単純です。より高い精度に伴う複雑さを考慮しなくてよい場合、コードの記述も、頭の中での推論も、はるかに簡単になる操作があるためです。たとえば、Date 型は1日単位の精度しか持たないため(つまり、時・分・秒を扱わないため)、タイムゾーン、夏時間、うるう秒について通常必要となる考慮は不要であり、回避できます。

Date と DateTime は、基本的に不変な Int64 ラッパーです。どちらの型も、唯一のフィールド instant は実際には UTInstant{P} 型であり、UT秒に基づいて連続的に増加するマシン上の時間軸を表します[1]。DateTime 型はタイムゾーンを認識しません(Pythonの用語では naive)。Java 8の LocalDateTime に相当します。タイムゾーン機能を追加するには、TimeZones.jl package を利用できます。これは IANA time zone database をコンパイルします。Date と DateTime はどちらも、先発グレゴリオ暦に従う ISO 8601 標準に基づいています。ISO 8601標準では、紀元前(BC/BCE)の日付の扱いに注意が必要です。一般に、紀元前の最後の日である紀元前1年12月31日の翌日は、紀元1年1月1日であり、したがって0年は存在しません。しかしISO標準では、紀元前1年を0年と定めています。そのため、0000-12-31 は 0001-01-01 の前日であり、年 -0001(そう、年はマイナス1です)は紀元前2年、年 -0002 は紀元前3年となります。

Constructors

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 または DateTime のコンストラクターに渡す形式は、Date("2015-01-01",dateformat"y-m-d") または DateTime("20150101",dateformat"yyyymmdd") です。

区切り付きスロットでは、連続する2つの期間の間にパーサーが期待する区切り文字を指定します。たとえば、"y-m-d" は、"2014-07-16" のような日付文字列の最初と2番目のスロットの間に、- 文字があることをパーサーに伝えます。y、m、d の各文字は、それぞれのスロットで解析する期間をパーサーに伝えます。

上記の Date(2013) などのコンストラクターと同様に、区切り付きの DateFormat では、先行する部分が指定されていれば、日付や時刻の一部を省略できます。省略された部分には通常の既定値が使われます。たとえば、Date("1981-03", dateformat"y-m-d") は 1981-03-01 を返し、Date("31/12", dateformat"d/m/y") は 0001-12-31 を返します。(既定の年は紀元1年です。)ただし、空文字列を渡すと必ず ArgumentError がスローされます。

固定幅スロットは、区切り文字を挟まず、期間を表す文字を幅の数だけ繰り返して指定します。したがって、dateformat"yyyymmdd" は、"20140716" のような日付文字列に対応します。パーサーは区切り文字がないことから固定幅スロットを判別し、ある期間文字から次の期間文字への移行を "yyyymm" として認識します。

月名をテキスト形式で解析する機能も、略称用の u と、完全な月名用の U によって利用できます。既定では英語の月名のみがサポートされるため、u は「Jan」「Feb」「Mar」などに対応し、U は「January」「February」「March」などに対応します。dayname や monthname など、名前から値へのマッピングを行う他の関数と同様に、略称と完全な月名に対応する MONTHTOVALUEABBR および MONTHTOVALUE の辞書に locale=>Dict{String,Int} マッピングを渡すことで、独自のロケールを読み込めます。

上記の例では、dateformat"" 文字列マクロを使いました。このマクロは展開時に DateFormat オブジェクトを一度だけ作成し、コードスニペットを複数回実行しても同じ DateFormat オブジェクトを使います。

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

または、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

ブロードキャストを使う方法もあります。

julia> years = ["2015", "2016"];

julia> Date.(years, DateFormat("yyyy"))
2-element Vector{Date}:
 2015-01-01
 2016-01-01

簡便な方法として、書式文字列を直接渡すこともできます(例:Date("2015-01-01","y-m-d"))。ただし、同じ書式を繰り返し解析する場合、この形式は毎回新しい DateFormat オブジェクトを内部で作成するため、性能上のコストがかかります。

コンストラクターに加えて、Date または DateTime は、parse 関数や tryparse 関数を使って文字列から構築することもできます。これらの関数には、書式を指定する DateFormat 型の第3引数を任意で渡せます。たとえば、parse(Date, "06.23.2013", dateformat"m.d.y") のように指定するか、既定の書式を使う tryparse(DateTime, "1999-12-31T23:59:59") を使います。両関数の主な違いは、tryparse では文字列が空、または書式が無効でもエラーがスローされず、代わりに nothing が返される点です。

Julia 1.9

Julia 1.9より前は、空文字列をコンストラクターや parse に渡してもエラーにならず、適切な値として DateTime(1)、Date(1)、または Time(0) が返されていました。同様に、tryparse は nothing を返しませんでした。

解析と書式設定に関するテストおよび例一式は、stdlib/Dates/test/io.jl で確認できます。

Durations/Comparisons

Date または DateTime の内部表現は、それぞれ UTInstant{Day} と UTInstant{Millisecond} なので、2つの値の間の時間を求めるのは簡単です。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

Accessor Functions

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

Query Functions

問い合わせ関数を使うと、TimeType に関する暦情報を取得できます。たとえば、曜日に関する情報です。

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

julia> Dates.dayofweek(t)
5

julia> Dates.dayname(t)
"Friday"

julia> Dates.dayofweekofmonth(t) # 5th Friday of January
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

dayname メソッドと monthname メソッドには、他の言語やロケールで曜日名または月名を返すための locale キーワード引数を任意で指定できます。略称を返す関数として、dayabbr と monthabbr もあります。まず、マッピングを LOCALES 変数に読み込みます。

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

julia> french_months_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_months_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 を使おうとするとエラーになります。

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

TimeType-Period Arithmetic

どの言語や日付フレームワークを使う場合でも、日付と期間の算術がどのように処理されるかを把握しておくのがよいでしょう。対処が必要な tricky issues がいくつかあるためです(ただし、日単位の精度を持つ型では問題はかなり少なくなります)。

Dates モジュールでは、Period 算術を行う際に、できるだけ変更を少なくするという単純な原則に従っています。この方法は 暦算術 とも呼ばれ、会話の中で同じ計算を尋ねられたときに、おそらく直感的に答える方法でもあります。なぜこれが問題になるのでしょうか。よくある例を考えてみましょう。2014年1月31日に1か月を加えると、どうなるでしょうか。JavaScriptでは March 3 となります(31日あると仮定)。PHPでは March 2 となります(30日あると仮定)。実際のところ、正解はありません。Dates モジュールでは、結果は2月28日になります。どのように求めるのでしょうか。カジノの定番スロットマシン、7-7-7を考えてみてください。

今度は、スロットの数字が7-7-7ではなく、年-月-日だと想像してください。この例では2014-01-31です。この日付に1か月を加えると、月のスロットが1つ進み、2014-02-31になります。次に、日が新しい月の最終日を超えているかを確認します。上の例のように超えていれば、日を有効な最終日(28日)まで戻します。この方法にはどのような影響があるでしょうか。元の日付 2014-02-28 + Month(1) == 2014-03-28 に、さらに1か月を加えてみてください。3月の最終日になると思いましたか。いいえ、7-7-7のスロットを思い出してください。変更するスロットはできるだけ少なくするため、まず月のスロットを1つ進めて2014-03-28とし、これは有効な日付なのでそこで終了です。一方、元の日付2014-01-31に2か月を加えると、期待どおり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行目では、2014年1月29日に1日を加えて2014-01-30とし、次に1か月を加えます。すると2014-02-30になりますが、これは2014-02-28に調整されます。2つ目の例では、まず1か月を加えるため、2014-02-29となり、2014-02-28に調整されます。その後、1日を加えると2014-03-01になります。この場合に役立つ設計原則の1つは、複数の 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 を使う人は、どうすればよいのでしょうか。要点は、月を扱うときに結合順序を明示的に固定すると、予想外の結果になることがあると理解しておくことです。それ以外は、すべて期待どおりに動作するはずです。幸い、UTに基づいて時間を扱う日付・期間算術で奇妙なケースは、ほぼこれだけです(夏時間やうるう秒などの「楽しさ」を避けられるためです)。

さらに、すべての期間算術オブジェクトは範囲と直接組み合わせて使えます。

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 Vector{Date}:
 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 Vector{Date}:
 2014-01-29
 2014-02-28
 2014-03-29
 2014-04-29
 2014-05-29
 2014-06-29
 2014-07-29

Adjuster Functions

日付と期間の算術は便利ですが、日付に必要な計算は、固定数の期間ではなく、暦や時間的な規則に基づくことがよくあります。祝日はその典型例です。「メモリアルデー = 5月の最終月曜日」や「感謝祭 = 11月の第4木曜日」のような規則に従うものが多くあります。このような時間的な表現では、「月の最初または最後の日」「次の火曜日」「第1および第3水曜日」など、暦に基づく規則を扱います。

Dates モジュールは、時間的な規則を簡潔に表現するのに役立つ、便利な複数のメソッドを通じて adjuster API を提供します。最初のグループの adjuster メソッドは、週・月・四半期・年の最初と最後を扱います。いずれも入力として単一の TimeType を受け取り、入力を基準に、指定した期間の最初または最後へ値を返す、あるいは値を調整します。

julia> Dates.firstdayofweek(Date(2014,7,16)) # Adjusts the input to the Monday of the input's week
2014-07-14

julia> Dates.lastdayofmonth(Date(2014,7,16)) # Adjusts to the last day of the input's month
2014-07-31

julia> Dates.lastdayofquarter(Date(2014,7,16)) # Adjusts to the last day of the input's quarter
2014-09-30

次の2つの高階メソッド tonext と toprev は、第1引数に DateFunction を取り、開始点となる TimeType と組み合わせることで、時間的な規則を一般化して扱います。DateFunction は単なる関数(通常は無名関数)で、入力として単一の TimeType を受け取り、調整条件を満たす Bool または true を返します。たとえば、次のようになります。

julia> istuesday = x->Dates.dayofweek(x) == Dates.Tuesday; # Returns true if the day of the week of x is Tuesday

julia> Dates.tonext(istuesday, Date(2014,7,13)) # 2014-07-13 is a Sunday
2014-07-15

julia> Dates.tonext(Date(2014,7,13), Dates.Tuesday) # Convenience method provided for day of the week adjustments
2014-07-15

より複雑な時間的規則を表現する場合は、doブロック構文が便利です。

julia> Dates.tonext(Date(2014,7,13)) do x
           # Return true on the 4th Thursday of November (Thanksgiving)
           Dates.dayofweek(x) == Dates.Thursday &&
           Dates.dayofweekofmonth(x) == 4 &&
           Dates.month(x) == Dates.November
       end
2014-11-27

Base.filter メソッドを使うと、指定した範囲内の有効な日付や時刻をすべて取得できます。

# Pittsburgh street cleaning; Every 2nd Tuesday from April to November
# Date range from January 1st, 2014 to January 1st, 2015
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 Vector{Date}:
 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 Types

期間とは、人間の視点から見た、離散的で、ときには不規則な時間の長さです。たとえば1か月は、年や月の状況によって28日、29日、30日、31日のいずれかになります。また、うるう年の場合、1年は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) # mirrors integer division
3 years

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

基本型の整数倍ではない期間や長さを表すには、Dates.CompoundPeriod 型を使います。複合期間は、単純な Period 型から手動で構築できます。また、canonicalize 関数を使って、期間を Dates.CompoundPeriod に分解することもできます。これは、たとえば2つの DateTime の差のような長さを、より扱いやすい表現に変換する場合に特に便利です。

julia> cp = Dates.CompoundPeriod(Day(1),Minute(1))
1 day, 1 minute

julia> t1 = DateTime(2018,8,8,16,58,00)
2018-08-08T16:58:00

julia> t2 = DateTime(2021,6,23,10,00,00)
2021-06-23T10:00:00

julia> canonicalize(t2-t1) # creates a CompoundPeriod
149 weeks, 6 days, 17 hours, 2 minutes

Rounding

Date と DateTime の値は、floor、ceil、または round を使って、指定した精度(例:1か月、15分)に丸めることができます。

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 メソッドとは異なり、TimeTyperound メソッドでは RoundNearestTiesUp 丸めモードが使われます。(「偶数」に最も近い TimeType へ同値を丸めるとはどういうことか、推測するのは難しいでしょう。)利用可能な RoundingMode の詳細は、API reference を参照してください。

丸めは通常、期待どおりに動作しますが、期待される動作が明確でないケースもいくつかあります。

Rounding Epoch

多くの場合、丸め精度(例:Dates.Second(30))は、次に大きい期間(この場合は Dates.Minute(1))を均等に分割できます。しかし、そうならない場合の丸め動作は混乱を招くことがあります。DateTime を最も近い10時間単位に丸めると、どのような結果になるでしょうか。

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 が選ばれています。(これは、Rata Die notation を使った Julia 内部での Date の表現とは少し異なります。ただし、ISO 8601標準のほうがエンドユーザーにとって目にする機会が多いため、混乱を避ける目的で、内部で使われる 0000-12-31T00:00:00 ではなく 0000-01-01T00:00:00 を丸めエポックに選びました。)

丸めエポックに 0000-01-01T00:00:00 を使わない唯一の例外は、週単位の丸めです。最も近い週に丸めると、必ず月曜日(ISO 8601で定められた週の初日)が返されます。そのため、週数への丸めでは、ISO 8601で定義された0000年の第1週の初日である 0000-01-03T00:00:00 を起点として使います。

期待される動作が必ずしも明らかでない関連ケースをもう1つ見てみましょう。P(2)(ここで P は Period 型)に最も近い値へ丸めると、どうなるでしょうか。いくつかのケース(具体的には 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

これらの期間を2つずつまとめても、次に大きい単位の期間を均等に分割できるため、これは明らかに思えます。しかし、2か月の場合(1年を均等に分割できる点は同じです)は、意外な結果になることがあります。

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

月が7(奇数)なのに、なぜ7月1日に丸められるのでしょうか。重要なのは、月は1から数える(最初の月を1とする)のに対し、時・分・秒・ミリ秒は0から数える(最初の値を0とする)ことです。

つまり、秒・分・時・年の偶数倍に DateTime を丸めると(ISO 8601仕様には0年が含まれるため)、そのフィールドの値が偶数の DateTime になります。一方、月の偶数倍に DateTime を丸めると、月フィールドの値は奇数になります。月と年には日数が一定でない場合があるため、日数の偶数倍に丸めたときに日フィールドが偶数になるかどうかは一定しません。

Dates モジュールからエクスポートされるメソッドの詳細については、API reference を参照してください。

API reference

Dates and Time Types

Dates.Period — Type
Period
Year
Quarter
Month
Week
Day
Hour
Minute
Second
Millisecond
Microsecond
Nanosecond

Period 型は、時間を離散的かつ人間が扱いやすい形で表現します。

source
Dates.CompoundPeriod — Type
CompoundPeriod

CompoundPeriodは、より小さな期間の固定倍数では表せない期間を表すのに便利です。たとえば、「1年と1日」は日数の固定値ではありませんが、CompoundPeriodを使って表せます。実際、異なる種類の期間を加算すると、CompoundPeriodが自動的に生成されます。たとえば、Year(1) + Day(1)はCompoundPeriodを返します。

source
Dates.Instant — Type
Instant

Instant 型は、エポックを起点とする連続した時間軸を整数で表現したものです。

source
Dates.UTInstant — Type
UTInstant{T}

UTInstantは、UT時刻に基づく機械時間軸(1日=地球の1回転)を表します。Tは、時点の分解能または精度を示すPeriodパラメーターです。

source
Dates.TimeType — Type
TimeType

TimeType 型は、機械上の時点を人間に分かりやすく表現するため、Instant のインスタンスをラップします。Time、DateTime、Date は、TimeType のサブタイプです。

source
Dates.DateTime — Type
DateTime

DateTimeは、先発グレゴリオ暦における時点を表します。時間の最小単位はミリ秒です(つまり、この型ではマイクロ秒やナノ秒を表現できません)。この型は固定小数点演算をサポートするため、アンダーフローやオーバーフローが発生しやすくなっています。その顕著な例として、MicrosecondまたはNanosecondを加算したときの丸めがあります。

julia> dt = DateTime(2023, 8, 19, 17, 45, 32, 900)
2023-08-19T17:45:32.900

julia> dt + Millisecond(1)
2023-08-19T17:45:32.901

julia> dt + Microsecond(1000) # 1000us == 1ms
2023-08-19T17:45:32.901

julia> dt + Microsecond(999) # 999us rounded to 1000us
2023-08-19T17:45:32.901

julia> dt + Microsecond(1499) # 1499 rounded to 1000us
2023-08-19T17:45:32.901
source
Dates.Date — Type
Date

Date は UTInstant{Day} をラップし、先発グレゴリオ暦に従って解釈します。

source
Dates.Time — Type
Time

Time は Nanosecond をラップし、24時間制の1日の特定の時刻を表します。

source
Dates.TimeZone — Type
TimeZone

経度を基準に、特定の場所の時刻を定める地理的な区域。夏時間を採用しているタイムゾーンもあります(例:EST → EDT)。実装や詳細については、TimeZones.jl パッケージを参照してください。

source
Dates.UTC — Type
UTC

UTC(協定世界時)は、ほかのすべての時刻の基準となるTimeZoneです。経度0°の地点の時刻に対応し、夏時間による調整は行われません。

source

Dates Functions

Dates.DateTime — Method
DateTime(y, [m, d, h, mi, s, ms])::DateTime

DateTime 型を、各パーツから構築します。引数は Int64 に変換可能でなければなりません。

source
Dates.DateTime — Method
DateTime(periods::Period...)::DateTime

Period 型の各要素から DateTime 型を構築します。引数の順序は任意です。指定されていない DateTime の要素には、Dates.default(period) の値がデフォルトで使用されます。

source
Dates.DateTime — Method
DateTime(f::Function, y[, m, d, h, mi, s]; step=Day(1), limit=10000)::DateTime

adjuster API を通じて DateTime を作成します。開始点は、指定された y, m, d... 引数から構築され、f::Function が true を返すまで調整されます。調整時のステップサイズは、step キーワードで手動指定できます。limit は、調整 API がエラーをスローするまでに実行する反復回数の上限を指定します(f::Function が満たされない場合)。

Examples

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

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

Date を DateTime に変換します。新しい DateTime の時、分、秒、ミリ秒の各部分はゼロと仮定されます。

source
Dates.DateTime — Method
DateTime(dt::AbstractString, format::AbstractString; locale="english")

dt の日時文字列を、format 文字列で指定されたパターンに従って解析し、DateTime を構築します(構文については DateFormat を参照してください)。

Note

このメソッドは、呼び出すたびに DateFormat オブジェクトを作成します。同じ書式を繰り返し使用する場合のパフォーマンス低下を避けるため、代わりに DateFormat オブジェクトを作成し、第2引数として使用することをおすすめします。

Examples

julia> DateTime("2020-01-01", "yyyy-mm-dd")
2020-01-01T00:00:00

julia> a = ("2020-01-01", "2020-01-02");

julia> [DateTime(d, dateformat"yyyy-mm-dd") for d ∈ a] # preferred
2-element Vector{DateTime}:
 2020-01-01T00:00:00
 2020-01-02T00:00:00
source
Dates.format — Method
format(dt::TimeType, format::AbstractString; locale="english")::AbstractString

TimeType オブジェクトを使い、指定された format を適用して文字列を構築します。以下の文字コードを使って format 文字列を構築できます。

コード例説明
y6固定幅の数値の年
Y1996最小幅の数値の年
m1, 12最小幅の数値の月
uJanlocale に従った3文字の月名
UJanuarylocale キーワードに従った月の正式名称
d1, 31最小幅の日
H0, 23最小幅の時(24時間制)
M0, 59最小幅の分
S0, 59最小幅の秒
s000, 500最小幅3のミリ秒
eMon, Tue曜日の略称
EMonday曜日の正式名称

コード文字が連続する数によって、コードの幅が決まります。yyyy-mm という形式では、コード y の幅は4、m の幅は2になります。数値を出力するコードには、固定幅または最小幅のモードがあります。固定幅モードでは、値が指定幅より短い場合は左側をゼロで埋め、長い場合は切り詰めます。最小幅モードも固定幅モードと同様ですが、指定幅を超える値を切り詰めません。

format を作成するときは、コード以外の任意の文字を区切り文字として使用できます。たとえば、文字列 "1996-01-15T00:00:00" を生成するには、format: "yyyy-mm-ddTHH:MM:SS" を使用します。コード文字をリテラルとして使う必要がある場合は、エスケープ文字のバックスラッシュを使用できます。文字列 "1996y01m" は、書式 raw"yyyy\ymm\m" で生成できます。

source
Dates.DateFormat — Type
DateFormat(format::AbstractString, locale="english")

日付文字列の解析や、日付オブジェクトの文字列への整形に使用できる日付書式オブジェクトを構築します。format 文字列の構築には、次の文字コードを使用できます。

コード一致する値説明
Y1996, 96それぞれ 1996 年、0096 年を返します
y1996, 96parse では Y と同じですが、format では余分な桁を切り捨てます
m1, 011 桁または 2 桁の月に一致します
uJanlocale キーワードに従って、月名の略称に一致します
UJanuarylocale キーワードに従って、月名の正式名称に一致します
d1, 011 桁または 2 桁の日に一致します
H00時(24 時間制)に一致します
I00時を 12 時間制で出力するために使用します
M00分に一致します
S00秒に一致します
s.500ミリ秒に一致します
eMon, Tues曜日名の略称に一致します
EMonday曜日名の正式名称に一致します
pAMAM/PM に一致します(大文字と小文字を区別しません)
yyyymmdd19960101固定幅の年、月、日に一致します

上記以外の文字は、通常、日付と時刻の各フィールドの区切り文字として扱われます。たとえば、dt 文字列が "1996-01-15T00:00:00.0" の場合、format 文字列は "y-m-dTH:M:S.s" のようになります。コードとして使われる文字を区切り文字として使用するには、バックスラッシュでエスケープします。日付 "1995y01m" の書式は "y\ym\m" となります。

12:00AM は 00:00(真夜中)に、12:00PM は 12:00(正午)に対応することに注意してください。p 指定子を含む時刻を解析する場合、時の指定は H と I のどちらでも 12 時間制として解釈されるため、I コードは主に出力時に役立ちます。

DateFormat オブジェクトの作成にはコストがかかります。可能な限り、一度作成したものを繰り返し使用するか、dateformat"" 文字列マクロを試してください。このマクロを使用すると、マクロ展開時に DateFormat オブジェクトが一度だけ作成され、以降は再利用されます。また、後述する pre-defined formatters もいくつか用意されています。

DateFormat オブジェクトを使用して Date 文字列を解析する方法については DateTime を、書き出す方法については format を参照してください。

source
Dates.@dateformat_str — Macro
dateformat"Y-m-d H:M:S"

DateFormat オブジェクトを作成します。DateFormat("Y-m-d H:M:S") と似ていますが、マクロ展開時に DateFormat オブジェクトを一度だけ作成します。

書式指定子の詳細については、DateFormat を参照してください。

source
Dates.DateTime — Method
DateTime(dt::AbstractString, df::DateFormat=ISODateTimeFormat)

dtの日付時刻文字列を、DateFormatオブジェクトで指定されたパターン(省略時はdateformat"yyyy-mm-dd\THH:MM:SS.s")に従って解析し、DateTimeを構築します。

DateTime(::AbstractString, ::AbstractString)と同様ですが、あらかじめ作成したDateFormatオブジェクトを使うため、同じ形式の日付時刻文字列を繰り返し解析する場合に、より効率的です。

source
Dates.Date — Method
Date(y, [m, d])::Date

Int64 に変換可能な引数を使って、Date 型を部分ごとに構築します。

source
Dates.Date — Method
Date(period::Period...)::Date

Period 型の各要素から Date 型を構築します。引数の順序は任意です。指定されていない Date 要素には、Dates.default(period) の値がデフォルトで設定されます。

source
Dates.Date — Method
Date(f::Function, y[, m, d]; step=Day(1), limit=10000)::Date

adjuster API を通じて Date を作成します。開始点は、指定された y, m, d 引数から構築され、f::Function が true を返すまで調整されます。調整時のステップサイズは、step キーワードで手動指定できます。limit は、f::Function が満たされない場合に、エラーをスローするまで調整 API が実行する反復回数の上限を指定します。

Examples

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

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

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

DateTimeをDateに変換します。DateTimeの時、分、秒、ミリ秒の各部分は切り捨てられるため、構築には年、月、日の部分のみが使用されます。

source
Dates.Date — Method
Date(d::AbstractString, format::AbstractString; locale="english")

dの日付文字列を、format文字列で指定されたパターンに従って解析し、Dateを構築します(構文についてはDateFormatを参照)。

Note

このメソッドは、呼び出すたびにDateFormatオブジェクトを作成します。同じフォーマットを繰り返し使用する際のパフォーマンス低下を避けるため、代わりにDateFormatオブジェクトを作成し、それを第2引数として使用することをおすすめします。

Examples

julia> Date("2020-01-01", "yyyy-mm-dd")
2020-01-01

julia> a = ("2020-01-01", "2020-01-02");

julia> [Date(d, dateformat"yyyy-mm-dd") for d ∈ a] # preferred
2-element Vector{Date}:
 2020-01-01
 2020-01-02
source
Dates.Date — Method
Date(d::AbstractString, df::DateFormat=ISODateFormat)

dの日付文字列を、DateFormatオブジェクトで指定されたパターン(省略時はdateformat"yyyy-mm-dd")に従って解析し、Dateを構築します。

Date(::AbstractString, ::AbstractString)と同様ですが、あらかじめ作成したDateFormatオブジェクトを使うため、同じ形式の日付文字列を繰り返し解析する場合により効率的です。

source
Dates.Time — Method
Time(h, [mi, s, ms, us, ns])::Time

Int64 に変換可能な引数を使って、Time 型を部分ごとに構築します。

source
Dates.Time — Method
Time(period::TimePeriod...)::Time

Period 型のパーツから Time 型を構築します。引数の順序は任意です。指定されていない Time パーツには、Dates.default(period) の値がデフォルトで設定されます。

source
Dates.Time — Method
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)

adjuster API を使って Time を作成します。開始点は、指定された h, mi, s, ms, us 引数から構築され、f::Function が true を返すまで調整されます。調整時のステップ幅は、step キーワードで手動指定できます。limit は、調整 API がエラーをスローするまでに実行する反復回数の上限を指定します(f::Function が一度も満たされない場合)。なお、デフォルトのステップ幅は、指定された引数に応じてより高い精度が得られるよう調整されます。たとえば、時、分、秒の引数が指定されている場合、デフォルトのステップ幅は Second(1) ではなく Millisecond(1) になります。

Examples

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

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

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

DateTimeをTimeに変換します。DateTimeの時、分、秒、ミリ秒の各部分を使って、新しいTimeを作成します。マイクロ秒とナノ秒は、デフォルトでゼロです。

source
Dates.Time — Method
Time(t::AbstractString, format::AbstractString; locale="english")

Timeを、format文字列で指定されたパターンに従ってt時刻文字列を解析することで構築します(構文についてはDateFormatを参照)。

Note

このメソッドは呼び出すたびにDateFormatオブジェクトを作成します。同じ書式を繰り返し使用する際のパフォーマンス低下を避けるため、代わりにDateFormatオブジェクトを作成し、それを第2引数として使用することをおすすめします。

Examples

julia> Time("12:34pm", "HH:MMp")
12:34:00

julia> a = ("12:34pm", "2:34am");

julia> [Time(d, dateformat"HH:MMp") for d ∈ a] # preferred
2-element Vector{Time}:
 12:34:00
 02:34:00
source
Dates.Time — Method
Time(t::AbstractString, df::DateFormat=ISOTimeFormat)

t の日時文字列を、DateFormat オブジェクトで指定されたパターン(省略時は dateformat"HH:MM:SS.s")に従って解析し、Time を構築します。

Time(::AbstractString, ::AbstractString) と似ていますが、あらかじめ作成した DateFormat オブジェクトを使って、同じ形式の時刻文字列を繰り返し解析する場合に、より効率的です。

source
Dates.now — Method
now()::DateTime

ユーザーのシステム時刻とシステムのタイムゾーンロケールに対応する DateTime を返します。

source
Dates.now — Method
now(::Type{UTC})::DateTime

ユーザーのシステム時刻に対応するUTC/GMTのDateTimeを返します。その他のタイムゾーンについては、TimeZones.jlパッケージを参照してください。

Examples

julia> now(UTC)
2023-01-04T10:52:24.864
source
Base.eps — Method
eps(::Type{DateTime})::Millisecond
eps(::Type{Date})::Day
eps(::Type{Time})::Nanosecond
eps(::TimeType)::Period

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

Examples

julia> eps(DateTime)
1 millisecond

julia> eps(Date)
1 day

julia> eps(Time)
1 nanosecond
source

Accessor Functions

Dates.year — Function
year(dt::TimeType)::Int64

Date または DateTime の年を Int64 として。

source
Dates.week — Function
week(dt::TimeType)::Int64

ISO week date を Date または DateTime の Int64 として返します。年の第1週は、その年の最初の木曜日を含む週です。そのため、1月4日より前の日付が前年の最終週に含まれる場合があります。たとえば、week(Date(2005, 1, 1)) は2004年の第53週です。

Examples

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

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

julia> week(Date(2004, 12, 31))
53
source
Dates.day — Function
day(dt::TimeType)::Int64

DateまたはDateTimeの月内の日付を、Int64として。

source
Dates.hour — Function
hour(dt::DateTime)::Int64

DateTime の時刻を Int64 として取得します。

source
hour(t::Time)::Int64

Time の時刻を Int64 として。

source
Dates.Year — Method
Year(v)

指定された v 値を持つ Year オブジェクトを構築します。入力は Int64 に損失なく変換できる必要があります。

source
Dates.Month — Method
Month(v)

指定されたvの値を持つMonthオブジェクトを構築します。入力はInt64に損失なく変換できる必要があります。

source
Dates.Week — Method
Week(v)

指定されたvの値を持つWeekオブジェクトを構築します。入力は、損失なくInt64に変換できる必要があります。

source
Dates.Day — Method
Day(v)

指定されたvの値を持つDayオブジェクトを構築します。入力はInt64に損失なく変換できる必要があります。

source
Dates.Hour — Method
Hour(dt::DateTime)

DateTime の時を表す部分。Hour。

source
Dates.Minute — Method
Minute(dt::DateTime)

DateTime の分の部分を表す Minute。

source
Dates.Second — Method
Second(dt::DateTime)

DateTime の第 2 部分は Second です。

source
Dates.Nanosecond — Method
Nanosecond(dt::Time)

Time のナノ秒部分は、Nanosecond として表されます。

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

Date または DateTime の年と月の部分を同時に返します。

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

Date または DateTime の月と日の部分を同時に返します。

source
Dates.yearmonthday — Function
yearmonthday(dt::TimeType) -> (Int64, Int64, Int64)

Date または DateTime の年、月、日を同時に返します。

source

Query Functions

Dates.dayname — Function
dayname(dt::TimeType; locale="english")::String
dayname(day::Integer; locale="english")::String

指定されたlocaleにおけるDateまたはDateTimeの曜日を、曜日名(省略なし)で返します。Integerも受け付けます。

Examples

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

julia> dayname(4)
"Thursday"
source
Dates.dayabbr — Function
dayabbr(dt::TimeType; locale="english")::String
dayabbr(day::Integer; locale="english")::String

指定されたlocaleにおけるDateまたはDateTimeの曜日の略称を返します。Integerも受け付けます。

Examples

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

julia> dayabbr(3)
"Wed"
source
Dates.dayofweek — Function
dayofweek(dt::TimeType)::Int64

曜日を 1 = Monday, 2 = Tuesday, etc. として返します(Int64)。

Examples

julia> dayofweek(Date("2000-01-01"))
6
source
Dates.dayofweekofmonth — Function
dayofweekofmonth(dt::TimeType)::Int

dt の曜日が、dt の月の何回目に当たるかを返します。たとえば、dt の曜日が月曜日なら、1 = First Monday of the month, 2 = Second Monday of the month, etc. は 1:5 の範囲になります。

Examples

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

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

julia> dayofweekofmonth(Date("2000-02-15"))
3
source
Dates.daysofweekinmonth — Function
daysofweekinmonth(dt::TimeType)::Int

dtの曜日が、dtの月に何回あるかを返します。戻り値は4または5です。調整関数にdayofweekofmonth(dt) == daysofweekinmonth(dt)を含めることで、その月の最終週の曜日を指定する時間式に便利です。

Examples

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

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

指定されたlocaleに含まれるDate、DateTime、またはIntegerの月名を、省略せずに返してください。

Examples

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

julia> monthname(2)
"February"
source
Dates.monthabbr — Function
monthabbr(dt::TimeType; locale="english")::String
monthabbr(month::Integer, locale="english")::String

指定されたlocaleに含まれるDate、DateTime、またはIntegerの月の略称を返します。

Examples

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

julia> monthabbr(2)
"Feb"
source
Dates.daysinmonth — Function
daysinmonth(dt::TimeType)::Int

dtの月の日数を返します。値は28、29、30、または31です。

Examples

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

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

julia> daysinmonth(Date("2000-02"))
29
source
Dates.isleapyear — Function
isleapyear(dt::TimeType)::Bool

trueを返します。dtの年がうるう年の場合です。

Examples

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

julia> isleapyear(Date("2005"))
false
source
Dates.dayofyear — Function
dayofyear(dt::TimeType)::Int

dtについて、1月1日を1日目として、その年の何日目かを返します。

source
Dates.daysinyear — Function
daysinyear(dt::TimeType)::Int

dtの年がうるう年の場合は366を返し、そうでない場合は365を返します。

Examples

julia> daysinyear(1999)
365

julia> daysinyear(2000)
366
source
Dates.quarterofyear — Function
quarterofyear(dt::TimeType)::Int

dt が属する四半期を返します。値の範囲は 1:4 です。

source
Dates.dayofquarter — Function
dayofquarter(dt::TimeType)::Int

dtの現在の四半期における日数を返します。値の範囲は1:92です。

source

Adjuster Functions

Base.trunc — Method
trunc(dt::TimeType, ::Type{Period})::TimeType

指定されたPeriod型に従って、dtの値を切り詰めます。

Examples

julia> trunc(DateTime("1996-01-01T12:30:00"), Day)
1996-01-01T00:00:00
source
Dates.firstdayofweek — Function
firstdayofweek(dt::TimeType)::TimeType

dtを、その週の月曜日に調整します。

Examples

julia> firstdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-01T00:00:00
source
Dates.lastdayofweek — Function
lastdayofweek(dt::TimeType)::TimeType

dt を、その週の日曜日に調整します。

Examples

julia> lastdayofweek(DateTime("1996-01-05T12:30:00"))
1996-01-07T00:00:00
source
Dates.firstdayofmonth — Function
firstdayofmonth(dt::TimeType)::TimeType

dtを、その月の1日に調整します。

Examples

julia> firstdayofmonth(DateTime("1996-05-20"))
1996-05-01T00:00:00
source
Dates.lastdayofmonth — Function
lastdayofmonth(dt::TimeType)::TimeType

dtを、その月の最終日に調整します。

Examples

julia> lastdayofmonth(DateTime("1996-05-20"))
1996-05-31T00:00:00
source
Dates.firstdayofyear — Function
firstdayofyear(dt::TimeType)::TimeType

dtを、その年の初日に調整します。

Examples

julia> firstdayofyear(DateTime("1996-05-20"))
1996-01-01T00:00:00
source
Dates.lastdayofyear — Function
lastdayofyear(dt::TimeType)::TimeType

dt を、その年の最終日に調整します。

Examples

julia> lastdayofyear(DateTime("1996-05-20"))
1996-12-31T00:00:00
source
Dates.firstdayofquarter — Function
firstdayofquarter(dt::TimeType)::TimeType

dtを、その四半期の初日に調整します。

Examples

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

julia> firstdayofquarter(DateTime("1996-08-20"))
1996-07-01T00:00:00
source
Dates.lastdayofquarter — Function
lastdayofquarter(dt::TimeType)::TimeType

dtを、その四半期の最終日に調整します。

Examples

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

julia> lastdayofquarter(DateTime("1996-08-20"))
1996-09-30T00:00:00
source
Dates.tonext — Method
tonext(dt::TimeType, dow::Int; same::Bool=false)::TimeType

dtを、1 = Monday, 2 = Tuesday, etcを基準として、dowに該当する次の曜日に調整します。same=trueを設定すると、現在のdtを次のdowとみなせるため、調整が行われない場合があります。

source
Dates.toprev — Method
toprev(dt::TimeType, dow::Int; same::Bool=false)::TimeType

dowに対応する曜日のうち、1 = Monday, 2 = Tuesday, etcを基準に前の日へdtを調整します。same=trueを設定すると、現在のdtを前のdowとみなせるため、調整が行われない場合があります。

source
Dates.tofirst — Function
tofirst(dt::TimeType, dow::Int; of=Month)::TimeType

dtを、その月の最初のdowに調整します。あるいは、of=Yearを、その年の最初のdowに調整します。

source
Dates.tolast — Function
tolast(dt::TimeType, dow::Int; of=Month)::TimeType

dtを、その月の最後のdowに調整します。あるいは、of=Yearを、その年の最後のdowに調整します。

source
Dates.tonext — Method
tonext(func::Function, dt::TimeType; step=Day(1), limit=10000, same=false)::TimeType

dtを、funcがtrueを返すまで、stepずつ増やしながら、最大limit回の反復で調整します。funcは、引数をTimeTypeひとつだけ取り、Boolを返す必要があります。sameを使うと、funcを満たすかどうかの判定にdtを考慮できます。

source
Dates.toprev — Method
toprev(func::Function, dt::TimeType; step=Day(-1), limit=10000, same=false)::TimeType

func が true を返すまで、最大 limit 回の反復で step ずつ増加させて dt を調整します。func は、単一の TimeType 引数を受け取り、Bool を返す必要があります。same を使用すると、func を満たすかどうかの判定で dt を考慮できます。

source

Periods

Dates.Period — Method
Year(v)
Quarter(v)
Month(v)
Week(v)
Day(v)
Hour(v)
Minute(v)
Second(v)
Millisecond(v)
Microsecond(v)
Nanosecond(v)

指定された v 値を持つ Period 型を構築します。入力は Int64 に損失なく変換できる必要があります。

source
Dates.CompoundPeriod — Method
CompoundPeriod(periods)

VectorのPeriodからCompoundPeriodを構築します。同じ型のPeriodはすべて加算されます。

Examples

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

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

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

julia> Dates.CompoundPeriod(Dates.Minute(50000))
50000 minutes
source
Dates.canonicalize — Function
canonicalize(::CompoundPeriod)::CompoundPeriod

次の規則を適用して、CompoundPeriodを標準形に変換します。

  • より粗いPeriodで一部を表現できるほど大きなPeriodは、複数のPeriodに分割されます(例:Hour(30)はDay(1) + Hour(6)になります)。
  • 符号が反対のPeriodは、可能な場合にまとめられます(例:Hour(1) - Day(1)は-Hour(23)になります)。

Examples

julia> canonicalize(Dates.CompoundPeriod(Dates.Hour(12), Dates.Hour(13)))
1 day, 1 hour

julia> canonicalize(Dates.CompoundPeriod(Dates.Hour(-1), Dates.Minute(1)))
-59 minutes

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

julia> canonicalize(Dates.CompoundPeriod(Dates.Minute(50000)))
4 weeks, 6 days, 17 hours, 20 minutes
source
Dates.value — Function
Dates.value(x::Period)::Int64

指定した期間に対応する値を返します。たとえば、value(Millisecond(10))は整数の10を返します。

source
Dates.default — Function
default(p::Period)::Period

入力された Period に対して、Year、Month、Day では T(1) を、Hour、Minute、Second、Millisecond では T(0) を返し、妥当な「デフォルト」値を返します。

source
Dates.periods — Function
Dates.periods(::CompoundPeriod)::Vector{Period}

指定されたPeriodsを構成するCompoundPeriodのVectorを返します。

Julia 1.7

この関数を使用するには、Julia 1.7以降が必要です。

source

Rounding Functions

Date と DateTime の値は、floor、ceil、または round を使って、指定した精度(例:1か月、15分)に丸めることができます。

Base.floor — Method
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), Month)
1985-08-01

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

julia> floor(DateTime(2016, 8, 6, 12, 0, 0), Day)
2016-08-06T00:00:00
source
Base.ceil — Method
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), Month)
1985-09-01

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

julia> ceil(DateTime(2016, 8, 6, 12, 0, 0), Day)
2016-08-07T00:00:00
source
Base.round — Method
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), Month)
1985-08-01

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

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

round(::TimeType, ::Period, ::RoundingMode)で有効な丸めモードは、RoundNearestTiesUp(デフォルト)、RoundDown(floor)、およびRoundUp(ceil)です。

source

ほとんどの Period 値も、指定した精度に丸めることができます。

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

xを、precisionの最も近い倍数に切り下げます。xとprecisionがPeriodの異なるサブタイプである場合、戻り値の型はprecisionと同じになります。

便宜上、precisionには値の代わりに型を指定できます。floor(x, Dates.Hour)はfloor(x, Dates.Hour(1))の省略形です。

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

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

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

MonthまたはYearのprecisionへの丸めはサポートされていません。これらのPeriodの長さが一定ではないためです。

source
Base.ceil — Method
ceil(x::Period, precision::T) where T <: Union{TimePeriod, Week, Day} -> T

xを、precisionの最も近い倍数に切り上げます。xとprecisionがPeriodの異なるサブタイプである場合、戻り値の型はprecisionと同じになります。

便宜上、precisionには値ではなく型を指定できます。ceil(x, Dates.Hour)はceil(x, Dates.Hour(1))の省略形です。

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

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

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

precisionをMonthまたはYearにする丸めはサポートされていません。これらのPeriodの長さは一定ではないためです。

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

xを、最も近いprecisionの倍数に丸めます。xとprecisionがPeriodの異なるサブタイプである場合、戻り値の型はprecisionと同じになります。デフォルト(RoundNearestTiesUp)では、ちょうど中間の値(例:90分を最も近い時間に丸める場合)は切り上げられます。

便宜上、precisionには値ではなく型を指定できます。round(x, Dates.Hour)はround(x, Dates.Hour(1))の省略形です。

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

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

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

round(::Period, ::T, ::RoundingMode)で有効な丸めモードは、RoundNearestTiesUp(デフォルト)、RoundDown(floor)、およびRoundUp(ceil)です。

precisionをMonthまたはYearの単位に丸めることはできません。これらのPeriodは長さが一定ではないためです。

source

次の関数はエクスポートされません。

Dates.floorceil — Function
floorceil(dt::TimeType, p::Period) -> (TimeType, TimeType)

解像度pで、DateまたはDateTimeのfloorとceilを同時に返します。floorとceilを個別に呼び出すより効率的です。

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

Periodをpの解像度で処理し、floorとceilを同時に返します。floorとceilを個別に呼び出すより効率的です。

source
Dates.epochdays2date — Function
epochdays2date(days)::Date

丸めの基準時点からの日数(0000-01-01T00:00:00)を受け取り、対応するDateを返します。

source
Dates.epochms2datetime — Function
epochms2datetime(milliseconds)::DateTime

丸めの基準時点からの経過ミリ秒数(0000-01-01T00:00:00)を受け取り、対応するDateTimeを返します。

source
Dates.date2epochdays — Function
date2epochdays(dt::Date)::Int64

指定されたDateを受け取り、丸めの基準時点(0000-01-01T00:00:00)からの日数をInt64として返します。

source
Dates.datetime2epochms — Function
datetime2epochms(dt::DateTime)::Int64

与えられたDateTimeを受け取り、丸めの基準時刻(0000-01-01T00:00:00)からの経過ミリ秒数をInt64として返します。

source

Conversion Functions

Dates.unix2datetime — Function
unix2datetime(x)::DateTime

Unixエポックからの経過秒数 1970-01-01T00:00:00 を、対応する DateTime に変換します。

source
Dates.datetime2unix — Function
datetime2unix(dt::DateTime)::Float64

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

source
Dates.julian2datetime — Function
julian2datetime(julian_days)::DateTime

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

source
Dates.datetime2julian — Function
datetime2julian(dt::DateTime)::Float64

指定されたDateTimeを受け取り、ユリウス暦の元期-4713-11-24T12:00:00からのユリウス暦日数をFloat64として返します。

source
Dates.rata2datetime — Function
rata2datetime(days)::DateTime

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

source
Dates.datetime2rata — Function
datetime2rata(dt::TimeType)::Int64

指定されたDateまたはDateTimeから、エポック以降のRata Die日数を返します。

source

Constants

曜日:

変数略称値(整数)
MondayMon1
TuesdayTue2
WednesdayWed3
ThursdayThu4
FridayFri5
SaturdaySat6
SundaySun7

月:

変数略称値(整数)
JanuaryJan1
FebruaryFeb2
MarchMar3
AprilApr4
MayMay5
JuneJun6
JulyJul7
AugustAug8
SeptemberSep9
OctoberOct10
NovemberNov11
DecemberDec12

Common Date Formatters

Dates.ISODateTimeFormat — Constant
Dates.ISODateTimeFormat

日付と時刻の ISO 8601 形式を表します。これは、DateTime の Dates.format のデフォルト値です。

Examples

julia> Dates.format(DateTime(2018, 8, 8, 12, 0, 43, 1), ISODateTimeFormat)
"2018-08-08T12:00:43.001"
source
Dates.ISODateFormat — Constant
Dates.ISODateFormat

日付の ISO 8601 形式を指定します。これは、Date の Dates.format のデフォルト値です。

Examples

julia> Dates.format(Date(2018, 8, 8), ISODateFormat)
"2018-08-08"
source
Dates.ISOTimeFormat — Constant
Dates.ISOTimeFormat

時刻の ISO8601 形式を表します。これは、Dates.format の Time におけるデフォルト値です。

Examples

julia> Dates.format(Time(12, 0, 43, 1), ISOTimeFormat)
"12:00:43.001"
source
Dates.RFC1123Format — Constant
Dates.RFC1123Format

日付と時刻のRFC1123形式について説明します。

Examples

julia> Dates.format(DateTime(2018, 8, 8, 12, 0, 43, 1), RFC1123Format)
"Wed, 08 Aug 2018 12:00:43"
source
  • 1UT秒という概念は、実は非常に基本的なものです。一般に受け入れられている時間の考え方は大きく2つあります。地球の物理的な自転(1回転を1日とする)に基づくものと、SI秒(固定された一定の値)に基づくものです。この2つは大きく異なります。地球の自転に対して定義される「UT秒」は、日によって絶対的な長さが異なる可能性があることを考えてみてください。いずれにせよ、Date と DateTime がUT秒に基づいているのは、うるう秒などの複雑さを避けるための、簡略化でありながら誠実な前提です。この時間の基準は、正式には UT(UT1)と呼ばれます。型をUT秒に基づかせると、各分は60秒、各日は24時間となり、暦日を扱う際により自然な計算ができます。