Package org.apache.juneau.commons.lang

Class StringFormat

java.lang.Object
org.apache.juneau.commons.lang.StringFormat
public final class StringFormat extends Object
Unified string formatter supporting both MessageFormat-style and printf-style formatting in the same pattern.

This class provides a thread-safe, cacheable formatter that can handle mixed format styles in a single pattern. It supports both MessageFormat syntax ("{0}", "{1,number}") and printf syntax ("%s", "%d") within the same string.

Features:
  • Dual Format Support: Mix MessageFormat and printf-style placeholders in the same pattern
  • Thread-Safe: Immutable class, safe for concurrent use
  • Cacheable: Use of(String) for cached instances
  • Argument Sharing: Both format styles share the same argument array
Format Style Detection:

The formatter automatically detects which style to use for each placeholder:

  • MessageFormat style: "{0}", "{1,number}", "{2,date}", etc.
  • Printf style: "%s", "%d", "%.2f", "%1$s", etc.
Argument Mapping:

Arguments are processed in order of appearance:

  • MessageFormat placeholders: Use explicit indices (e.g., "{0}" uses args[0])
  • Printf placeholders: Use sequential indices starting after the highest MessageFormat index
Examples:

// Mixed format styles StringFormat fmt = StringFormat.of("Hello {0}, you have %d items"); String result = fmt.format("John", 5); // Returns: "Hello John, you have 5 items" // MessageFormat with explicit indices, printf with sequential StringFormat fmt2 = StringFormat.of("User {0} has %s and {1} items"); String result2 = fmt2.format("Alice", 10, "admin"); // Returns: "User Alice has admin and 10 items" // {0} -> "Alice", {1} -> 10, %s -> "admin" // Printf with explicit indices StringFormat fmt3 = StringFormat.of("%1$s loves %2$s, and {0} also loves %3$s"); String result3 = fmt3.format("Alice", "Bob", "Charlie"); // Returns: "Alice loves Bob, and Alice also loves Charlie"

Caching:

Use of(String) to get cached instances. The cache is thread-safe and limited to 1000 entries. For uncached instances, use the constructor directly.

Thread Safety:

This class is immutable and thread-safe. Multiple threads can safely use the same instance concurrently.

See Also:

  • Constructor Details

    • StringFormat

      public StringFormat(String pattern)
      Creates a new StringFormat instance.
      Parameters:
      pattern - The format pattern. Can contain both MessageFormat and printf-style placeholders.
      Throws:
      IllegalArgumentException - If the pattern is null.

  • Method Details

    • format

      public static String format(String pattern, Locale locale, Object... args)
      Formats a pattern string with the given arguments using the specified locale.

      This is a convenience method that creates a StringFormat instance and formats it. If no arguments are passed in, the pattern is returned as-is.

      Parameters:
      pattern - The format pattern.
      locale - The locale to use for formatting. If null, uses the default locale.
      args - The arguments to format.
      Returns:
      The formatted string.
      Throws:
      IllegalArgumentException - If the pattern is null or format specifiers are invalid.

    • format

      public static String format(String pattern, Object... args)
      Formats a pattern string with the given arguments using the default locale.

      This is a convenience method that creates a StringFormat instance and formats it. If no arguments are passed in, the pattern is simply returned as-is.

      Parameters:
      pattern - The format pattern.
      args - The arguments to format.
      Returns:
      The formatted string.
      Throws:
      IllegalArgumentException - If the pattern is null or format specifiers are invalid.

    • of

      public static StringFormat of(String pattern)
      Returns a cached StringFormat instance for the given pattern.

      This method uses a thread-safe cache to avoid recreating StringFormat instances for the same pattern. The cache is limited to 1000 entries.

      Parameters:
      pattern - The format pattern.
      Returns:
      A cached or new StringFormat instance.
      Throws:
      IllegalArgumentException - If the pattern is null.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • format

      public String format(Locale locale, Object... args)
      Formats the pattern with the given arguments using the specified locale.

      The locale affects both MessageFormat and printf-style formatting:

      • MessageFormat: Locale-specific number, date, and time formatting
      • Printf: Locale-specific number formatting (decimal separators, etc.)
      Parameters:
      locale - The locale to use for formatting. If null, uses the default locale.
      args - The arguments to format.
      Returns:
      The formatted string.
      Throws:
      IllegalArgumentException - If format specifiers are invalid or arguments don't match.

    • format

      public String format(Object... args)
      Formats the pattern with the given arguments using the default locale.
      Parameters:
      args - The arguments to format.
      Returns:
      The formatted string.
      Throws:
      IllegalArgumentException - If format specifiers are invalid or arguments don't match.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toPattern

      public String toPattern()
      Returns a debug representation of the parsed pattern showing the token structure.

      This method is useful for debugging and understanding how a pattern was parsed. It returns a string showing each token in the format:

      • Literal tokens: "[L:text]" - Literal text
      • MessageFormat tokens (simple): "[M:s0]" - Simple MessageFormat placeholder (format='s', index=0)
      • MessageFormat tokens (complex): "[M:o0:{0,number,currency}]" - Complex MessageFormat placeholder (format='o', index=0, content)
      • StringFormat tokens (simple): "[S:s0:%s]" - Simple printf placeholder (format='s', index=0, content)
      • StringFormat tokens (complex): "[S:z0:%.2f]" - Complex printf placeholder (format='z', index=0, content)
      Token Format:
      • L = Literal token
      • M = MessageFormat token
      • S = StringFormat (printf) token
      • Format character: 's' = simple, 'o' = other/complex, 'z' = complex printf
      • Index: 0-based argument index
      • Content: The format string content (for complex tokens)
      Examples:

      StringFormat fmt = StringFormat.of("Hello {0}, you have %d items"); fmt.toPattern(); // Returns: "[L:Hello ][M:s0][L:, you have ][S:d1:%d][L: items]"

      Returns:
      A debug string showing the parsed token structure.

    • toString

      public String toString()
      Overrides:
      toString in class Object