モジュール java.base

パッケージ java.lang

インタフェースStringTemplate

public interface StringTemplate

StringTemplateは、JavaプラットフォームのプレビューAPIです。

プレビュー機能が有効な場合のみ、プログラムでStringTemplateを使用できます。

プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。

StringTemplate^PREVIEWは、テンプレート式内の文字列テンプレートまたはテキスト・ブロック・テンプレートの実行時表現です。

Javaプログラムのソース・コードでは、文字列テンプレートまたはテキスト・ブロック・テンプレートに、「フラグメント・リテラル」および「埋込み式」のインタリーブ後継が含まれます。 fragments()メソッドはフラグメント・リテラルを返し、values()メソッドは埋込み式を評価した結果を返します。 StringTemplate^PREVIEWでは、埋込み式自体のソース・コードへのアクセスは提供されません。文字列テンプレートまたはテキスト・ブロック・テンプレートのコンパイル時表現ではありません。

StringTemplate^PREVIEWは主にテンプレート・プロセッサと組み合せて使用され、文字列またはその他の意味のある値を生成します。 テンプレート式の評価では、最初にテンプレート式の右側を表すStringTemplate^PREVIEWのインスタンスが生成され、次にテンプレート式によって指定されたテンプレート・プロセッサにインスタンスが渡されます。

たとえば、次のコードには、テンプレート・プロセッサRAWを使用するテンプレート式が含まれています。テンプレート・プロセッサRAWでは、渡されたStringTemplate^PREVIEWが単に生成されます:

int x = 10;
int y = 20;
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
List<String> fragments = st.fragments();
List<Object> values = st.values();

fragmentsは、空の最初と最後のフラグメントを含むList.of("", " + ", " = ", "")と同等です。valuesは、List.of(10, 20, 30)と同等です。

次のコードには、同じテンプレートを使用するテンプレート式が含まれていますが、テンプレート・プロセッサSTRは異なります:

int x = 10;
int y = 20;
String s = STR."\{x} + \{y} = \{x + y}";

テンプレート式が評価されると、StringTemplate^PREVIEWのインスタンスが生成され、前述のようにfragments()およびvalues()から同じリストが返されます。 STRテンプレート・プロセッサは、これらのリストを使用して補間された文字列を生成します。 sの値は、"10 + 20 = 30"と同等です。

interpolate()メソッドは、StringTemplate^PREVIEWの文字列補間を実行する直接的な方法を提供します。 テンプレート・プロセッサでは、次のコード・パターンを使用できます:

List<String> fragments = st.fragments();
List<Object> values    = st.values();
... check or manipulate the fragments and/or values ...
String result = StringTemplate.interpolate(fragments, values);

process(Processor)メソッドをRAWプロセッサと組み合せて使用すると、StringTemplate^PREVIEWの処理を遅延できます。

StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...other steps...
String result = st.process(STR);

ファクトリ・メソッドof(String)およびof(List, List)を使用して、StringTemplate^PREVIEWを構築できます。

実装上のノート:

StringTemplate^PREVIEWの実装では、fragments()およびvalues()メソッドを最小限に実装する必要があります。 StringTemplate^PREVIEWのインスタンスは不変とみなされます。 文字列テンプレートおよびテキスト・ブロック・テンプレートのセマンティクスを保持するには、fragments()によって返されるリストは、values()によって返されるリストより大きい1つの要素である必要があります。

Java言語仕様を参照してください:

「15.8.6 テンプレート式の処理」

導入されたバージョン:

21

関連項目:

• StringTemplate.Processor^PREVIEW
• FormatProcessor^PREVIEW

ネストされたクラスのサマリー

ネストされたクラス

修飾子と型	インタフェース	説明
static interface	StringTemplate.ProcessorPREVIEW<R,E extends Throwable>	Preview. このインタフェースでは、汎用文字列テンプレート・プロセッサによって提供されるメソッドについて説明します。

フィールドのサマリー

フィールド

