String.format, formatted() and printf in Java: The Complete Cheat Sheet

Versions this was tested against. JDK 25.0.5+8 (Temurin LTS; the build date its own java -version reports is 2026-10-20), Maven 3.9.11, JUnit Jupiter 5.11.0. String.formatted() exists since Java 15; the formatting engine itself (java.util.Formatter) has been in the JDK since Java 5. Companion module: java-core-examples/string-format, 11 tests, one command (scripts/run-all.sh) to regenerate every transcript quoted below.

A format string is a sentence with holes in it

System.out.println("== conversions: what kind of value ==");
System.out.println(String.format("%s | %d | %f | %x | %c | %b", "text", 42, 3.14159, 255, 'A', true));

System.out.println("== width: minimum characters ==");
System.out.println(String.format("[%8s] [%-8s] [%8d] [%-8d]", "ab", "ab", 42, 42));

System.out.println("== precision: digits after the point (f), or max chars (s) ==");
System.out.println(String.format("[%.2f] [%.0f] [%8.3f] [%.3s]", 3.14159, 3.5, 3.14159, "abcdef"));

== conversions: what kind of value ==
text | 42 | 3.141590 | ff | A | true
== width: minimum characters ==
[      ab] [ab      ] [      42] [42      ]
== precision: digits after the point (f), or max chars (s) ==
[3.14] [4] [   3.142] [abc]

System.out.println("== flags ==");
System.out.println(String.format("[%05d] [%+d] [%+d] [% d] [%(d] [%,d]", 42, 42, -42, 42, -42, 1234567));
System.out.println(String.format("[%#x] [%#o] [%X] [%08.3f]", 255, 8, 255, -3.14159));

== flags ==
[00042] [+42] [-42] [ 42] [(42)] [1,234,567]
[0xff] [010] [FF] [-003.142]

%b does not parse text. It prints true for any argument that is not null and not a Boolean, so String.format("%b", "false") is true — and so is 0. The last line below comes from output/01-basics.txt, and a test in StringFormatTest pins it.

== %b is not 'is this the string true' ==
true true false false

System.out.println("== argument index: reuse and reorder ==");
System.out.println(String.format("%2$s %1$s", "world", "hello"));
System.out.println(String.format("%1$s, %1$s and again %<s", "echo"));

== argument index: reuse and reorder ==
hello world
echo, echo and again echo

Going deeper

• BasicsDemo.java — the whole file, one change per line
• Formatter Javadoc — the full table of conversions and which flags each accepts
• output/01-basics.txt — the complete transcript

Padding and alignment: make a table line up

String header = String.format("%-18s %5s %10s %12s", "Item", "Qty", "Price", "Total");
System.out.println(header);
System.out.println("-".repeat(header.length()));
double grand = 0;
for (Line l : lines) {
    double total = l.qty() * l.price();
    grand += total;
    System.out.println(String.format("%-18s %5d %10.2f %,12.2f", l.item(), l.qty(), l.price(), total));
}
System.out.println("-".repeat(header.length()));
System.out.println(String.format("%-18s %5s %10s %,12.2f", "Grand total", "", "", grand));

Item                 Qty      Price        Total
------------------------------------------------
Notebook              12      45.50       546.00
Pen (box of 10)        3     120.00       360.00
Stapler                1     350.00       350.00
------------------------------------------------
Grand total                             1,256.00

System.out.println("== truncation: %.Ns cuts, width pads ==");
System.out.println(String.format("[%-10.6s] [%10.6s]", "Pen (box of 10)", "Pen (box of 10)"));

