Java書式付き出力

Javaで高度な書式を使って、値を編集（変換）する方法。

System.out.printf()・String#format()

C言語のprintf()関数相当の機能がJDK1.5で追加された。

第一引数で書式を指定し、その書式に則って第二引数以降の値を編集（変換）して出力する。
（第二引数以降の値は、可変長引数で複数指定できる）

	System.out.printf("値1=%d 値2=%d", 123, 456);
	String s = String.format("%04x", 789);

書式には「%」が入った文字列を指定する。「%」の書式指定に従って変換が行われる。
デフォルトでは、複数の%指定がある場合、第二引数以降の値が順番に使われる。
引数が多い分には無視されるだけなので別に構わないが、指定に該当する引数が足りないと例外が発生する。

変換の実体はFormatterクラスにある。
したがってどのような書式があるかについてはFormatterのJavadocに載っているが、代表的なのは以下のようなもの。

書式指定文字には大文字小文字で区別があるので、使用する際は注意。
日付書式は全く違うものが割り当てられている。それ以外は、基本的に 書式指定文字が大文字なら値が大文字に変換される。
例えば「%b」はtrue又はfalseになるが、「%B」だとTRUE・FALSEになる。
「%S」も、デフォルトでは大文字に変換される。

また、C言語では、書式指定に合致した値を引数に指定する必要があった。
（なので、例えばC言語でlong値を指定する場合は「%ld」のように「long型整数」という指定をする必要があった。
 Java版ではlongでもintでも「%d」でよい（「%ld」という指定をしたら「java.util.UnknownFormatConversionException: Conversion = 'l'」という例外が発生する））
Javaでは引数はObject型なので、その値を書式に合わせて変換してくれる。[/2008-05-21]
（変換できない場合はさすがに例外が発生するけど）

	System.out.printf("%d", 123);	…OK（当然）
	System.out.printf("%s", 123);	…OK！
	System.out.printf("%d", "123");	…java.util.IllegalFormatConversionException
	System.out.printf("%s", "123");	…OK（当然）

※C言語と同じく可変引数部分に数値（プリミティブ型）を置く書き方が出来るが、実際にはオートボクシングによってラッパークラスに変換されるので、実行速度を考えるならそれを意識した方がいいだろう。[2008-05-21]
（オートボクシングでは、例えばintだと、変換先のクラス指定がIntegerの時だけでなく、Objectの時もIntegerに変換してくれる）

	String.format("%d %d %d", 12, 12, 12);
↓実態
	String.format("%d %d %d", Integer.valueOf(12), Integer.valueOf(12), Integer.valueOf(12));

↓効率化を図ったコーディング
	Integer n12 = 12;
	String.format("%d %d %d", n12, n12, n12);

とは言うものの、Formatterによる変換自体（書式文字列の解釈とか）にそれなりのコストがかかるだろうから、そもそも速度にあまり口うるさくないシーンでしか使わない想定かな。

引数番号指定「数$」の動作はC言語とちょっと違うようだ。

C言語では、%1$d（1番目を指定）の後の%d（番号指定なし）は2番目（最後の番号指定の次の番号）の値が使われるのに対し、
Javaでは、n$の指定（番号指定）は全く無視して、番号指定の無いもの同士だけで順番に値が使われるようだ。

一方、「$」と似たような機能である「<」については、忠実に直前の値を使用する。（すなわち、直前が番号指定であろうが無かろうが、直前の%の値を使用する）

	System.out.printf("%d %d %<d %1$d %<s %d %<d %d%n", 11, 22, 33, 44);
	↓
11 22 22 11 11 33 33 44

%sの桁指定について

書式指定の「%s」に桁数や精度（最大表示幅）を指定をする場合、文字数のカウントはUNICODEで行われる。[2008-07-29]
すなわち、いわゆる半角文字（文字コード0x7f未満）と全角文字も、文字数は同じ扱いになってしまう。
つまり、等幅のコンソールに出力した場合、たぶん期待している状態にならない。

Formattable

書式指定の「%s」は、基本的に、引数のtoString()を呼んで変換するものと思ってよいだろう。
（nullの場合は"null"になってくれる）

ただし、引数のインスタンスのクラスがFormattableインターフェースを実装している場合は、そのクラスのformatTo()メソッドが呼ばれて変換される。
すなわち、自作クラスをprintf()やformat()の「%s」で出力したい場合、その出力のさせ方（表現方法）を（toString()とは別に）実装することが出来る。

FormattableDate.java：

import java.io.IOException;
import java.util.Calendar;
import java.util.Date;
import java.util.Formattable;
import java.util.Formatter;

public class FormattableDate extends Date implements Formattable {

	@Override
	public void formatTo(Formatter formatter, int flags, int width, int precision) {
		format_test1(formatter);
//		format_test2(formatter);
//		format_test3(formatter);
	}

