日付時刻フォーマッター

Javaの日付時刻APIのDateTimeFormatterについて。

概要

日付時刻オブジェクトを文字列に整形（format）、あるいは逆に文字列から日付時刻オブジェクトを生成（parse）するにはjava.time.format.DateTimeFormatterを使う。
（従来はjava.text.SimpleDateFormatを使っていた）

DateTimeFormatterは不変オブジェクトであり、スレッドセーフである。
ただし、シリアライズ可能ではない。（SimpleDateFormatはシリアライズ可能だったが）[2017-07-26]

import java.time.format.DateTimeFormatter;

DateTimeFormatterインスタンスの生成

DateTimeFormatterインスタンスは、基本的にofPatternメソッドで生成する。

import java.time.format.DateTimeFormatter;

他に、with系メソッドを使って属性を変更することが出来る。
→リゾルバースタイル

内部ではDateTimeFormatterBuilderを使っており、これを直接使ってDateTimeFormatterオブジェクトを作ってもいい。

DateTimeFormatterインスタンスの生成時間

従来 日付の整形や解析に使っていたSimpleDateFormatは、スレッドセーフではなかった。
マルチスレッドで同期化せずに使うのに一番簡単な方法は「使う度に毎回インスタンスを生成する」ことだが、インスタンス生成も重い（実行時間が遅い）部類だった。

DateTimeFormatterはスレッドセーフなので、staticフィールドに定義しておいてマルチスレッドで使うことが出来る。
ついでに、インスタンス生成もSimpleDateFormatより軽い。

整形（format）に関してはSimpleDateFormatより速いような遅いような微妙な感じだが、
解析（parse）もDateTimrFormatterの方が速い。

	static void loop() throws InterruptedException, ParseException {
		// SimpleDateFormat sdf = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss.SSS");
		// Date date = new Date();

		// DateTimeFormatter dtf = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss.SSS");
		// ZonedDateTime date = ZonedDateTime.now();

		long total = 0;
		for (int n = 0; n < 10; n++) {
			long s = System.currentTimeMillis();

			for (int i = 0; i < 100_0000; i++) {
				new SimpleDateFormat("yyyy/MM/dd HH:mm:ss.SSS");
				// DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss.SSS");
				// sdf.format(date);
				// dtf.format(date);
				// sdf.parse("2014/07/21 14:05:31.789");
				// dtf.parse("2014/07/21 14:05:31.789");
			}

			long e = System.currentTimeMillis();
			long t = e - s;
			System.out.println(t);
			total += t;

			System.gc();
			Thread.sleep(1000);
		}

		System.out.println("----");
		System.out.println(total / 10);
	}

日付時刻オブジェクトから文字列へ整形する例

日付時刻オブジェクトから文字列へ整形するには、日付時刻クラスのformatメソッドを使う方法と、DateTimeFormatterのformatメソッドを使う方法がある。
日付時刻クラスのformatメソッドも内部ではDateTimeFormatterのformatメソッドを呼び出しているが、分かりやすさから言うと前者の方法を使う方が良さそう。
（解析（parse）するときも日付時刻クラスのparseメソッドを使う方が良いので、日付時刻クラスのメソッドを呼ぶ方が統一がとれる）

import java.time.*;
import java.time.format.DateTimeFormatter;

// 日付時刻クラスのformatメソッドを使う方法
		ZonedDateTime zonedDateTime = ZonedDateTime.now();
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss.SSSxxxxx VV");
		String s = zonedDateTime.format(formatter);

// DateTimeFormatterのformatメソッドを使う方法
		ZonedDateTime zonedDateTime = ZonedDateTime.now();
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss.SSSxxxxx VV");
		String s = formatter.format(zonedDateTime);

文字列を解析して日付時刻オブジェクトを生成する例

文字列を解析して日付時刻オブジェクトを生成するには、日付時刻クラスのparseメソッドを使う方法と、DateTimeFormatterのparseメソッドを使う方法がある。
日付時刻クラスのparseメソッドも内部ではDateTimeFormatterのparseメソッドを呼び出しているが、前者の方が戻り値のクラスがはっきりするので、基本的には前者の方法を使うのが良さそう。
ただし、 エラーチェック等を行いたい場合はDateTimeFormatterのparseメソッドを使った方が良さそう。
（→DateTimeFormatterのparseUnresolvedメソッド）

なお、解析に失敗するとjava.time.DateTimeExceptionが発生するが、この例外は非チェック例外（RuntimeException）である。
（SimpleDateFormat#parse()はParseExceptionを発生させるが、この例外はチェック例外（catch又はthrowsする必要がある）である）

import java.time.*;
import java.time.format.DateTimeFormatter;

