Module java.base
Package java.lang

Interface StringTemplate

public interface StringTemplate
StringTemplate 是 Java 平台的预览 API。
仅当启用预览功能时，程序才能使用 StringTemplate。
预览功能可能会在将来的版本中被移除，或升级为 Java 平台的永久功能。
StringTemplate预览 是模板表达式中字符串模板或文本块模板的运行时表示。

在 Java 程序的源代码中，字符串模板或文本块模板包含交错的一系列 片段文字 和 嵌入表达式。 fragments() 方法返回片段文字，values() 方法返回评估嵌入表达式的结果。 StringTemplate预览 不提供对嵌入表达式本身源代码的访问；它不是字符串模板或文本块模板的编译时表示。

StringTemplate预览 主要与模板处理器一起使用，以生成字符串或其他有意义的值。模板表达式的评估首先产生一个 StringTemplate预览 实例，表示模板表达式的右侧，然后将该实例传递给模板表达式给定的模板处理器。

例如，以下代码包含一个使用模板处理器 RAW 的模板表达式，该处理器简单地返回传递给它的 StringTemplate预览：

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预览 实例，该实例从 fragments() 和 values() 中返回与上述相同的列表。 STR 模板处理器使用这些列表生成一个插值字符串。 s 的值将等同于 "10 + 20 = 30"。

interpolate() 方法提供了直接执行 StringTemplate预览 字符串插值的方法。模板处理器可以使用以下代码模式：

List<String> fragments = st.fragments();
List<Object> values    = st.values();
... 检查或操作片段和/或值 ...
String result = StringTemplate.interpolate(fragments, values);
process(Processor) 方法与 RAW 处理器结合使用，可用于延迟处理 StringTemplate预览。 
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...其他步骤...
String result = st.process(STR);
工厂方法 of(String) 和 of(List, List) 可用于构造 StringTemplate预览。
实现注意事项：
StringTemplate预览 的实现必须最低限度地实现 fragments() 和 values() 方法。 StringTemplate预览 的实例被视为不可变的。为了保持字符串模板和文本块模板的语义，fragments() 返回的列表必须比 values() 返回的列表多一个元素。
参见 Java 语言规范：
15.8.6 处理模板表达式
自 JDK 版本：
21
另请参见：

  • Field Details

  • Method Details

    • fragments

      List<String> fragments()
      返回此StringTemplate预览的片段文字列表。片段文字是源代码中每个嵌入表达式之前的字符序列，以及最后一个嵌入表达式之后的字符序列。如果嵌入表达式出现在模板的开头或结尾，或者如果两个嵌入表达式直接相邻在模板中，则这样的字符序列可能是零长度。在示例中： 
      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预览的嵌入表达式结果列表。在示例中： 
      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预览的片段和值的字符串插值。
      API 注意：
      为了更好的可见性和实用性，建议使用STR处理器，而不是调用interpolate()方法。 
      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预览中的片段和值进行交错连接而生成的。为了进行连接，值将被转换为字符串，就好像调用String.valueOf(Object)一样。
      实现要求：
      默认实现返回调用StringTemplate.interpolate(this.fragments(), this.values())的结果。
      返回：
      此StringTemplate预览的插值

    • process

      default <R, E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor) throws E
      返回将指定处理器应用于此StringTemplate预览的结果。此方法可用作字符串模板表达式的替代。例如， 
      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预览实例
      返回：
      类型为R的构造对象
      抛出：
      E - 模板处理器在验证失败时抛出的异常
      NullPointerException - 如果处理器为null

    • toString

      static String toString(StringTemplatePREVIEW stringTemplate)
      生成描述所提供的StringTemplate预览的片段和值的诊断字符串。
      参数：
      stringTemplate - 要表示的StringTemplate预览
      返回：
      表示所提供的字符串模板的诊断字符串
      抛出：
      NullPointerException - 如果stringTemplate为null

    • of

      static StringTemplatePREVIEW of(String string)
      返回一个StringTemplate预览，就好像通过调用StringTemplate.of(List.of(string), List.of())构造一样。也就是说，一个具有一个片段和没有值的StringTemplate预览。
      参数：
      string - 单个字符串片段
      返回：
      由字符串组成的StringTemplate
      抛出：
      NullPointerException - 如果string为null

    • of

      static StringTemplatePREVIEW of(List<String> fragments, List<?> values)
      返回具有给定片段和值的StringTemplate。
      实现要求:
      fragments 列表的大小必须比 values 列表的大小多一个。
      实现说明:
      两个列表的内容被复制以构建不可变列表。
      参数:
      fragments - 字符串片段列表
      values - 表达式值列表
      返回:
      由字符串组成的StringTemplate
      抛出:
      IllegalArgumentException - 如果fragments列表的大小不是比values列表的大小多一个
      NullPointerException - 如果fragments为null或values为null或任何片段为null。

    • interpolate

      static String interpolate(List<String> fragments, List<?> values)
      创建一个字符串，将values的元素插入到fragments的元素之间。为了适应插值，值被转换为字符串，就好像调用String.valueOf(Object)一样。
      参数:
      fragments - 字符串片段列表
      values - 表达式值列表
      返回:
      fragments和values的字符串插值
      抛出:
      IllegalArgumentException - 如果fragments列表的大小不是比values列表的大小多一个
      NullPointerException - 如果fragments或values为null或任何片段为null

    • combine

      static StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)
      将零个或多个StringTemplates预览组合成一个单个StringTemplate预览。 
      StringTemplate st = StringTemplate.combine(RAW."\{a}", RAW."\{b}", RAW."\{c}");
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      来自StringTemplates预览的片段列表被端对端地组合，每个StringTemplate预览的最后一个片段与下一个的第一个片段连接起来。为了演示，如果我们取两个字符串并将它们组合如下： 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      第一个字符串的最后一个字符"c"与第二个字符串的第一个字符"x"并置。对于组合StringTemplates预览也是如此。 
      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预览，其中n是所有提供的StringTemplates预览的值的总数。
      实现说明:
      如果未提供零个StringTemplate预览参数，则返回一个具有空片段和无值的StringTemplate预览，就好像调用StringTemplate.of("")一样。如果只提供一个StringTemplate预览参数，则返回该参数不变。
      参数:
      stringTemplates - 零个或多个StringTemplate预览
      返回:
      组合的StringTemplate预览
      抛出:
      NullPointerException - 如果stringTemplates为null或其中任何一个stringTemplates为null

    • combine

      static StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)
      将一个StringTemplates预览列表组合成一个单个StringTemplate预览。 
      StringTemplate st = StringTemplate.combine(List.of(RAW."\{a}", RAW."\{b}", RAW."\{c}"));
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      来自StringTemplates预览的片段列表被端对端地组合，每个StringTemplate预览的最后一个片段与下一个的第一个片段连接起来。为了演示，如果我们取两个字符串并将它们组合如下： 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      第一个字符串的最后一个字符"c"与第二个字符串的第一个字符"x"并置。对于组合StringTemplates预览也是如此。 
      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预览，其中n是所有提供的StringTemplates预览的值的总数。
      实现说明:
      如果stringTemplates.size() == 0，则返回一个具有空片段和无值的StringTemplate预览，就好像调用StringTemplate.of("")一样。如果stringTemplates.size() == 1，则返回列表的第一个元素不变。
      参数:
      stringTemplates - StringTemplate预览列表
      返回:
      组合的StringTemplate预览
      抛出:
      NullPointerException - 如果stringTemplates为null或其中任何一个元素为null