Package io.github.zazalng.utils

Class FormatTemplate

java.lang.Object
io.github.zazalng.utils.FormatTemplate
public final class FormatTemplate extends Object
Immutable template for custom format strings with named placeholder support (v1.4.0+).

This class encapsulates a custom format string and provides validation to ensure the format is valid before use. All instances are immutable and thread-safe. Format templates enable precise control over how monetary amounts are displayed in text form.

Supported Placeholders

All placeholders must be wrapped in curly braces. The following placeholders are recognized:

Required Placeholders

  • {INTEGER} - The baht (integer) part of the amount as text. This placeholder is mandatory and must appear in every format.
  • {FLOAT} - The satang (fractional) part as text. This placeholder is mandatory and must appear in every format.

Optional Currency Placeholders

  • {UNIT} - Currency unit word ("บาท"/"Baht")
  • {EXACT} - Exact/only indicator ("ถ้วน"/"Only") shown when satang = 0
  • {SATANG} - Satang unit word ("สตางค์"/"Satang")
  • {NEGPREFIX} - Negative prefix ("ลบ"/"Minus") for negative format only

Conditional Placeholders

Conditional placeholders allow content to be shown or hidden based on whether satang is zero:

  • {FLOAT?content} - Show content only if satang is not zero. Useful for omitting satang when there are no fractional units.
  • {SATANG?content} - Show content only if satang is not zero. Useful for conditional unit word inclusion.

Conditional content can contain arbitrary text and other placeholders, supporting complex nested structures.

Validation and Requirements

Format strings are validated at construction time to ensure:

  • The string is not null or empty
  • Both {INTEGER} and {FLOAT} placeholders are present
  • If validation fails, an IllegalArgumentException is thrown with a descriptive message

Validation errors: 


 // Will throw: Missing {INTEGER}
 FormatTemplate.of("{FLOAT}");

 // Will throw: Missing {FLOAT}
 FormatTemplate.of("{INTEGER}");

 // OK: Both required placeholders present
 FormatTemplate.of("{INTEGER}{FLOAT}");

Usage Examples

Basic Thai Format


 FormatTemplate template = FormatTemplate.of("{INTEGER}{UNIT}{FLOAT?{FLOAT}{SATANG}}");
 // Output for 100.50: "หนึ่งร้อยบาทห้าสิบสตางค์"
 // Output for 100.00: "หนึ่งร้อยบาท"

English with Explicit Exact Value


 FormatTemplate template = FormatTemplate.of("{INTEGER} {UNIT} {EXACT}{FLOAT? {FLOAT} {SATANG}}");
 // Output for 100.50: "One Hundred Baht Fifty Satang"
 // Output for 100.00: "One Hundred Baht Only"

Parenthesized Negative Format


 FormatTemplate template = FormatTemplate.of("({NEGPREFIX} {INTEGER}{UNIT}{EXACT}{FLOAT? {FLOAT} {SATANG}})");
 // Output for negative 100.50: "(ลบ หนึ่งร้อยบาทห้าสิบสตางค์)"

Advanced with Conjunctions


 FormatTemplate template = FormatTemplate.of(
     "{INTEGER}{UNIT}{FLOAT?และ{FLOAT}{SATANG}}"
 );
 // Output for 100.50: "หนึ่งร้อยบาทและห้าสิบสตางค์"
 // Output for 100.00: "หนึ่งร้อยบาท"

Immutability and Thread Safety

This class is fully immutable - all fields are private, final, and set at construction time. Instances are safe to share across threads without synchronization. Format templates can be constructed once and reused across multiple configurations.

Example - reusing format templates: 


 // Create template once
 FormatTemplate template = FormatTemplate.of("{INTEGER}{UNIT}{FLOAT?{FLOAT}{SATANG}}");

 // Reuse in multiple configurations
 ThaiBahtConfig config1 = ThaiBahtConfig.builder()
     .setFormatTemplate(template)
     .build();

 ThaiBahtConfig config2 = ThaiBahtConfig.builder(Language.ENGLISH)
     .setFormatTemplate(template)
     .build();
Since:
1.4.0
Author:
Zazalng
See Also:

  • Method Details

    • of

      public static FormatTemplate of(String formatString)
      Creates a FormatTemplate from a format string.

      This factory method constructs an immutable FormatTemplate that encapsulates the given format string. The format string is validated to ensure it contains the required placeholders before creating the template.

      Example usage: 

      
 // Create template with conditional satang
 FormatTemplate template = FormatTemplate.of(
     "{INTEGER}{UNIT}{EXACT}{FLOAT?{FLOAT}{SATANG}}"
 );

 // Use in configuration
 ThaiBahtConfig config = ThaiBahtConfig.builder()
     .setFormatTemplate(template)
     .build();
      Parameters:
      formatString - the format string with named placeholders
      Returns:
      a new immutable FormatTemplate with the given format string
      Throws:
      IllegalArgumentException - if format string is invalid (null, empty, or missing required placeholders)
      Since:
      1.4.0

    • getTemplate

      public String getTemplate()
      Returns the original format string with its named placeholders.

      The returned string is the exact format string provided at construction time, with all placeholders intact. This can be used for debugging, logging, or for creating modified templates.

      Returns:
      the original format string, never null or empty
      Since:
      1.4.0

    • toString

      public String toString()
      Returns a string representation of this FormatTemplate.

      This method returns the template string itself, making it easy to use FormatTemplate objects in string contexts (e.g., logging, debugging).

      Overrides:
      toString in class Object
      Returns:
      the format string, never null