// 日付時刻クラスのparseメソッドを使う方法
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
		String text = "2014/07/19 12:34:56";

		LocalDateTime localDateTime = LocalDateTime.parse(text, formatter);

// DateTimeFormatterのparseメソッドを使う方法
		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd HH:mm:ss");
		String text = "2014/07/19 12:34:56";

		TemporalAccessor parsed = formatter.parse(text);
		LocalDateTime localDateTime = LocalDateTime.from(parsed);
		// LocalDateTime localDateTime = parsed.query(LocalDateTime::from);

		// LocalDateTime localDateTime = formatter.parse(text, LocalDateTime::from);

SimpleDateFormatとの違い

SimpleDateFormatで解析（parse）する際は、対象文字列内の空白は無視される。[2014-07-23]

		// いずれも受理される
		SimpleDateFormat sdf = new SimpleDateFormat("yyyy/MM/dd");
		System.out.println(sdf.parse("2014/07/23"));
		System.out.println(sdf.parse("2014/7/23"));
		System.out.println(sdf.parse("2014/ 7/23"));
		System.out.println(sdf.parse("2014/  7/ 23"));

しかしDateTimeFormatterの場合、対象文字列内の空白は、書式文字列内に空白が指定されている場合だけ受理される。

		DateTimeFormatter tdf = DateTimeFormatter.ofPattern("yyyy/MM/dd");
		System.out.println(tdf.parse("2014/07/23"));
//×		System.out.println(tdf.parse("2014/7/23"));
//×		System.out.println(tdf.parse("2014/ 7/23"));
//×		System.out.println(tdf.parse("2014/  7/ 23"));

		DateTimeFormatter tdf = DateTimeFormatter.ofPattern("yyyy/M/d");
		System.out.println(tdf.parse("2014/07/23"));
		System.out.println(tdf.parse("2014/7/23"));
//×		System.out.println(tdf.parse("2014/ 7/23"));
//×		System.out.println(tdf.parse("2014/  7/ 23"));

		DateTimeFormatter tdf = DateTimeFormatter.ofPattern("yyyy/ M/d");
//×		System.out.println(tdf.parse("2014/07/23"));
//×		System.out.println(tdf.parse("2014/7/23"));
		System.out.println(tdf.parse("2014/ 7/23"));
//×		System.out.println(tdf.parse("2014/  7/ 23"));

空白をオプション書式にすれば、空白が有っても無くても受理されるようになる。
が、複数の空白には対応できない。（オプションを複数指定できるが、任意の個数には対応しきれない）

		DateTimeFormatter tdf = DateTimeFormatter.ofPattern("yyyy/[ ]M/[ ]d");
		System.out.println(tdf.parse("2014/07/23"));
		System.out.println(tdf.parse("2014/7/23"));
		System.out.println(tdf.parse("2014/ 7/23"));
//×		System.out.println(tdf.parse("2014/  7/ 23"));

		DateTimeFormatter tdf = DateTimeFormatter.ofPattern("yyyy/[ ][ ]M/[ ][ ]d");
		System.out.println(tdf.parse("2014/07/23"));
		System.out.println(tdf.parse("2014/7/23"));
		System.out.println(tdf.parse("2014/ 7/23"));
		System.out.println(tdf.parse("2014/  7/ 23"));

書式の文字

年「y」「u」

パターンの「y」は年を表す。[2014-07-23]
「y」は、厳密には暦（ERA。和暦の場合は昭和とか平成とか）に対する年を表す。
暦と関係ない年は「u」で表す。

→ResolverStyleがSTRICTの場合に違いが出る

時「h」「H」「k」「K」

時（hour）を表すパターンはいくつかある。[2014-07-23]
基本的には「H」だけ使えばいいと思うが。

大文字・小文字で24時間系か12時間系かが異なるが、hでは小文字がAM/PMで、Kでは大文字がAM/PM。

パディング「p」

パターンの「p」はパディング（空白埋め）を意味する。[2014-07-23]
「p」の個数分の桁を確保し、直後に指定したパターンがその桁数になるよう空白埋めされる。
（空白埋めという仕様上、「p」は2個以上必要（「p」が1個だけだとエラーになる））

例えば「ppM」は月が2桁分、「pppM」なら月が3桁分になる。

オプション「[〜]」

角括弧で囲むと、その部分はオプション（省略可能）になる。[2014-07-23]

		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("uuuu/[ ]M/[ ]d [ ]H:[ ]m:[ ]s.SSS");

空白文字をオプションにすると、解析（parse）する際、そこに空白が有っても無くても受理されるようになる。

リゾルバースタイル

DateTimeFormatterはリゾルバースタイルという属性を持っている。
これは、日時文字列を解析した後の値が範囲外の場合に、それを解決する方法を決めるもの。
デフォルトはSMART（賢い）で、他にLENIENT（寛大）、STRICT（厳密）がある。

