<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
</head>
<body style="word-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;" class="">
CSR and available docs have been changed to reflect these changes.
<div class=""><br class="">
</div>
<div class=""><a href="https://cr.openjdk.java.net/~jlaskey/templates/docs/api/java.base/java/lang/template/StringTemplate.html" class="">https://cr.openjdk.java.net/~jlaskey/templates/docs/api/java.base/java/lang/template/StringTemplate.html</a></div>
<div class=""><br class="">
</div>
<div class="">Cheers,</div>
<div class=""><br class="">
</div>
<div class="">— Jim</div>
<div class=""><br class="">
<div><br class="">
<blockquote type="cite" class="">
<div class="">On Nov 16, 2022, at 3:10 PM, Alex Buckley <<a href="mailto:alex.buckley@oracle.com" class="">alex.buckley@oracle.com</a>> wrote:</div>
<br class="Apple-interchange-newline">
<div class="">
<div class="">Below, a revised description for `StringTemplate`.<br class="">
<br class="">
<br class="">
// High-level opener.<br class="">
<br class="">
`StringTemplate` is the run-time representation of a string template or text block template in a template expression.<br class="">
<br class="">
[Sidebar. The JEP says "An instance of StringTemplate represents the string template or text block template that appears either as the template in a template expression, or as a standalone literal." -- the 'standalone literal' clause should be deleted.]<br class="">
<br class="">
// Basic concepts. No need to spell out details like immutability or return types here; leave them for the method specs.<br class="">
<br class="">
In the source code of a Java program, a string template or text block template contains an interleaved succession of _fragment literals_ and _embedded expressions_. The `fragments()` method returns the fragment literals, and the `values()` method returns the
results of evaluating the embedded expressions. `StringTemplate` does not provide access to the source code of the embedded expressions themselves; it is not a compile-time representation of a string template or text block template.<br class="">
<br class="">
// Usage<br class="">
<br class="">
`StringTemplate` is primarily used in conjunction with a template processor to produce a string or other useful value. Evaluation of a template expression first produces an instance of `StringTemplate`, representing the template of the template expression,
and then passes the instance to the template processor given by the template expression.<br class="">
<br class="">
For example, the following code contains a template expression that uses the template processor `RAW`, which simply yields the `StringTemplate` passed to it:<br class="">
<br class="">
int x = 10;<br class="">
int y = 20;<br class="">
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";<br class="">
List<String> fragments = st.fragments();<br class="">
List<Object> values = st.values();<br class="">
<br class="">
`fragments` will be equivalent to `List.of(" + ", " = ")` and `values` will be the equivalent of `List.of(10, 20, 30)`.<br class="">
<br class="">
The following code contains a template expression with the same template but a different template processor:<br class="">
<br class="">
int x = 10;<br class="">
int y = 20;<br class="">
String s = STR."\{x} + \{y} = \{x + y}";<br class="">
<br class="">
When the template expression is evaluated, an instance of `StringTemplate` is produced that returns the same lists from `fragments()` and `values()` as shown above. The `STR` template processor uses these lists to yield an interpolated string. `s` will be equivalent
to `"10 + 20 = 30"`.<br class="">
<br class="">
The `interpolate()` method provides a direct way to perform string interpolation of a `StringTemplate`. Template processors can use the following code pattern:<br class="">
<br class="">
List<String> fragments = st.fragments();<br class="">
List<Object> values = st.values();<br class="">
... check or manipulate the fragments and/or values ...<br class="">
String result = StringTemplate.interpolate(fragments, values);<br class="">
<br class="">
The `process(ValidatingProcessor)` method provides an alternative to using string template expressions. [Sidebar. The example line of code which follows, is using a template expression. I'm not sure what was meant here.]<br class="">
<br class="">
String result = RAW."\{x} + \{y} = \{x + y}".process(STR);<br class="">
<br class="">
The factory methods `of(String)` and `of(List, List)` can be used to construct a `StringTemplate`.<br class="">
<br class="">
@implNote: Implementations of `StringTemplate` must minimally implement the methods fragments() and values(). Instances of `StringTemplate` are considered immutable. To preserve the semantics of string templates and text block templates, the list returned by
`fragments()` must be one element larger than the list returned by `values()`.<br class="">
<br class="">
@jls 15.8.6<br class="">
<br class="">
<br class="">
Alex<br class="">
<br class="">
On 11/16/2022 4:49 AM, Jim Laskey wrote:<br class="">
<blockquote type="cite" class="">May I get a final (PR) review of JDK-8285932 Implementation of JEP-430 String Templates (Preview) from core-libs and compiler.<br class="">
PR: <a href="https://github.com/openjdk/jdk/pull/10889" class="">https://github.com/openjdk/jdk/pull/10889</a> <<a href="https://github.com/openjdk/jdk/pull/10889" class="">https://github.com/openjdk/jdk/pull/10889</a>><br class="">
JBS: <a href="https://bugs.openjdk.org/browse/JDK-8285932" class="">https://bugs.openjdk.org/browse/JDK-8285932</a> <<a href="https://bugs.openjdk.org/browse/JDK-8285932" class="">https://bugs.openjdk.org/browse/JDK-8285932</a>><br class="">
CSR: <a href="https://bugs.openjdk.org/browse/JDK-8286021" class="">https://bugs.openjdk.org/browse/JDK-8286021</a> <<a href="https://bugs.openjdk.org/browse/JDK-8286021" class="">https://bugs.openjdk.org/browse/JDK-8286021</a>><br class="">
JEP: <a href="https://openjdk.org/jeps/430" class="">https://openjdk.org/jeps/430</a> <<a href="https://openjdk.org/jeps/430" class="">https://openjdk.org/jeps/430</a>>
<a href="https://bugs.openjdk.org/browse/JDK-8273943" class="">https://bugs.openjdk.org/browse/JDK-8273943</a> <<a href="https://bugs.openjdk.org/browse/JDK-8273943" class="">https://bugs.openjdk.org/browse/JDK-8273943</a>><br class="">
SPEC: <a href="https://bugs.openjdk.org/browse/JDK-8296302" class="">https://bugs.openjdk.org/browse/JDK-8296302</a> <<a href="https://bugs.openjdk.org/browse/JDK-8296302" class="">https://bugs.openjdk.org/browse/JDK-8296302</a>><br class="">
Thank you.<br class="">
Cheers,<br class="">
— Jim<br class="">
</blockquote>
</div>
</div>
</blockquote>
</div>
<br class="">
</div>
</body>
</html>