Интерфейс StringTemplate

public interface StringTemplate

StringTemplate — это предварительный API платформы Java.

Программы могут использовать 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();
... check or manipulate the fragments and/or values ...
String result = StringTemplate.interpolate(fragments, values);

Метод process(Processor) совместно с процессором RAW может использоваться для отсрочки обработки StringTemplate^{ПРЕДПРОСМОТР}.

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

Фабричные методы of(String) и of(List, List) могут использоваться для создания StringTemplate^{ПРЕДПРОСМОТР}.

Примечание по реализации:

Реализации StringTemplate^{ПРЕДПРОСМОТР} должны в минимальном объёме реализовывать методы fragments() и values(). Экземпляры StringTemplate^{ПРЕДПРОСМОТР} считаются неизменяемыми. Для сохранения семантики шаблонов строк и шаблонов текстовых блоков список, возвращаемый методом fragments(), должен быть на один элемент больше, чем список, возвращаемый методом values().

См. Спецификацию языка Java:

15.8.6 Обработка выражений шаблонов

С:

См. также:

Краткое описание вложенных классов

Модификатор и тип	Интерфейс	Описание
`static interface`	`StringTemplate.Processor^PREVIEW<R,E extends Throwable>`	Предварительный просмотр. Этот интерфейс описывает методы, предоставляемые обобщенным процессором шаблонов строк.

Краткое описание полей

Модификатор и тип	Поле	Описание
`static final StringTemplate.Processor^PREVIEW<StringTemplate^PREVIEW,RuntimeException>`	`RAW`	Этот экземпляр `StringTemplate.Processor`^{ПРЕДПРОСМОТР} обычно используется для указания того, что обработка `StringTemplate`^{ПРЕДПРОСМОТР} должна быть отложена на более позднее время.
`static final StringTemplate.Processor^PREVIEW<String,RuntimeException>`	`STR`	Этот экземпляр `StringTemplate.Processor`^{ПРЕДПРОСМОТР} обычно используется для строковой интерполяции переданного `StringTemplate`^{ПРЕДПРОСМОТР}.

Краткое описание методов

Модификатор и тип	Метод	Описание
`static StringTemplate^PREVIEW`	`combine(StringTemplate^PREVIEW... stringTemplates)`	Объединить ноль или более `StringTemplates`^{ПРЕДПРОСМОТР} в один `StringTemplate`^{ПРЕДПРОСМОТР}.
`static StringTemplate^PREVIEW`	`combine(List<StringTemplate^PREVIEW> stringTemplates)`	Объединить список `StringTemplates`^{ПРЕДПРОСМОТР} в один `StringTemplate`^{ПРЕДПРОСМОТР}.
`List<String>`	`fragments()`	Возвращает список литералов фрагментов для этого `StringTemplate`^{ПРЕДПРОСМОТР}.
`default String`	`interpolate()`	Возвращает строковую интерполяцию фрагментов и значений для этого `StringTemplate`^{ПРЕДПРОСМОТР}.
`static String`	`interpolate(List<String> fragments, List<?> values)`	Создаёт строку, которая чередует элементы значений между элементами фрагментов.
`static StringTemplate^PREVIEW`	`of(String string)`	Возвращает `StringTemplate`^{ПРЕДПРОСМОТР}, как если бы он был создан вызовом `StringTemplate.of(List.of(string), List.of())`.
`static StringTemplate^PREVIEW`	`of(List<String> fragments, List<?> values)`	Возвращает StringTemplate с указанными фрагментами и значениями.
`default <R, E extends Throwable> R`	`process(StringTemplate.Processor^PREVIEW<? extends R,? extends E> processor)`	Возвращает результат применения указанного процессора к этому `StringTemplate`^{ПРЕДПРОСМОТР}.
`static String`	`toString(StringTemplate^PREVIEW stringTemplate)`	Создаёт диагностическую строку, которая описывает фрагменты и значения переданного `StringTemplate`^{ПРЕДПРОСМОТР}.
`List<Object>`	`values()`	Возвращает список результатов встроенных выражений для этого `StringTemplate`^{ПРЕДПРОСМОТР}.

Подробное описание полей

STR

static final StringTemplate.ProcessorPREVIEW<String,RuntimeException> STR

Этот экземпляр StringTemplate.Processor^ПРЕВЬЮ обычно используется для интерполяции строк с предоставленной строкой StringTemplate^ПРЕВЬЮ.