== truncation: %.Ns cuts, width pads ==
[Pen (b    ] [    Pen (b]

Going deeper

• ReportTableDemo.java — the invoice table, the printf variant and the truncation example
• Formatter Javadoc: flags — which flags work with which conversions

Format strings fail at runtime, not at compile time

run("wrong type for %d",          () -> String.format("%d", "42"));
run("too few arguments",          () -> String.format("%s and %s", "one"));
run("unknown conversion",         () -> String.format("%q", 1));
run("precision on an integer",    () -> String.format("%.2d", 5));
run("flag not valid for %x ,",    () -> String.format("%,x", 255));
run("left-justify without width", () -> String.format("%-d", 5));
run("zero pad AND left-justify",  () -> String.format("%-08d", 5));
run("width on %n",                () -> String.format("%5n"));
run("double passed to %d",        () -> String.format("%d", 3.0));
run("int passed to %f",           () -> String.format("%f", 3));
run("a stray % in user text",     () -> String.format("Discount 50% off"));
run("extra arguments (no error)", () -> String.format("%s", "a", "b", "c"));

wrong type for %d            -> IllegalFormatConversionException: d != java.lang.String
too few arguments            -> MissingFormatArgumentException: Format specifier '%s'
unknown conversion           -> UnknownFormatConversionException: Conversion = 'q'
precision on an integer      -> IllegalFormatPrecisionException: 2
flag not valid for %x ,      -> FormatFlagsConversionMismatchException: Conversion = x, Flags = ,
left-justify without width   -> MissingFormatWidthException: %-d
zero pad AND left-justify    -> IllegalFormatFlagsException: Flags = '-0'
width on %n                  -> IllegalFormatWidthException: 5
double passed to %d          -> IllegalFormatConversionException: d != java.lang.Double
int passed to %f             -> IllegalFormatConversionException: f != java.lang.Integer
a stray % in user text       -> MissingFormatArgumentException: Format specifier '% o'
extra arguments (no error)   -> OK: a

“50% off” is not an unknown-conversion error. I expected UnknownFormatConversionException and the test I wrote failed. Java reads % o as the space flag followed by the octal conversion o, so the message is MissingFormatArgumentException: Format specifier '% o' — confusing until you know. If user text can contain a %, never use it as the format string: pass it as an argument (String.format("%s", text)) or write %%.

Too many arguments is silent. The last line of the output shows String.format("%s", "a", "b", "c") returning a with no error. Too few throws; too many is ignored, which hides a forgotten placeholder.

Going deeper

• FormatErrorsDemo.java — the twelve cases
• StringFormatTest.java — each failure pinned as an assertion

Why %.2f sometimes disagrees with C and BigDecimal

System.out.println("== same number, three routes: %f rounds what it is given ==");
System.out.println(String.format("double 2.675                  -> %.2f", 2.675));
System.out.println(String.format("new BigDecimal(\"2.675\")       -> %.2f", new BigDecimal("2.675")));
System.out.println(String.format("new BigDecimal(2.675)         -> %.2f", new BigDecimal(2.675)));

== same number, three routes: %f rounds what it is given ==
double 2.675                  -> 2.68
new BigDecimal("2.675")       -> 2.68
new BigDecimal(2.675)         -> 2.67

C printf   %.2f of 2.675 : 2.67
C printf   %.1f of 0.35  : 0.3
C printf   %.2f of 1.005 : 1.00
C printf   %.2f of 0.125 : 0.12

For money, do not rely on any of this. The new BigDecimal(2.675) line above shows %f rounding the exact value when it is handed a BigDecimal, so building one from a double silently changes the answer. Keep amounts as BigDecimal built from strings, choose the RoundingMode explicitly, and use %f only to display the result.

== %.0f on halves: HALF_UP, away from zero ==
1 2 3 -3

Going deeper

• RoundingDemo.java — the full table of eight values
• Formatter Javadoc: floating point conversions

Locale: the same format string, different text

for (Locale l : new Locale[]{Locale.US, Locale.GERMANY, Locale.FRANCE, Locale.of("en", "IN"), Locale.of("de", "CH"), Locale.ROOT}) {
    String s = String.format(l, "%,.2f", v);
    System.out.println(String.format("%-8s %s", l.toLanguageTag().isEmpty() ? "ROOT" : l.toLanguageTag(), visible(s)));
}

== %,.2f of 1234567.891 ==
en-US    1,234,567.89
de-DE    1.234.567,89
fr-FR    1^234^567,89
en-IN    1,234,567.89
de-CH    1’234’567.89
und      1,234,567.89

Locale saved = Locale.getDefault(Locale.Category.FORMAT);
System.out.println("default (" + saved + ")   : " + String.format("%.2f", 1234.5));
Locale.setDefault(Locale.Category.FORMAT, Locale.GERMANY);
System.out.println("default (de_DE)   : " + String.format("%.2f", 1234.5));
System.out.println("explicit ROOT     : " + String.format(Locale.ROOT, "%.2f", 1234.5));
Locale.setDefault(Locale.Category.FORMAT, saved);

== the bug: changing the default locale changes %.2f ==
default (en_US)   : 1234.50
default (de_DE)   : 1234,50
explicit ROOT     : 1234.50

Machine-readable output needs Locale.ROOT. CSV files, JSON, URLs, SQL and log lines that another program will parse must not change with the server’s locale. Pass Locale.ROOT (or Locale.US) explicitly there, and keep the default locale for text a person reads.

== not localized: hex, NaN, Infinity ==
ff NaN Infinity

Going deeper

• LocaleDemo.java — the six locales and the default-locale switch
• Locale Javadoc — categories (FORMAT vs DISPLAY)

Indian lakh and crore grouping: what Java cannot do for you

System.out.println("== what the JDK gives for 123456789 ==");
System.out.println("String.format(en_IN, \"%,d\")      : " + String.format(enIN, "%,d", amount));
System.out.println("String.format(hi_IN, \"%,d\")      : " + String.format(hiIN, "%,d", amount));
System.out.println("NumberFormat.getInstance(en_IN)   : " + NumberFormat.getInstance(enIN).format(amount));
System.out.println("NumberFormat currency (en_IN)     : " + NumberFormat.getCurrencyInstance(enIN).format(amount + 0.5));
System.out.println("CLDR pattern for en_IN            : " + ((DecimalFormat) NumberFormat.getInstance(enIN)).toPattern());

== what the JDK gives for 123456789 ==
String.format(en_IN, "%,d")      : 123,456,789
String.format(hi_IN, "%,d")      : 123,456,789
NumberFormat.getInstance(en_IN)   : 123,456,789
NumberFormat currency (en_IN)     : ₹123,456,789.50
CLDR pattern for en_IN            : #,##0.###

DecimalFormat df = new DecimalFormat("#,##,##0");
System.out.println("pattern #,##,##0 -> grouping size : " + df.getGroupingSize());
System.out.println("pattern #,##,##0 -> output        : " + df.format(amount));

== a DecimalFormat pattern that LOOKS like it should work ==
pattern #,##,##0 -> grouping size : 3
pattern #,##,##0 -> output        : 123,456,789

The pattern #,##,##0 lies to you. It reports a grouping size of 3, so DecimalFormat keeps only the last group length of the pattern — the DecimalFormat Javadoc says only the interval after the final separator counts. Because the , flag in Formatter reads that same single number (the Javadoc says it uses the locale’s grouping size from DecimalFormat.getGroupingSize()), no locale and no flag can make %,d produce lakh/crore grouping.

== compact formatting knows crore but drops the digits ==
compact (default rounding)        : 12Cr
compact (2 fraction digits)       : 12.35Cr

public final class IndianNumberFormat {

    private IndianNumberFormat() {}

    /** Groups a whole number: 12345678 -> "1,23,45,678". */
    public static String format(long value) {
        String digits = Long.toString(value);
        boolean negative = digits.startsWith("-");
        if (negative) {
            digits = digits.substring(1);
        }
        return (negative ? "-" : "") + group(digits);
    }

    /** Groups the integer part of a decimal and rounds the fraction HALF_UP: 1234567.891, 2 -> "12,34,567.89". */
    public static String format(BigDecimal value, int fractionDigits) {
        BigDecimal rounded = value.setScale(fractionDigits, RoundingMode.HALF_UP);
        String plain = rounded.abs().toPlainString();
        int dot = plain.indexOf('.');
        String integerPart = dot < 0 ? plain : plain.substring(0, dot);
        String fraction = dot < 0 ? "" : plain.substring(dot);
        String sign = rounded.signum() < 0 ? "-" : "";
        return sign + group(integerPart) + fraction;
    }

    /** Convenience for doubles - goes through BigDecimal.valueOf so it rounds the way %f does. */
    public static String format(double value, int fractionDigits) {
        return format(BigDecimal.valueOf(value), fractionDigits);
    }

    private static String group(String digits) {
        int n = digits.length();
        if (n <= 3) {
            return digits;
        }
        String head = digits.substring(0, n - 3);
        String tail = digits.substring(n - 3);
        StringBuilder sb = new StringBuilder();
        int first = head.length() % 2;           // leading group of 1 or 2 digits
        if (first == 1) {
            sb.append(head.charAt(0));
        }
        for (int i = first; i < head.length(); i += 2) {
            if (sb.length() > 0) {
                sb.append(',');
            }
            sb.append(head, i, i + 2);
        }
        return sb.append(',').append(tail).toString();
    }
}

== IndianNumberFormat ==
              0  ->  0
            999  ->  999
          1,000  ->  1,000
         12,345  ->  12,345
        123,456  ->  1,23,456
      1,234,567  ->  12,34,567
    123,456,789  ->  12,34,56,789
   -123,456,789  ->  -12,34,56,789
12,34,567.89
-1,00,000.00
Rs. 12,34,567.50

Use BigDecimal for amounts. format(BigDecimal, int) rounds HALF_UP before grouping, and -99999.995 becomes -1,00,000.00, so the group boundary moves correctly when rounding carries a digit. The double overload goes through BigDecimal.valueOf, which matches the decimal-string behaviour of %f from the previous section.

System.out.println("== plugging it into a format string through %s ==");
System.out.println(String.format("%-12s %20s", "Balance", IndianNumberFormat.format(new BigDecimal("98765432.10"), 2)));

== plugging it into a format string through %s ==
Balance            9,87,65,432.10

Going deeper

• IndianGroupingDemo.java — every route tried, in order
• DecimalFormat Javadoc — the pattern syntax and grouping behaviour
• StringFormatTest.java — javaCannotGroupInLakhsAndCrores pins the failing routes

format, formatted, printf and Formatter: one engine, four doors

String a = String.format("Hi %s, %d items, Rs %.2f", name, items, total);
String b = "Hi %s, %d items, Rs %.2f".formatted(name, items, total);
StringBuilder sb = new StringBuilder();
new Formatter(sb).format("Hi %s, %d items, Rs %.2f", name, items, total);
System.out.println(a);
System.out.println(b);
System.out.println(sb);
System.out.printf("Hi %s, %d items, Rs %.2f%n", name, items, total);
System.out.println("format == formatted == Formatter: " + (a.equals(b) && b.equals(sb.toString())));

== four spellings, one result ==
Hi Asha, 3 items, Rs 1499.50
Hi Asha, 3 items, Rs 1499.50
Hi Asha, 3 items, Rs 1499.50
Hi Asha, 3 items, Rs 1499.50
format == formatted == Formatter: true

String invoice = """
        Invoice for %s
          items : %5d
          total : %,10.2f
        """.formatted(name, items, total);

== formatted() on a text block ==
Invoice for Asha
  items :     3
  total :   1,499.50

%n is the platform’s line separator, not always \n. On this machine they are the same (the transcript prints true for String.format("a%nb").equals("a\nb")), but the Javadoc says %n gives the platform-specific separator, so on a platform with a different separator (Windows typically uses two characters) the output differs. Use %n when writing text for people on the local platform and \n when a protocol needs exactly one.

Object[] row = {"x", 1};
String[] strings = {"p", "q"};
System.out.println(String.format("%s-%s", row));
System.out.println(String.format("%s-%s", strings));
System.out.println(String.format("%s", (Object) strings).startsWith("[Ljava.lang.String;@"));

== an array argument: spread as the varargs, unless you cast it to Object ==
x-1
p-q
true

Dates and times

System.out.println("== %t suffixes on a LocalDateTime ==");
System.out.println(String.format(Locale.US, "%tF | %tT | %tR | %tD", when, when, when, when));
System.out.println(String.format(Locale.US, "%tA, %<te %<tB %<tY", when));
System.out.println(String.format(Locale.US, "%tI:%<tM %<Tp", when));

== %t suffixes on a LocalDateTime ==
2026-11-12 | 09:05:07 | 09:05 | 11/12/26
Thursday, 12 November 2026
09:05 AM

Going deeper

• FormattedAndPrintfDemo.java — all four spellings plus the text-block example
• DateTimeDemo.java — the %t suffixes and the LocalDate trap
• DateTimeFormatter Javadoc

What it costs compared with +

String s = switch (v) {
    case PLUS -> "user=" + i + " score=" + (i * 0.5);
    case BUILDER -> new StringBuilder().append("user=").append(i).append(" score=").append(i * 0.5).toString();
    case FORMATTED -> "user=%d score=%.1f".formatted(i, i * 0.5);
    case FORMAT -> String.format("user=%d score=%.1f", i, i * 0.5);
};

JDK 25.0.5, 2000000 iterations per variant, best of 5 rounds
PLUS           52.6 ns/op
BUILDER        66.3 ns/op
FORMATTED     292.1 ns/op
FORMAT        279.5 ns/op

Should you use String.format at all? Yes, wherever you need padding, rounding or locale-aware numbers; it is the most convenient built-in for all three in one call, and the time per call here is in the hundreds of nanoseconds. Skip it for a plain join of a few values in a loop that runs millions of times, where + or a StringBuilder is clearer and several times cheaper. And skip it for lakh/crore grouping — as the previous section showed, it cannot produce it.

Going deeper

• ConcatBenchmarkDemo.java — the four variants and the warm-up
• Kabutz: String.format() 3x faster in Java 17

Further reading

• Companion code: java-core-examples/string-format — eleven transcripts in output/, eleven tests, one script to regenerate them
• On this blog: JMH Tutorial: Writing Java Microbenchmarks That Don’t Lie; Top 50 Java Interview Questions for Freshers
• java.util.Formatter (JDK 25 Javadoc) — the reference for every conversion and flag
• java.lang.String (JDK 25 Javadoc) — format and formatted
• java.text.DecimalFormat (JDK 25 Javadoc)