修飾子と型	フィールド	説明
static final StringTemplate.ProcessorPREVIEW<StringTemplatePREVIEW,RuntimeException>	RAW	このStringTemplate.ProcessorPREVIEWインスタンスは、通常、StringTemplatePREVIEWの処理を後で遅延することを示すために使用されます。
static final StringTemplate.ProcessorPREVIEW<String,RuntimeException>	STR	このStringTemplate.ProcessorPREVIEWインスタンスは、通常、指定されたStringTemplatePREVIEWの文字列補間に使用されます。

メソッドのサマリー

修飾子と型	メソッド	説明
static StringTemplatePREVIEW	combine(StringTemplatePREVIEW... stringTemplates)	0個以上のStringTemplatesPREVIEWを1つのStringTemplatePREVIEWに結合します。
static StringTemplatePREVIEW	combine(List<StringTemplatePREVIEW> stringTemplates)	StringTemplatesPREVIEWのリストを1つのStringTemplatePREVIEWに結合します。
List<String>	fragments()	このStringTemplatePREVIEWのフラグメント・リテラルのリストを返します。
default String	interpolate()	このStringTemplatePREVIEWのフラグメントおよび値の文字列補間を返します。
static String	interpolate(List<String> fragments, List<?> values)	フラグメントの要素間で値の要素をインターリーブする文字列を作成します。
static StringTemplatePREVIEW	of(String string)	StringTemplatePREVIEWをStringTemplate.of(List.of(string), List.of())を呼び出すことによって構築されたかのように返します。
static StringTemplatePREVIEW	of(List<String> fragments, List<?> values)	指定されたフラグメントおよび値を持つStringTemplateを返します。
default <R, E extends Throwable> R	process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor)	指定されたプロセッサをこのStringTemplatePREVIEWに適用した結果を返します。
static String	toString(StringTemplatePREVIEW stringTemplate)	指定されたStringTemplatePREVIEWのフラグメントおよび値を説明する診断文字列を生成します。
List<Object>	values()	このStringTemplatePREVIEWの埋込み式の結果のリストを返します。

フィールド詳細

STR

static final StringTemplate.ProcessorPREVIEW<String,RuntimeException> STR

このStringTemplate.Processor^PREVIEWインスタンスは、通常、指定されたStringTemplate^PREVIEWの文字列補間に使用されます。

可視性を高めるため、実際的な場合は、interpolate()メソッドを起動するかわりにSTRプロセッサを使用することをお薦めします。 例:

int x = 10;
int y = 20;
String result = STR."\{x} + \{y} = \{x + y}";

前述の例では、resultの値は"10 + 20 = 30"になります。 これは、指定されたStringTemplate^PREVIEWからのフラグメントと値のインターリーブ連結によって生成されます。 連結に対応するために、値はString.valueOf(Object)を呼び出すかのように文字列に変換されます。

APIのノート:

STRは、すべてのJavaコンパイル・ユニットに暗黙的にインポートされます。

RAW

static final StringTemplate.ProcessorPREVIEW<StringTemplatePREVIEW,RuntimeException> RAW

このStringTemplate.Processor^PREVIEWインスタンスは、通常、StringTemplate^PREVIEWの処理を後で遅延することを示すために使用されます。 遅延処理は、process(Processor)またはStringTemplate.Processor.process(StringTemplate)^PREVIEWメソッドを起動することで再開できます。

import static java.lang.StringTemplate.RAW;
...
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...other steps...
String result = STR.process(st);

実装上のノート:

STRとは異なり、RAWは明示的に静的にインポートする必要があります。

メソッドの詳細

fragments

List<String> fragments()

このStringTemplate^PREVIEWのフラグメント・リテラルのリストを返します。 フラグメント・リテラルは、ソース・コードの各埋込み式の前の文字シーケンスと、最後の埋込み式の後の文字シーケンスです。 埋込み式がテンプレートの先頭または末尾に表示される場合、または2つの埋込み式がテンプレート内で直接隣り合っている場合、このような文字シーケンスは長さゼロになることがあります。 この例では:

String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<String> fragments = st.fragments();

fragmentsはList.of("The student ", " is in ", "'s classroom.")と同等です

実装要件:

返されるリストは不変です

戻り値:

文字列フラグメントのリスト

values

List<Object> values()

このStringTemplate^PREVIEWの埋込み式の結果のリストを返します。 この例では:

String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<Object> values = st.values();

valuesはList.of(student, teacher)と同等です

