Struct Formatter 

pub struct Formatter<'a> {
    pub elements: Vec<FormatElement<'a>>,
    pub arg_num: usize,
}

Compatible with java.util.Formatter

Fields

elements: Vec<FormatElement<'a>>

arg_num: usize

Implementations

impl<'a> Formatter<'a>

pub fn new(elements: Vec<FormatElement<'a>>) -> Self

pub fn parse(fmt: &'a str, arg_types: &[DataType]) -> Result<Self>

Parses a printf-style format string into a Formatter with validation.

This method implements a comprehensive parser for Java java.util.Formatter syntax, processing the format string character by character to identify and validate format specifiers against the provided argument types.

Arguments

• fmt - The format string containing literal text and format specifiers
• arg_types - Array of DataFusion DataTypes corresponding to the arguments

Parsing Process

The parser operates in several phases:

1. String Scanning: Iterates through the format string looking for ‘%’ characters that mark the beginning of format specifiers or special sequences.

2. Special Sequence Handling: Processes escape sequences:

   • %% becomes a literal ‘%’ character
   • %n becomes a newline character
   • %< indicates reuse of the previous argument with a new format specifier

3. Argument Index Resolution: Determines which argument each format specifier refers to:

   • Sequential indexing: arguments are consumed in order (1, 2, 3, …)
   • Positional indexing: explicit argument position using %n$ syntax
   • Previous argument reuse: %< references the last used argument

4. Format Specifier Parsing: For each format specifier, extracts:

   • Flags (-, +, space, #, 0, ‘,’, ‘(’)
   • Width specification (minimum field width)
   • Precision specification (decimal places or maximum characters)
   • Conversion type (d, s, f, x, etc.)

5. Type Validation: Verifies that each format specifier’s conversion type is compatible with the corresponding argument’s DataType. For example:

   • Integer conversions (%d, %x, %o) require integer DataTypes
   • String conversions (%s, %S) accept any DataType
   • Float conversions (%f, %e, %g) require numeric DataTypes

6. Element Construction: Creates FormatElement instances for:

   • Verbatim text sections (copied directly to output)
   • Validated format specifiers with their parsed parameters

Internal State Management

The parser maintains several state variables:

• argument_index: Tracks the current sequential argument position
• prev: Remembers the last used argument index for %< references
• res: Accumulates the parsed FormatElement instances
• rem: Points to the remaining unparsed portion of the format string

Validation and Error Handling

The parser performs extensive validation including:

• Argument index bounds checking against the provided arg_types array
• Format specifier syntax validation
• Type compatibility verification between conversion types and DataTypes
• Detection of malformed numeric parameters and invalid flag combinations

Returns

Returns a Formatter containing the parsed elements and the maximum argument index encountered, enabling efficient argument validation during formatting.

pub fn format(&self, args: &[ScalarValue]) -> Result<String>

Trait Implementations

impl<'a> Debug for Formatter<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.