OpenJDK 1.22 · java.util.FormatProcessor

This Processor constructs a String result using Formatter specifications and values found in the StringTemplate. Unlike Formatter, FormatProcessor uses the value from the embedded expression that immediately follows, without whitespace, the format specifier. For example:

FormatProcessor fmt = FormatProcessor.create(Locale.ROOT);
int x = 10;
int y = 20;
String result = fmt."%05d\{x} + %05d\{y} = %05d\{x + y}";

In the above example, the value of result will be "00010 + 00020 = 00030".

Embedded expressions without a preceeding format specifier, use %s by default.

FormatProcessor fmt = FormatProcessor.create(Locale.ROOT);
int x = 10;
int y = 20;
String result1 = fmt."\{x} + \{y} = \{x + y}";
String result2 = fmt."%s\{x} + %s\{y} = %s\{x + y}";

In the above example, the value of result1 and result2 will both be "10 + 20 = 30".

The FormatProcessor format specification used and exceptions thrown are the same as those of Formatter.

However, there are two significant differences related to the position of arguments. An explict n$ and relative < index will cause an exception due to a missing argument list. Whitespace appearing between the specification and the embedded expression will also cause an exception.

FormatProcessor allows the use of different locales. For example:

Locale locale = Locale.forLanguageTag("th-TH-u-nu-thai");
FormatProcessor thaiFMT = FormatProcessor.create(locale);
int x = 10;
int y = 20;
String result = thaiFMT."%4d\{x} + %4d\{y} = %5d\{x + y}";

In the above example, the value of result will be " ๑๐ + ๒๐ = ๓๐".

For day to day use, the predefined FormatProcessor#FMT FormatProcessor is available. FormatProcessor#FMT is defined using the Locale#ROOT. Example:

int x = 10;
int y = 20;
String result = FMT."0x%04x\{x} + 0x%04x\{y} = 0x%04x\{x + y}";

In the above example, the value of result will be "0x000a + 0x0014 = 0x001E".

Field Summary

Modifier and Type	Field and Description
public static final FormatProcessor	FMT This predefined `FormatProcessor` instance constructs a `String` result using the Locale.ROOT `Locale`.
private final Locale	locale `Locale` used to format

Constructor Summary

Access	Constructor and Description
private	FormatProcessor(Locale `Locale` used to format locale) Constructor.

Method Summary

Modifier and Type	Method and Description
public static FormatProcessor	Returns: a new instance of `FormatProcessor` create(Locale `Locale` used to format locale) Create a new `FormatProcessor` using the specified locale.
private static boolean	Returns: true if the specification is found and needed findFormat(String fragment to check fragment, boolean if the specification is needed needed) Find a format specification at the end of a fragment.
public MethodHandle	linkage(List<String> string template fragments fragments, MethodType method type, includes the StringTemplate receiver as well as the value types type) Implements java.lang.StringTemplate.Processor.Linkage.linkage. Constructs a `MethodHandle` that when supplied with the values from a `StringTemplate` will produce a result equivalent to that provided by `FormatProcessor#process(StringTemplate)`.
public final String	Returns: constructed `String` process(StringTemplate a `StringTemplate` instance stringTemplate) Implements java.lang.StringTemplate.Processor.process. Constructs a `String` based on the fragments, format specifications found in the fragments and values in the supplied `StringTemplate` object.
private static String	Returns: format string stringTemplateFormat(List<String> string template fragments fragments) Convert `StringTemplate` fragments, containing format specifications, to a form that can be passed on to `Formatter`.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

FMT back to summary

FMT	back to summary
public static final FormatProcessor FMT This predefined `FormatProcessor` instance constructs a `String` result using the Locale.ROOT `Locale`. See `FormatProcessor` for more details. Example: `int x = 10; int y = 20; String result = FMT."0x%04x\{x} + 0x%04x\{y} = 0x%04x\{x + y}";` int x = 10; int y = 20; String result = FMT."0x%04x\{x} + 0x%04x\{y} = 0x%04x\{x + y}"; In the above example, the value of `result` will be `"0x000a + 0x0014 = 0x001E"`. See Also `java.util.FormatProcessor`