import java.time.*;
import java.time.format.DateTimeFormatter;

		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd").withResolverStyle(ResolverStyle.SMART);		

範囲外の数値を指定した場合、
SMART（賢い）では、明らかに許容範囲を超えている場合はエラーになる。例えば13月や32日は絶対にありえないのでエラー。
小の月（31日より少ない月）では、31以下で本来ありえない日を指定すると、その月の末日になる。

LENIENT（寛大）では、許容範囲を超えている場合は、本来の月末日を超えて、超過分を加算した日付になる。

STRICT（厳密）では、その日時に許されないものは全てエラーになる。
書式「yyyy」は、厳密には暦（ERA。和暦の場合は昭和とか平成とか）に対する年なので、ERAが指定されていない場合はエラーになるようだ。
書式「uuuu」はERAと無関係な年を表す。

• 参考
  • ゆっちさんのJava8 の Date & Time API ではまった。
  • @matsumanaさんのJava8のDate and Time API(JSR 310)で文字列をparseする

どうしてもSTRICTで「yyyy」を使いたかったら、以下の様にすると使えなくもない。[2014-07-23]

書式で暦を指定する方法

import java.time.format.DateTimeFormatter;
import java.time.format.ResolverStyle;
import java.util.Locale;

		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd G")
			.withLocale(Locale.ENGLISH)
			.withResolverStyle(ResolverStyle.STRICT);

		LocalDate ldate = LocalDate.parse("2014/07/23 AD", formatter);

書式「G」で暦を指定する。
ここで、ロケールにENGLISH（等の英語圏）を指定しておかないと、「AD」という値はエラーになってしまう。
（日本の場合は、デフォルトのロケールが日本なので、「西暦」という値ならOK。だが、プログラム内の値に漢字とか使いたくない＾＾；）

デフォルトの暦を指定する方法

import java.time.chrono.IsoEra;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeFormatterBuilder;
import java.time.format.ResolverStyle;
import java.time.temporal.ChronoField;

		DateTimeFormatter formatter = new DateTimeFormatterBuilder()
			.appendPattern("yyyy/MM/dd")
			.parseDefaulting(ChronoField.ERA, IsoEra.CE.getValue())
			.toFormatter()
			.withResolverStyle(ResolverStyle.STRICT);

		LocalDate ldate = LocalDate.parse("2014/07/23", formatter);

LENIENT（寛大）の場合、時刻に関しては、超過した日数を取得する方法がある。

		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("HH:mm:ss").withResolverStyle(ResolverStyle.LENIENT);

		TemporalAccessor parsed = formatter.parse("24:01:02");
		LocalTime ltime = parsed.query(LocalTime::from); //→ 00:01:02
		Period period = parsed.query(DateTimeFormatter.parsedExcessDays()); //→ P1D

同様の方法をLocalDateでも試してみたが、こちらでは超過日数を取得することは出来なかった。

解析フェーズのみの実行

通常のparseメソッドでは、解析フェーズと解決フェーズを実行する。[2014-07-28]
解析フェーズで文字列の解析を行い、それぞれの要素の値を決定する。
解決フェーズでそれぞれの値が正しい範囲に収まっているかどうかを判定する。

parseUnresolvedメソッドを使うと、解析フェーズのみを実行し、解決フェーズを実行しない。
つまり、通常のparseメソッドではエラーとなるような値でも取得することが出来る。

import static org.hamcrest.CoreMatchers.*;
import static org.junit.Assert.*;

import java.text.ParsePosition;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.temporal.ChronoField;
import java.time.temporal.TemporalAccessor;

		DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/[ ]M/[ ]d");

		ParsePosition position = new ParsePosition(0);
		TemporalAccessor temporal = formatter.parseUnresolved("9999/13/99", position);

		assertThat(temporal, is(not(nullValue())));
		assertThat(position.getErrorIndex(), is(-1));
		assertThat(temporal.getLong(ChronoField.YEAR_OF_ERA), is(9999L));
		assertThat(temporal.getLong(ChronoField.MONTH_OF_YEAR), is(13L));
		assertThat(temporal.getLong(ChronoField.DAY_OF_MONTH),  is(99L));

parseUnresolvedメソッドでは、解析エラーがあると戻り値はnullとなり、引数のParsePositionオブジェクトにエラー位置がセットされる。
（ParsePositionは、旧来のDateFormatで使用していたParsePositionと全く同じクラス）

解析に成功した場合は、戻り値のTemporalAccessorに対してgetLongメソッドを呼び出すことにより、それぞれの値を取得できる。
ちなみにgetメソッドを使うと有効範囲チェックが行われるので、範囲外の値だと例外が発生する。