実装要件:

返されるリストは不変です

戻り値:

式の値のリスト

interpolate

default String interpolate()

このStringTemplate^PREVIEWのフラグメントおよび値の文字列補間を返します。

APIのノート:

可視性を高めるため、実際的な場合は、interpolate()メソッドを起動するかわりにSTRプロセッサを使用することをお薦めします。

String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
String result = st.interpolate();

前述の例では、resultの値は"The student Mary is in Johnson's classroom."になります。 これは、指定されたStringTemplate^PREVIEWからのフラグメントと値のインターリーブ連結によって生成されます。 連結に対応するために、値はString.valueOf(Object)を呼び出すかのように文字列に変換されます。

実装要件:

デフォルトの実装では、StringTemplate.interpolate(this.fragments(), this.values())の呼出しの結果が返されます。

戻り値:

このStringTemplate^PREVIEWの補間

process

default <R, E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor) throws E

指定されたプロセッサをこのStringTemplate^PREVIEWに適用した結果を返します。 このメソッドは、文字列テンプレート式の代替として使用できます。 たとえば、

String student = "Mary";
String teacher = "Johnson";
String result1 = STR."The student \{student} is in \{teacher}'s classroom.";
String result2 = RAW."The student \{student} is in \{teacher}'s classroom.".process(STR);

result1とresult2の両方で同等の結果が生成されます。

実装要件:

デフォルトの実装では、processor.process(this)の呼出しの結果が返されます。 呼出しで例外がスローされた場合、例外は呼出し元に転送されます。

型パラメータ:

R - プロセッサのプロセス結果タイプ。

E - 例外スロー・タイプ。

パラメータ:

processor - 処理するStringTemplate.Processor^PREVIEWインスタンス

戻り値:

R型の構築されたオブジェクト

例外:

E - 検証が失敗したときにテンプレート・プロセッサによってスローされた例外

NullPointerException - プロセッサがnullの場合

toString

static String toString(StringTemplatePREVIEW stringTemplate)

指定されたStringTemplate^PREVIEWのフラグメントおよび値を説明する診断文字列を生成します。

パラメータ:

stringTemplate - 表すStringTemplate^PREVIEW

戻り値:

指定された文字列テンプレートを表す診断文字列

例外:

NullPointerException - stringTemplateがnullの場合

of

static StringTemplatePREVIEW of(String string)

StringTemplate^PREVIEWをStringTemplate.of(List.of(string), List.of())を呼び出すことによって構築されたかのように返します。 つまり、StringTemplate^PREVIEWには1つのフラグメントがあり、値はありません。

パラメータ:

string - 単一文字列フラグメント

戻り値:

文字列から構成されるStringTemplate

例外:

NullPointerException - 文字列がnullの場合

of

static StringTemplatePREVIEW of(List<String> fragments, List<?> values)

指定されたフラグメントおよび値を持つStringTemplateを返します。

実装要件:

fragmentsリスト・サイズは、valuesリスト・サイズより1つ大きくする必要があります。

実装上のノート:

両方のリストの内容がコピーされ、不変リストが作成されます。

パラメータ:

fragments - 文字列フラグメントのリスト

values - 式の値のリスト

戻り値:

文字列から構成されるStringTemplate

例外:

IllegalArgumentException - フラグメント・リスト・サイズが値リスト・サイズより大きくない場合

NullPointerException - フラグメントがnullの場合、または値がnullの場合、またはフラグメントがnullの場合。

interpolate

static String interpolate(List<String> fragments, List<?> values)

フラグメントの要素間で値の要素をインターリーブする文字列を作成します。 補間に対応するために、値はString.valueOf(Object)を呼び出すかのように文字列に変換されます。

パラメータ:

fragments - 文字列フラグメントのリスト

values - 式の値のリスト

戻り値:

フラグメントと値の文字列補間

例外:

IllegalArgumentException - フラグメント・リスト・サイズが値リスト・サイズより大きくない場合

NullPointerException - フラグメントまたは値がnullであるか、フラグメントのいずれかがnullの場合

combine

static StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)

0個以上のStringTemplates^PREVIEWを1つのStringTemplate^PREVIEWに結合します。