	/** appendを使って出力する例 */
	void format_test1(Formatter formatter) {
		Calendar cal = Calendar.getInstance();
		cal.setTime(this);
		int yy = cal.get(Calendar.YEAR);
		int mm = cal.get(Calendar.MONTH) + 1;
		int dd = cal.get(Calendar.DATE);
		int hh = cal.get(Calendar.HOUR_OF_DAY);
		int mn = cal.get(Calendar.MINUTE);
		int ss = cal.get(Calendar.SECOND);
		int ms = cal.get(Calendar.MILLISECOND);

		Appendable a = formatter.out();
		try {
			a.append(Integer.toString(yy));
			a.append('/');
			a.append(Integer.toString(mm));
			a.append('/');
			a.append(Integer.toString(dd));
			a.append(' ');
			a.append(Integer.toString(hh));
			a.append(':');
			a.append(Integer.toString(mn));
			a.append(':');
			a.append(Integer.toString(ss));
			a.append('.');
			a.append(Integer.toString(ms));
		} catch (IOException e) {
			throw new RuntimeException(e);
		}
	}

Appendableは文字を出力（追加）する為のインターフェース。Formatter#out()によってインスタンスを取得する。
append()の引数はcharとCharSequenceインターフェースしか無いが、StringやStringBuilderはCharSequenceをimplementsしているので そのまま渡すことが出来る。

Formatterには、ioException()という「Appendableで最後に起きたI/O例外を返す」メソッドがある。
しかしFormatterにはIOExceptionをセットするメソッドが無い！
なので、Appendable#append()はIOExceptionを投げる可能性がある（throwsで宣言されている）にも関わらず、Formatterにセットする術が無い…。
なぜformatTo()には「throws IOException」が宣言されていないのだろう？
　

	/** formatと%dを使う方式 */
	void format_test2(Formatter formatter) {
		Calendar cal = Calendar.getInstance();
		cal.setTime(this);
		int yy = cal.get(Calendar.YEAR);
		int mm = cal.get(Calendar.MONTH) + 1;
		int dd = cal.get(Calendar.DATE);
		int hh = cal.get(Calendar.HOUR_OF_DAY);
		int mn = cal.get(Calendar.MINUTE);
		int ss = cal.get(Calendar.SECOND);
		int ms = cal.get(Calendar.MILLISECOND);
		formatter.format("%04d/%02d/%02d %02d:%02d:%02d.%03d", yy, mm, dd, hh, mn, ss, ms);
	}

formatTo()の引数であるformatterにもformat()メソッドがある。
自分自身のインスタンス内のそれぞれの値をそこに渡して変換してやればよい。

この例では、もっと簡便に以下の様にすることも出来る。

	/** formatと1$を使う方式 */
	void format_test3(Formatter formatter) {
		formatter.format("%1$tY/%1$tm/%1$td %1$tH:%1$tM:%1$tS.%1$tL", this);
//		formatter.format("%tY/%<tm/%<td %<tH:%<tM:%<tS.%<tL", this);
	}

全ての書式指定に「%1$」という引数番号を指定しているので、（もしくは「%<」という直前の値を使う指定をしているので、）可変引数部は一つだけでよい。
thisを渡しているので「また自分が呼ばれて無限ループになるんじゃないか」と一瞬思ってしまうかもしれないが、formatTo()が呼ばれるのは「%s」のときだけなので、再度呼ばれることは無い。

}
//FormattableDateの終わり

呼び出し例：

	Date date = new FormattableDate();
	System.out.printf("実験結果→%s%n", date);	//この%sの場所でformatTo()が呼ばれる

実行結果：

実験結果→2008/5/20 1:55:5.859   	…test1
実験結果→2008/05/20 01:55:28.078	…test2
実験結果→2008/05/20 01:55:45.359	…test3

formatTo()の引数

Formattable#formatTo()の第二引数以降には、書式の属性が渡されてくる。

widthは、出力する最小文字数。データがこの桁数に足りないときは、スペースで埋めるのが良い。（勝手に埋めてくれたりはしない）

precisionは、出力する最大文字数。データはこの桁数までしか出力しないようにするのが良い。（勝手にカットされたりはしない）

flagsの定数値はFormattableFlagsに定義されており、ビット論理和で合算されている。必要に応じてフラグを判断して編集内容を変えると良い。

	@Override
	public void formatTo(Formatter formatter, int flags, int width, int precision) {

		if ((flags & FormattableFlags.LEFT_JUSTIFY) != 0) {
			// 左寄せの書式指定「-」
			〜
		}
		if ((flags & FormattableFlags.UPPERCASE) != 0) {
			// 大文字の書式指定
			〜
		}
		if ((flags & FormattableFlags.ALTERNATE) != 0) {
			// 代替フォームの書式指定「#」
			〜
		}
		〜
	}