本エントリではDateTime
クラスの使用方法を説明する。
DateTimeとは
日付と時刻に関する情報を扱うクラス。UNIXエポックの1970年1月1日から100,000,000日以内の時刻を扱える。
インスタンス生成
DateTime
インスタンスを生成するには以下の2通りの方法がある。
- コンストラクタを利用
- 文字列をパース
以下でそれぞれを説明する。
コンストラクタを利用
DateTime()
コンストラクタDateTime()
を使用することで、マイクロ秒まで指定したインスタンスを生成する。
各桁は値が指定されない場合0になる。
DateTime.now()
名前付きコンストラクタDateTime.now()
を使用することで、生成を行なった時刻をマイクロ秒まで指定したインスタンスを生成する。
DateTime.utc()
名前付きコンストラクタDateTime.utc()
を使用することで、タイムゾーンをUTCとした時刻でインスタンスを生成する。
タイムゾーンをUTCに指定しているのでprint()
出力した値の末尾にZ
がついている。
ちなみにDateTime.utc()
を使用しない場合、生成されるインスタンスが保有する時刻のタイムゾーンはローカルのものになる。
文字列をパース
文字列をパースする際はDateTime.parse()
に指定のフォーマットで文字列を渡す必要がある。
このフォーマットはISO 8601。上記のコード以外にもISO 8601の記法がいくつかあるので 以下のサイトなどを参考にお好みのフォーマットを選んでいただきたい。
プロパティ
DateTime
インスタンスで利用できる主なプロパティを以下で説明する。
すべてのプロパティはこちら。
各時刻桁
年 ~ マイクロ秒 までそれぞれの値を取得できる。
isUtc
DateTime
インスタンスのタイムゾーンがUTCの場合true
、それ以外はfalse
になる。
timeZoneName
DateTime
インスタンスのタイムゾーン名が取得できる。
このタイムゾーンはプログラムが動作するOSから取得する。
timeZoneOffset
DateTime
インスタンスのタイムゾーンの時差を取得できる。
上記コードはタイムゾーンがJSTなので時差は9時間となっている。
weekday
DateTime
インスタンスの曜日を数値で取得できる。
月曜日が1に対応し、日曜日まで1ずつ増える。
日付と時刻の操作
DateTime
インスタンスはDuration
を用いることで
- 時間を足す
- 時間を引く
の操作を行うことができる。
また複数のDateTime
インスタンスを用いて次の操作が可能。
- 一致を確認
- 差分を取得
- 時刻の前後関係を取得
以下でそれぞれの操作を説明する。
時間を足す
add()
メソッドを用いる。
引数にはDuration
インスタンスを渡し、足し合わせる時間を設定する。
時間を引く
subtract()
メソッドを用いる。
引数にはDuration
インスタンスを渡し、引く時間を設定する。
一致・不一致を確認
compareTo()
メソッドを用いる。
引数には比較したいDateTime
インスタンスを渡す。
時刻が同じ場合0、異なる場合は前後関係によって1または-1が返される。
差分を取得
difference()
メソッドを用いる。
上記コードではプログラム実行時の時刻がベルリンの壁崩壊時からどれくらい経ったかを求めている。
戻り値はDuration
クラスなので、inDays
などのプロパティで日などに単位を換算できる。
時刻の前後関係を取得
isAfter()
またはisBefore()
を用いることで求められる。
それぞれ比較したいDateTime
インスタンスを引数に渡し、isAfter()
の場合引数に渡されたインスタンスの時刻よりthis
インスタンスが進んでいればtrue
、遅れていればfaluse
となる。isBefore()
メソッドではその関係が逆になる。
フォーマットを指定して日時を表示する
intl
パッケージを使用することで、フォーマットを指定して日時を表示することができる。
フォーマットはオブジェクトとして扱えるので、特定のフォーマットで日時を何度も表示する場合はintl
パッケージを使用した方が楽。
インストール
通常のパッケージと同様にpubspec.yamlに以下の記述をする。
フォーマットの指定
DateFormat
クラスを用いる。
例えば日時を「2020年10月4日 7:20」というフォーマットで表示したい場合、以下のように記述する。
この時、各桁を表す文字列(年桁だったらyyyyなど)はsymbolと呼ばれる。 symbol一覧はこちら。
フォーマットを指定したらformat()
メソッドで引数に表示したいDateTime
インスタンスを渡す。