public static final FormatProcessor FMT

This predefined FormatProcessor instance constructs a String result using the Locale.ROOT Locale. See FormatProcessor for more details. Example:

int x = 10;
int y = 20;
String result = FMT."0x%04x\{x} + 0x%04x\{y} = 0x%04x\{x + y}";

In the above example, the value of result will be "0x000a + 0x0014 = 0x001E".

See Also: java.util.FormatProcessor

locale	back to summary
private final Locale locale `Locale` used to format

Constructor Detail

FormatProcessor back to summary

FormatProcessor	back to summary
private FormatProcessor(Locale locale) Constructor. Parameters locale:Locale `Locale` used to format

private FormatProcessor(Locale locale)

Constructor.

Parameters

locale:Locale: Locale used to format

Method Detail

create back to summary

create	back to summary
public static FormatProcessor create(Locale locale) Create a new `FormatProcessor` using the specified locale. Parameters locale:Locale `Locale` used to format Returns:FormatProcessor a new instance of `FormatProcessor` Exceptions NullPointerException: if locale is null

public static FormatProcessor create(Locale locale)

Create a new FormatProcessor using the specified locale.

Parameters

locale:Locale: Locale used to format

Returns:FormatProcessor

a new instance of FormatProcessor

Exceptions

NullPointerException:: if locale is null

findFormat	back to summary
private static boolean findFormat(String fragment, boolean needed) Find a format specification at the end of a fragment. Parameters fragment:String fragment to check needed:boolean if the specification is needed Returns:boolean true if the specification is found and needed Exceptions MissingFormatArgumentException: if not at end or found and not needed

findFormat

back to summary

private static boolean findFormat(String fragment, boolean needed)

Find a format specification at the end of a fragment.

Parameters

fragment:String: fragment to check
needed:boolean: if the specification is needed

Returns:boolean

true if the specification is found and needed

Exceptions

MissingFormatArgumentException:: if not at end or found and not needed

linkage back to summary

linkage	back to summary
public MethodHandle linkage(List<String> fragments, MethodType type) Implements java.lang.StringTemplate.Processor.Linkage.linkage. Constructs a `MethodHandle` that when supplied with the values from a `StringTemplate` will produce a result equivalent to that provided by `FormatProcessor#process(StringTemplate)`. This `MethodHandle` is used by `FormatProcessor#FMT` and the ilk to perform a more specialized composition of a result. This specialization is done by prescanning the fragments and value types of a `StringTemplate`. Process template expressions can be specialized when the processor is of type `Linkage` and fetched from a static constant as is `FormatProcessor#FMT` (`static final FormatProcessor`). Other `FormatProcessors` can be specialized when stored in a static final. For example: `FormatProcessor THAI_FMT = FormatProcessor.create(Locale.forLanguageTag("th-TH-u-nu-thai"));` FormatProcessor THAI_FMT = FormatProcessor.create(Locale.forLanguageTag("th-TH-u-nu-thai")); `THAI_FMT` will now produce specialized `MethodHandles` by way of `FormatProcessor#linkage(List, MethodType)`. See `FormatProcessor#process(StringTemplate)` for more information. Parameters fragments:List<String> Doc from java.lang.StringTemplate.Processor.Linkage.linkage. string template fragments type:MethodType Doc from java.lang.StringTemplate.Processor.Linkage.linkage. method type, includes the StringTemplate receiver as well as the value types Returns:MethodHandle Doc from java.lang.StringTemplate.Processor.Linkage.linkage. `MethodHandle` for the processor applied to template Annotations @Override Exceptions IllegalFormatException: If a format specifier contains an illegal syntax, a format specifier that is incompatible with the given arguments, a specifier not followed immediately by an embedded expression or other illegal conditions. For specification of all possible formatting errors, see the details section of the formatter class specification. NullPointerException: if fragments or type is null See Also `java.util.Formatter`

public MethodHandle linkage(List<String> fragments, MethodType type)

Implements java.lang.StringTemplate.Processor.Linkage.linkage.

