[標準クラス]DateTimeクラスで日付と時刻の処理

Dartで日付や時刻を取り扱うには、標準で提供されているDateTimeクラスを利用します。
チートシートのように端的にまとめてみました。早速、用途ごとに使い方を見ていきましょう。

現在の時刻を取得する

現在の日時を取得するためにはnow()を使用します。

final today = DateTime.now();
print(today);
// 2022-02-21 22:07:35.120 というDateTimeのインスタンスを取得する

任意の時刻を作成する

DateTimeの引数にお好きなyear,monthなどを指定していくと、任意の時刻のインスタンスを作ることができます。

// year, month, day, hour, minute, secondを指定する
final day = DateTime(1867, 11, 9, 11, 30, 30);
print(day); // 1867-11-09 11:30:30.000

時刻を省略して日付だけでも可能です。

final day = DateTime(1867, 11, 9);
print(day); // 1867-11-09 00:00:00.000

文字列に変換する

書式にこだわりなく、ただ文字列に変換したいときはtoString()をすれば文字列になります。
たとえば一時的に時刻を文字列として保管しておき、後述するparseで読み込んで使うようなケースの場合は有効です。

final day = DateTime(1867, 11, 9, 12, 23, 34);
print(day.toString()); // '1867-11-09 12:23:34.000'

書式を指定して文字列に変換する

取得した日時を任意のフォーマットで文字列に変換するためには、yearやhourなどDateTimeのインスタンスから部分的に切り出して、文字列に当てはめるのが良さそうです。

final today = DateTime.now();
print('${today.year}-${today.month}-${today.day} ${today.hour}:${today.minute}:${today.second}');
// 2022-2-21 22:7:35 という文字列が手に入る

一桁のときに二桁目をゼロで埋めたいときは以下のように文字列に変換し、padLeftを使うとよいです。
ここではmonthのみゼロパディングしています。

final today = DateTime.now();
final month = today.month.toString().padLeft(2, '0');
print('${today.year}-$month-${today.day} ${today.hour}:${today.minute}:${today.second}');
// 2022-02-21 22:7:35 という文字列が手に入る

もし、他の言語にあるようなYYYYMMDDなど文字列で書式を指定して使いたいような場合はintlというパッケージをインストールすると同じことがDartでも可能になります。

文字列から時間に変換する

所定の文字列から時刻に変換したい、というのもよくあることです。
parseを利用すると文字列からDateTimeのインスタンスに変換可能です。

final timeText = '1979-11-08 17:35:32';
final time = DateTime.parse(timeText);
print(time.year); // 1979を取得できる

変換可能な文字列のパターンはparseメソッドの仕様ページに例として記載されています。

時間の加算・減算をする

ある時間を基準に足し引きも簡単にできます。
例えば今から3日後の日付を取得したいときはaddメソッドを使います。

final today = DateTime(2021, 2, 2, 11, 30, 30);
final after3Days = today.add(Duration(days: 3));
print(after3Days); // 2021-02-05 11:30:30.000

Duration(days: 3)みたいな書き方ができるのは大変便利ですね。
days:をhours:にすると3時間後の時間が出てきます。

final today = DateTime(2021, 2, 2, 11, 30, 30);
final after3Hours = today.add(Duration(hours: 3));
print(after3Hours); // 2021-02-02 14:30:30.000

他にもminutes:やseconds:、milliseconds:、microseconds:まで指定できます。

一方でsubtractを使うとある時間を基準に過去の時間を求めることが可能です。

final today = DateTime(2021, 2, 2, 11, 30, 30);
final yesterday = today.subtract(Duration(days: 1));
print(yesterday); // 2021-02-01 11:30:30.000

時間の差分を取得する

二つの時刻の差分を取得するにはdifferenceを使用します。
差分はinDaysやinHoursといったメソッドを使用することでお好みの時刻の単位を指定して取得することができます。
これはかなり便利ですね。各単位に換算したときに余りが発生したときは切り捨てになります。

final time1 = DateTime(2021, 2, 2, 11, 30, 30);
final time2 = DateTime(2021, 2, 4, 12, 35, 30);
final diffTime = time2.difference(time1);

print(diffTime.inDays); // 2
print(diffTime.inHours); // 49
print(diffTime.inMinutes); // 2945
print(diffTime.inSeconds); // 176700

時間を比較する

isAfterやisBeforeを使うと、二つのDateTimeインスタンスの大小を比較することができます。
どちらが未来日付か？みたいな処理はよくやりますね。

final time1 = DateTime(2021, 2, 2, 11, 30, 30);
final time2 = DateTime(2021, 2, 4, 12, 35, 30);

print(time1.isAfter(time2)); // false
print(time1.isBefore(time2)); // true

DateTimeはかなり使いやすく、便利なクラスだと使ってみて思いました。
日付や時刻の処理でやりたいことはほぼ実現できるのではないでしょうか。

オフィシャルの仕様ページもかなりわかりやすくまとめられています。
このページで紹介していないメソッドもあるので、一度目を通してみるとよいかもしれません。