Package org.apache.juneau.commons.lang

Class StringFormat

java.lang.Object
org.apache.juneau.commons.lang.StringFormat
public final class StringFormat extends Object
Printf-style string formatter with a small cache and lenient argument handling.

This class provides a thread-safe, cacheable formatter for printf-style (Formatter) patterns ("%s", "%d", "%.2f", "%1$s", etc.). MessageFormat-style ("{0}") patterns are not recognized here — { and ' are treated as literal text. For MessageFormat rendering use StringUtils.mformat(String, Object...) / Shorts.mf(...)/Shorts.mfs(...) (backed by MessageFormat).

Features:
  • Printf grammar: "%s", "%d", "%.2f", "%1$s", etc.
  • Thread-Safe: Immutable class, safe for concurrent use
  • Cacheable: Use ofPrintf(String) for cached instances
  • Lenient null handling: null arguments render as "null" for string conversions (rather than throwing) and a fast path avoids Formatter for simple "%s" tokens
Examples:

// Simple printf StringFormat fmt = StringFormat.ofPrintf("Hello %s, you have %d items"); String result = fmt.format("John", 5); // Returns: "Hello John, you have 5 items" // Argument index (reuse arguments) StringFormat fmt2 = StringFormat.ofPrintf("%1$s loves %2$s, and %1$s also loves %3$s"); String result2 = fmt2.format("Alice", "Bob", "Charlie"); // Returns: "Alice loves Bob, and Alice also loves Charlie"

Caching:

Use ofPrintf(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 printf StringFormat instance.

      { and ' are treated as literal text (genuine Formatter semantics); only printf-style placeholders are recognized.

      Parameters:
      pattern - The format pattern.
      Throws:
      IllegalArgumentException - If the pattern is null.

  • Method Details

    • formatPrintf

      public static String formatPrintf(String pattern, Object... args)
      Formats a pattern string with the given arguments using printf-style semantics.

      { and ' are literal text, matching Formatter semantics. If no arguments are passed in, the pattern is 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.

    • formatPrintf

      public static String formatPrintf(String pattern, Locale locale, Object... args)
      Formats a pattern string with the given arguments using printf-style semantics and the specified locale.
      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.

    • ofPrintf

      public static StringFormat ofPrintf(String pattern)
      Returns a cached printf 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. { and ' are treated as literal text (genuine Formatter semantics); only printf-style placeholders are recognized.

      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 locale-specific printf 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
      • 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
      • S = StringFormat (printf) token
      • Format character: 's' = simple, 'z' = complex printf
      • Index: 0-based argument index
      • Content: The format string content (for complex tokens)
      Examples:

      StringFormat fmt = StringFormat.ofPrintf("Hello %s, you have %d items"); fmt.toPattern(); // Returns: "[L:Hello ][S:s0:%s][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