Для лучшей видимости и когда это практично, рекомендуется, чтобы пользователи использовали процессор STR вместо вызова метода interpolate(). Пример:

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

В приведенном выше примере значение result будет "10 + 20 = 30". Это результат чередующегося конкатенации фрагментов и значений из предоставленной строкой StringTemplate^ПРЕВЬЮ. Для обеспечения конкатенации значения преобразуются в строки, как при вызове String.valueOf(Object).

Примечание API:: STR статически импортируется неявно в каждый Java-компиляционный модуль.

RAW

static final StringTemplate.ProcessorPREVIEW<StringTemplatePREVIEW,RuntimeException> RAW

Этот экземпляр StringTemplate.Processor^ПРЕВЬЮ обычно используется для отсрочки обработки строки StringTemplate^ПРЕВЬЮ на более позднее время. Отложенную обработку можно возобновить, вызвав методы process(Processor) или StringTemplate.Processor.process(StringTemplate)^ПРЕВЬЮ.

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^ПРЕВЬЮ. Фрагменты-литералы — это последовательности символов, предшествующие каждому встроенному выражению в исходном коде, плюс последовательность символов после последнего встроенного выражения. Такие последовательности могут быть нулевой длины, если встроенное выражение находится в начале или конце шаблона, или если два встроенных выражения расположены непосредственно рядом в шаблоне. В примере:

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 - если строка равна null

of

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

Возвращает StringTemplate с заданными фрагментами и значениями.

Требования к реализации:: Размер списка fragments должен быть на единицу больше размера списка values.
Примечание реализации:: Содержимое обоих списков копируется для создания неизменяемых списков.
Параметры:: fragments - список строковых фрагментов; values - список значений выражений
Возвращает:: StringTemplate, составленный из строки
Исключения:: IllegalArgumentException - если размер списка фрагментов не на единицу больше размера списка значений; NullPointerException - если fragments или values равны null, или если какой-либо фрагмент равен null.

interpolate

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

Создает строку, чередуя элементы значений между элементами фрагментов. Для обеспечения интерполяции значения преобразуются в строки, как при вызове String.valueOf(Object).

Параметры:: fragments - список строковых фрагментов; values - список значений выражений
Возвращает:: Строковая интерполяция фрагментов и значений
Исключения:: IllegalArgumentException - если размер списка фрагментов не на единицу больше размера списка значений; NullPointerException - fragments или values равны null, или если какой-либо фрагмент равен null

combine

static StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)

Объединить ноль или более StringTemplates^PREVIEW в один StringTemplate^PREVIEW.

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

Списки фрагментов из StringTemplates^PREVIEW объединяются конкатенацией, при этом последний фрагмент каждого StringTemplate^PREVIEW конкатенируется с первым фрагментом следующего. Для примера, если у нас есть две строки, и мы объединяем их следующим образом:

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

последний символ "c" первой строки сопоставляется с первым символом "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"));

Списки значений просто конкатенируются для получения одного списка значений. Результатом является правильно сформированный StringTemplate^PREVIEW с n+1 фрагментами и n значениями, где n — общее количество значений во всех переданных StringTemplates^PREVIEW.

Примечание реализации:: Если предоставлено ноль аргументов StringTemplate^PREVIEW, то возвращается StringTemplate^PREVIEW с пустым фрагментом и без значений, как если бы был вызван StringTemplate.of("") . Если передан только один аргумент StringTemplate^PREVIEW, то он возвращается без изменений.
Параметры:: stringTemplates - ноль или более StringTemplate^PREVIEW
Возвращает:: объединённый StringTemplate^PREVIEW
Исключения:: NullPointerException - если stringTemplates равно null или если любой из stringTemplates равен null

combine

static StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)

Объединить список StringTemplates^PREVIEW в один StringTemplate^PREVIEW.

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

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

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"));

Примечание реализации:: Если stringTemplates.size() == 0 , то возвращается StringTemplate^PREVIEW с пустым фрагментом и без значений, как если бы был вызван StringTemplate.of("") . Если stringTemplates.size() == 1 , то возвращается первый элемент списка без изменений.
Параметры:: stringTemplates - список StringTemplate^PREVIEW
Возвращает:: объединённый StringTemplate^PREVIEW
Исключения:: NullPointerException - если stringTemplates равно null или если любой из его элементов равен null

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/StringTemplate.html