Class Fmt

java.lang.Object
io.github.connellite.format.Fmt

public final class Fmt extends Object
Java port of {fmt} replacement-field formatting (fmtlib 11.2). Type p prints 0x and the reference bits of the argument; null is 0x0.

Grammar and presentation types follow fmt 11.2 syntax: replacement_field ::= "{" [arg_id] [":" format_spec] "}" and format_spec ::= [[fill]align][sign]["#"]["0"][width]["." precision]["L"][type]. Implementation references: format.h (write_escaped_string at L1763), ranges.h, chrono.h.

Null arguments (similar in spirit to SLF4J / typical Java logging): with no format spec, values use a default string form (like String.valueOf(Object) for non-arrays); null becomes "null" (no NPE). Arrays render as [1, 2, 3] with nesting, not [I@….

Radix: types b/B produce binary (optional alternate # → 0b/0B); d/i, x, o use sign-and-magnitude for negatives ({:x} of -42 is -2a); # adds 0x/0/0b after the sign. Type S upper-cases a string. bits / Bf print IEEE-754 bit patterns (Java extras).

Debug (?): strings and characters are quoted and escaped as in fmt write_escaped_string / write_escaped_char.

Ranges (arrays, Iterable, Map): empty spec follows fmt (["a"], {'x'}, {"k": 1}); {::spec}, n, s/?s follow range_format_spec. {::} uses an empty element spec (unquoted strings/chars).

Chrono: empty spec is fmt default (%F %T for date-times, %F for dates, tick+unit for Duration). With a spec, [[fill]align][width][.precision] then strftime (%Y, %F, glibc %-H/%_S/%OS, …) per chrono_format_spec. Duration also accepts time-of-day conversions and %Q/%q (Java Duration ticks: seconds, or ms/us/ns when there is a fraction).

Sign (after ':', before type): + always; a single leading space flag for positives; - default (only minus for negatives), same as omitting a sign flag.

Dynamic spec: nested braces in the part after ':' pull further arguments, e.g. Fmt.format(Locale.US, "{:.{}f}", 3.14, 1) → "3.1" (decimal separator follows Locale).

Named fields ({name}) are supplied with arg(String, Object) in the varargs list. Specs that are not a format_spec fall back to String.format(java.lang.String, java.lang.Object...)("%" + spec).

String overloads of format and formatTo reuse a compiled form for a pattern of at most 256 characters. compile(CharSequence) always parses anew.

See Also:
  • Constructor Details

    • Fmt

      public Fmt()
  • Method Details

    • arg

      public static Named arg(String name, Object value)
      Creates a named argument that can be referenced from a template as {name}.
      Parameters:
      name - argument name used in the template
      value - argument value
      Returns:
      immutable named argument wrapper
    • setDefaultLocale

      public static void setDefaultLocale(Locale locale)
      Sets the locale used by overloads that do not accept a locale parameter.
      Parameters:
      locale - new default locale, must not be null
    • toString

      public static String toString(Object value)
      Converts a value to text using the library formatting pipeline.
      Parameters:
      value - value to render
      Returns:
      formatted value string
    • compile

      public static CompiledFormat compile(CharSequence pattern)
      Parses a template and returns a reusable compiled representation. Each call parses pattern again and returns a new instance.
      Parameters:
      pattern - template text
      Returns:
      compiled template
    • format

      public static String format(CharSequence pattern, Object... args)
      Formats a template with positional and named arguments using the current default locale.
      Parameters:
      pattern - template text
      args - formatting arguments
      Returns:
      rendered text
    • format

      public static String format(Locale locale, CharSequence pattern, Object... args)
      Formats a template with an explicit locale.
      Parameters:
      locale - locale for locale-sensitive conversions
      pattern - template text
      args - formatting arguments
      Returns:
      rendered text
    • format

      public static String format(CompiledFormat compiled, Object... args)
      Formats with a precompiled template using the current default locale.
      Parameters:
      compiled - precompiled template
      args - formatting arguments
      Returns:
      rendered text
    • format

      public static String format(Locale locale, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and an explicit locale.
      Parameters:
      locale - locale for locale-sensitive conversions
      compiled - precompiled template
      args - formatting arguments
      Returns:
      rendered text
    • print

      public static void print(CharSequence pattern, Object... args)
      Formats and prints to System.out without a trailing newline.
      Parameters:
      pattern - template text
      args - formatting arguments
    • println

      public static void println(CharSequence pattern, Object... args)
      Formats and prints to System.out with a trailing newline.
      Parameters:
      pattern - template text
      args - formatting arguments
    • print

      public static void print(CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to System.out without newline.
      Parameters:
      compiled - precompiled template
      args - formatting arguments
    • println

      public static void println(CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to System.out with newline.
      Parameters:
      compiled - precompiled template
      args - formatting arguments
    • print

      public static void print(PrintStream out, CharSequence pattern, Object... args)
      Formats and prints to a PrintStream without a trailing newline.
      Parameters:
      out - destination stream
      pattern - template text
      args - formatting arguments
    • println

      public static void println(PrintStream out, CharSequence pattern, Object... args)
      Formats and prints to a PrintStream with a trailing newline.
      Parameters:
      out - destination stream
      pattern - template text
      args - formatting arguments
    • print

      public static void print(PrintStream out, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to a PrintStream.
      Parameters:
      out - destination stream
      compiled - precompiled template
      args - formatting arguments
    • println

      public static void println(PrintStream out, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to a PrintStream with newline.
      Parameters:
      out - destination stream
      compiled - precompiled template
      args - formatting arguments
    • print

      public static void print(PrintWriter out, CharSequence pattern, Object... args)
      Formats and prints to a PrintWriter without a trailing newline.
      Parameters:
      out - destination writer
      pattern - template text
      args - formatting arguments
    • println

      public static void println(PrintWriter out, CharSequence pattern, Object... args)
      Formats and prints to a PrintWriter with a trailing newline.
      Parameters:
      out - destination writer
      pattern - template text
      args - formatting arguments
    • print

      public static void print(PrintWriter out, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to a PrintWriter.
      Parameters:
      out - destination writer
      compiled - precompiled template
      args - formatting arguments
    • println

      public static void println(PrintWriter out, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and prints to a PrintWriter with newline.
      Parameters:
      out - destination writer
      compiled - precompiled template
      args - formatting arguments
    • formatTo

      public static void formatTo(Appendable out, CharSequence pattern, Object... args)
      Formats and appends output to an Appendable using the default locale.
      Parameters:
      out - destination appendable
      pattern - template text
      args - formatting arguments
    • formatTo

      public static void formatTo(Appendable out, Locale locale, CharSequence pattern, Object... args)
      Formats and appends output to an Appendable with an explicit locale.
      Parameters:
      out - destination appendable
      locale - locale for locale-sensitive conversions
      pattern - template text
      args - formatting arguments
    • formatTo

      public static void formatTo(Appendable out, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and appends output using the default locale.
      Parameters:
      out - destination appendable
      compiled - precompiled template
      args - formatting arguments
    • formatTo

      public static void formatTo(Appendable out, Locale locale, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and appends output with an explicit locale.
      Parameters:
      out - destination appendable
      locale - locale for locale-sensitive conversions
      compiled - precompiled template
      args - formatting arguments
    • formatTo

      public static void formatTo(Consumer<? super String> sink, CharSequence pattern, Object... args)
      Formats and passes result chunks to a string sink using the default locale.
      Parameters:
      sink - destination consumer
      pattern - template text
      args - formatting arguments
    • formatTo

      public static void formatTo(Consumer<? super String> sink, Locale locale, CharSequence pattern, Object... args)
      Formats and passes result chunks to a string sink with an explicit locale.
      Parameters:
      sink - destination consumer
      locale - locale for locale-sensitive conversions
      pattern - template text
      args - formatting arguments
    • formatTo

      public static void formatTo(Consumer<? super String> sink, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and passes output chunks to a string sink.
      Parameters:
      sink - destination consumer
      compiled - precompiled template
      args - formatting arguments
    • formatTo

      public static void formatTo(Consumer<? super String> sink, Locale locale, CompiledFormat compiled, Object... args)
      Formats with a precompiled template and passes output chunks to a sink with explicit locale.
      Parameters:
      sink - destination consumer
      locale - locale for locale-sensitive conversions
      compiled - precompiled template
      args - formatting arguments