StringTemplate st = StringTemplate.combine(RAW."\{a}", RAW."\{b}", RAW."\{c}");
assert st.interpolate().equals(STR."\{a}\{b}\{c}");

StringTemplates^PREVIEWのフラグメント・リストは、各StringTemplate^PREVIEWの最後のフラグメントと最後に結合され、次の最初のフラグメントと連結されます。 示すために、2つの文字列をとり、次のように結合しました:

String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");

最初の文字列の最後の文字"c"は、2番目の文字列の最初の文字"x"と結合されます。 StringTemplates^PREVIEWの結合についても同様です。

StringTemplate st1 = RAW."a\{}b\{}c";
StringTemplate st2 = RAW."x\{}y\{}z";
StringTemplate st3 = RAW."a\{}b\{}cx\{}y\{}z";
StringTemplate stc = StringTemplate.combine(st1, st2);

assert Objects.equals(st1.fragments(), List.of("a", "b", "c"));
assert Objects.equals(st2.fragments(), List.of("x", "y", "z"));
assert Objects.equals(st3.fragments(), List.of("a", "b", "cx", "y", "z"));
assert Objects.equals(stc.fragments(), List.of("a", "b", "cx", "y", "z"));

値リストは単純に連結され、単一の値リストが生成されます。 この結果は、n+1フラグメントおよびn値を持つ整形式のStringTemplate^PREVIEWになります。ここで、nは、指定されたすべてのStringTemplates^PREVIEWの値の合計数です。

実装上のノート:

StringTemplate^PREVIEW引数がゼロの場合、StringTemplate.of("")を呼び出す場合と同様に、空のフラグメントを含むStringTemplate^PREVIEWが返されず、値は返されません。 StringTemplate^PREVIEW引数を1つのみ指定した場合、その引数は変更されずに返されます。

パラメータ:

stringTemplates - ゼロ以上のStringTemplate^PREVIEW

戻り値:

結合StringTemplate^PREVIEW

例外:

NullPointerException - stringTemplatesがnullの場合、またはstringTemplatesのいずれかがnullの場合

combine

static StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)

StringTemplates^PREVIEWのリストを1つのStringTemplate^PREVIEWに結合します。

StringTemplate st = StringTemplate.combine(List.of(RAW."\{a}", RAW."\{b}", RAW."\{c}"));
assert st.interpolate().equals(STR."\{a}\{b}\{c}");

StringTemplates^PREVIEWのフラグメント・リストは、各StringTemplate^PREVIEWの最後のフラグメントと最後に結合され、次の最初のフラグメントと連結されます。 示すために、2つの文字列をとり、次のように結合しました:

String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");

最初の文字列の最後の文字"c"は、2番目の文字列の最初の文字"x"と結合されます。 StringTemplates^PREVIEWの結合についても同様です。

StringTemplate st1 = RAW."a\{}b\{}c";
StringTemplate st2 = RAW."x\{}y\{}z";
StringTemplate st3 = RAW."a\{}b\{}cx\{}y\{}z";
StringTemplate stc = StringTemplate.combine(List.of(st1, st2));

assert Objects.equals(st1.fragments(), List.of("a", "b", "c"));
assert Objects.equals(st2.fragments(), List.of("x", "y", "z"));
assert Objects.equals(st3.fragments(), List.of("a", "b", "cx", "y", "z"));
assert Objects.equals(stc.fragments(), List.of("a", "b", "cx", "y", "z"));

値リストは単純に連結され、単一の値リストが生成されます。 この結果は、n+1フラグメントおよびn値を持つ整形式のStringTemplate^PREVIEWになります。ここで、nは、指定されたすべてのStringTemplates^PREVIEWの値の合計数です。

実装上のノート:

stringTemplates.size() == 0の場合、StringTemplate.of("")を呼び出すかのように、空のフラグメントを持ち、値が戻されないStringTemplate^PREVIEWが返されます。 stringTemplates.size() == 1の場合、リストの最初の要素は変更されずに返されます。

パラメータ:

stringTemplates - StringTemplate^PREVIEWのリスト

戻り値:

結合StringTemplate^PREVIEW

例外:

NullPointerException - stringTemplatesがnullの場合、またはその要素のいずれかがnullの場合