FormatProcessor (Java SE 21 & JDK 21)
Description: declaration: module: java.base, package: java.util, class: FormatProcessor
Keywords: java.util.FormatProcessor class

Module java.base
Package java.util

# Class FormatProcessor

java.lang.Object
java.util.FormatProcessor

All Implemented Interfaces:
  `StringTemplate.ProcessorPREVIEW<String,RuntimeException>`, `StringTemplate.Processor.LinkagePREVIEW`

public final class FormatProcessor extends Object implements StringTemplate.ProcessorPREVIEW<String,RuntimeException>, StringTemplate.Processor.LinkagePREVIEW
`FormatProcessor` is a preview API of the Java platform.
Programs can only use `FormatProcessor` when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
This `StringTemplate.Processor`PREVIEW constructs a `String` result using `Formatter` specifications and values found in the `StringTemplate`PREVIEW. Unlike `Formatter`, `FormatProcessor`PREVIEW 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`PREVIEW 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`PREVIEW 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 `FMT` `FormatProcessor`PREVIEW is available. `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"`.

Since:
  21
See Also:
  - `StringTemplate.Processor`PREVIEW

- ## Nested Class Summary

  ## Nested classes/interfaces declared in interface java.lang.StringTemplate.ProcessorPREVIEW

  `StringTemplate.Processor.LinkagePREVIEW`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final FormatProcessorPREVIEW`
  `FMT`
  This predefined `FormatProcessor`PREVIEW instance constructs a `String` result using the Locale.ROOT `Locale`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static FormatProcessorPREVIEW`
  `create(Locale locale)`
  Create a new `FormatProcessor`PREVIEW using the specified locale.
  `MethodHandle`
  `linkage(List<String> fragments, MethodType type)`
  Constructs a `MethodHandle` that when supplied with the values from a `StringTemplate`PREVIEW will produce a result equivalent to that provided by `process(StringTemplate)`.
  `final String`
  `process(StringTemplatePREVIEW stringTemplate)`
  Constructs a `String` based on the fragments, format specifications found in the fragments and values in the supplied `StringTemplate`PREVIEW object.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### FMT

    public static final FormatProcessorPREVIEW FMT
    This predefined `FormatProcessor`PREVIEW instance constructs a `String` result using the Locale.ROOT `Locale`. See `FormatProcessor`PREVIEW 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:
      - `FormatProcessor`PREVIEW

- ## Method Details

  - ### create

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

  - ### process

    public final String process(StringTemplatePREVIEW stringTemplate)
    Constructs a `String` based on the fragments, format specifications found in the fragments and values in the supplied `StringTemplate`PREVIEW 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.

    Specified by:
      `process` in interface `StringTemplate.ProcessorPREVIEW<String,RuntimeException>`
    Parameters:
      `stringTemplate` - a `StringTemplate`PREVIEW instance
    Returns:
      constructed `String`
    Throws:
      `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:
      - `Formatter`

  - ### linkage

    public MethodHandle linkage(List<String> fragments, MethodType type)
    Constructs a `MethodHandle` that when supplied with the values from a `StringTemplate`PREVIEW will produce a result equivalent to that provided by `process(StringTemplate)`. This `MethodHandle` is used by `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`PREVIEW.

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

    Other `FormatProcessors`PREVIEW 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 `linkage(List, MethodType)`. See `process(StringTemplate)` for more information.
    Specified by:
      `linkage` in interface `StringTemplate.Processor.LinkagePREVIEW`
    Parameters:
      `fragments` - string template fragments
      `type` - method type, includes the StringTemplate receiver as well as the value types
    Returns:
      `MethodHandle` for the processor applied to template
    Throws:
      `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:
      - `Formatter`