Constructs a MethodHandle that when supplied with the values from a StringTemplate will produce a result equivalent to that provided by FormatProcessor#process(StringTemplate). This MethodHandle is used by FormatProcessor#FMT and the ilk to perform a more specialized composition of a result. This specialization is done by prescanning the fragments and value types of a StringTemplate.

Process template expressions can be specialized when the processor is of type Linkage and fetched from a static constant as is FormatProcessor#FMT (static final FormatProcessor).

Other FormatProcessors can be specialized when stored in a static final. For example:

FormatProcessor THAI_FMT = FormatProcessor.create(Locale.forLanguageTag("th-TH-u-nu-thai"));

THAI_FMT will now produce specialized MethodHandles by way of FormatProcessor#linkage(List, MethodType). See FormatProcessor#process(StringTemplate) for more information.

Parameters

fragments:List<String>

Doc from java.lang.StringTemplate.Processor.Linkage.linkage.

string template fragments

type:MethodType

Doc from java.lang.StringTemplate.Processor.Linkage.linkage.

method type, includes the StringTemplate receiver as well as the value types

Returns:MethodHandle

Doc from java.lang.StringTemplate.Processor.Linkage.linkage.

MethodHandle for the processor applied to template

Annotations

@Override

Exceptions

IllegalFormatException:: If a format specifier contains an illegal syntax, a format specifier that is incompatible with the given arguments, a specifier not followed immediately by an embedded expression or other illegal conditions. For specification of all possible formatting errors, see the details section of the formatter class specification.
NullPointerException:: if fragments or type is null

See Also

java.util.Formatter

process back to summary

process	back to summary
public final String process(StringTemplate stringTemplate) Implements java.lang.StringTemplate.Processor.process. Constructs a `String` based on the fragments, format specifications found in the fragments and values in the supplied `StringTemplate` object. This method constructs a format string from the fragments, gathers up the values and evaluates the expression asif evaulating `new Formatter(locale).format(format, values).toString()`. If an embedded expression is not immediately preceded by a specifier then a `%s` is inserted in the format. Parameters stringTemplate:StringTemplate a `StringTemplate` instance Returns:String constructed `String` Annotations @Override Exceptions IllegalFormatException: If a format specifier contains an illegal syntax, a format specifier that is incompatible with the given arguments, a specifier not followed immediately by an embedded expression or other illegal conditions. For specification of all possible formatting errors, see the details section of the formatter class specification. NullPointerException: if stringTemplate is null See Also `java.util.Formatter`

public final String process(StringTemplate stringTemplate)

Implements java.lang.StringTemplate.Processor.process.

Constructs a String based on the fragments, format specifications found in the fragments and values in the supplied StringTemplate object. This method constructs a format string from the fragments, gathers up the values and evaluates the expression asif evaulating new Formatter(locale).format(format, values).toString().

If an embedded expression is not immediately preceded by a specifier then a %s is inserted in the format.

Parameters

stringTemplate:StringTemplate: a StringTemplate instance

Returns:String

constructed String

Annotations

@Override

Exceptions

IllegalFormatException:: If a format specifier contains an illegal syntax, a format specifier that is incompatible with the given arguments, a specifier not followed immediately by an embedded expression or other illegal conditions. For specification of all possible formatting errors, see the details section of the formatter class specification.
NullPointerException:: if stringTemplate is null

See Also

java.util.Formatter

stringTemplateFormat back to summary

stringTemplateFormat	back to summary
private static String stringTemplateFormat(List<String> fragments) Convert `StringTemplate` fragments, containing format specifications, to a form that can be passed on to `Formatter`. The method scans each fragment, matching up formatter specifications with the following expression. If no specification is found, the method inserts "%s". Parameters fragments:List<String> string template fragments Returns:String format string

private static String stringTemplateFormat(List<String> fragments)

Convert StringTemplate fragments, containing format specifications, to a form that can be passed on to Formatter. The method scans each fragment, matching up formatter specifications with the following expression. If no specification is found, the method inserts "%s".

Parameters

fragments:List<String>: string template fragments

Returns:String

format string

public final Class FormatProcessor

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail