{"title":"String Formatting","description":"","content":"Building a clean line of output with raw `+` concatenation gets ugly the moment you need decimals, alignment, or padding. Java's formatting tools, `String.format`, `printf`, and `String.formatted`, let you write a single template string with placeholders and hand the values in separately. This lesson covers all three, every common format specifier, width and precision, flags, argument indexes, locale, and the pitfalls that turn into runtime exceptions.\n\n---\n\n# Why Formatting Exists\n\nConsider printing a one-line receipt summary. The price needs two decimals, the order ID needs zero-padding to five digits, and the customer name should sit in a fixed-width column so the totals line up. With plain concatenation, the code drifts into a mess.\n\n\n```java\npublic class ReceiptUgly {\n public static void main(String[] args) {\n int orderId = 42;\n String customerName = \"Alice\";\n double total = 89.5;\n\n String paddedId = \"\" + orderId;\n while (paddedId.length() < 5) {\n paddedId = \"0\" + paddedId;\n }\n String paddedName = customerName;\n while (paddedName.length() < 10) {\n paddedName = paddedName + \" \";\n }\n String roundedTotal = \"\" + ((int) (total * 100)) / 100.0;\n if (!roundedTotal.contains(\".\") || roundedTotal.split(\"\\\\.\")[1].length() < 2) {\n roundedTotal = roundedTotal + \"0\";\n }\n\n System.out.println(\"Order #\" + paddedId + \" | \" + paddedName + \" | $\" + roundedTotal);\n }\n}\n```\n\n\nThe output is correct, but reading the code is painful. Three different problems (padding, alignment, decimal places) each got their own ad-hoc patch. Scale this to a receipt with ten columns and it becomes unmaintainable.\n\nThe fix is a format string. We write one template with placeholders that describe how each value should look, then pass the values in order.\n\n\n```java\npublic class ReceiptFormatted {\n public static void main(String[] args) {\n int orderId = 42;\n String customerName = \"Alice\";\n double total = 89.5;\n\n String line = String.format(\"Order #%05d | %-10s | $%.2f\", orderId, customerName, total);\n System.out.println(line);\n }\n}\n```\n\n\nOne line replaces twelve. The template reads like the output it produces: an order ID padded to five digits with zeros, a name left-aligned in a ten-character column, and a total with two decimal places. The rest of the lesson breaks down what each piece of that template means.\n\n---\n\n# `String.format`, `printf`, and `formatted`\n\nJava gives you three ways to apply a format string. They share the same syntax and the same set of placeholders. They differ in where the result goes.\n\n\n| Method | Signature | What it does |\n| ------ | --------- | ------------ |\n| `String.format` | `static String format(String fmt, Object... args)` | Returns the formatted text as a new `String`. |\n| `System.out.printf` | `PrintStream printf(String fmt, Object... args)` | Writes the formatted text directly to standard output. No newline is added. |\n| `String.formatted` | `String formatted(Object... args)` (Java 15+) | Instance method on the format string itself. Returns the formatted text as a new `String`. |\n\n\nHere are the same values rendered three ways.\n\n\n```java\npublic class ThreeWays {\n public static void main(String[] args) {\n String productName = \"Wireless Mouse\";\n double price = 24.5;\n\n // 1. String.format: build a string, then use it\n String line = String.format(\"%s costs $%.2f\", productName, price);\n System.out.println(line);\n\n // 2. printf: write directly to stdout\n System.out.printf(\"%s costs $%.2f%n\", productName, price);\n\n // 3. formatted (Java 15+): call on the template itself\n String line2 = \"%s costs $%.2f\".formatted(productName, price);\n System.out.println(line2);\n }\n}\n```\n\n\nA few details apply. `printf` doesn't append a newline. The `%n` at the end of its format string is what produces one. Without `%n`, the next print would land on the same line. `System.out.println(line)` does add a newline because that's what `println` always does. `formatted` is a compact form when the template is a literal, because the template and the call read in the same order as the output.\n\nEach call to `String.format` allocates a new `String`. Inside a tight loop that builds millions of strings, that allocation cost adds up. Use `printf` for direct output, or build with `StringBuilder` for repeated concatenation.\n\n`println` versus `printf` is a common source of confusion. `println` prints the value's `toString` and adds a newline. `printf` interprets its first argument as a format string and never adds a newline on its own. If you write `System.out.printf(\"Hello\")`, the cursor stays on the same line as `Hello`.\n\n---\n\n# The Anatomy of a Format Specifier\n\nEvery placeholder in a format string starts with `%` and ends with a single letter called the **conversion**. Between them, you can put flags, a width, a precision, and an argument index. Most placeholders only need the `%` and the conversion. The rest of the parts are optional and order-sensitive.\n\n\n```mermaid\nflowchart LR\n Pct[\"%\"]:::cyan --> Idx[\"argument index
(optional)
e.g. 1$\"]:::orange\n Idx --> Flag[\"flags
(optional)
- 0 + , (\"]:::teal\n Flag --> Wid[\"width
(optional)
e.g. 10\"]:::orange\n Wid --> Prec[\"precision
(optional)
e.g. .2\"]:::teal\n Prec --> Conv[\"conversion
(required)
s d f x b c e n\"]:::green\n\n classDef cyan fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n```\n\n\nThe order is fixed: percent sign, optional argument index, optional flags, optional width, optional precision, then the required conversion letter. Get the order wrong and the format string throws a `MissingFormatArgumentException` or just produces gibberish.\n\nHere are a few specifiers broken down piece by piece.\n\n\n| Specifier | Index | Flags | Width | Precision | Conversion | Meaning |\n| --------- | ----- | ----- | ----- | --------- | ---------- | ------- |\n| `%s` | none | none | none | none | `s` | A string, no padding |\n| `%10s` | none | none | `10` | none | `s` | A string in a 10-character right-aligned column |\n| `%-10s` | none | `-` | `10` | none | `s` | A string in a 10-character left-aligned column |\n| `%05d` | none | `0` | `5` | none | `d` | An integer padded with zeros to width 5 |\n| `%,.2f` | none | `,` | none | `.2` | `f` | A float with two decimal places and thousands separators |\n| `%1$s` | `1$` | none | none | none | `s` | The first argument, as a string |\n\n\nRecognize the shape so that `%-12.3f` reads left to right as: left-align, width 12, precision 3, floating-point conversion.\n\n---\n\n# The Common Conversions\n\nThe conversion letter at the end is the heart of the specifier. It tells Java what kind of value to expect and how to render it. Use the wrong letter for the value and Java throws `IllegalFormatConversionException`. The common ones:\n\n\n| Conversion | Accepts | Example input | Example output |\n| ---------- | ------- | ------------- | -------------- |\n| `%s` | Any value (calls `toString`) | `\"Wireless Mouse\"` | `Wireless Mouse` |\n| `%d` | Integer types: `byte`, `short`, `int`, `long`, `BigInteger` | `42` | `42` |\n| `%f` | Floating-point: `float`, `double`, `BigDecimal` | `19.5` | `19.500000` |\n| `%e` | Floating-point in scientific notation | `19500.0` | `1.950000e+04` |\n| `%x` | Integer in lowercase hexadecimal | `255` | `ff` |\n| `%X` | Integer in uppercase hexadecimal | `255` | `FF` |\n| `%o` | Integer in octal | `8` | `10` |\n| `%b` | Any value, prints `true` if non-null and non-false, else `false` | `null` | `false` |\n| `%c` | Character: `char`, or integer code point | `'A'` | `A` |\n| `%n` | Nothing (no argument) | n/a | platform newline |\n| `%%` | Nothing (no argument) | n/a | a literal `%` |\n\n\nA few notes on the surprises.\n\n`%s` is the most forgiving. It accepts any object, calls `toString` on it, and even handles `null` by printing the four-character string `null`. This is why `%s` is often the safest choice when you're not sure of the exact type.\n\n`%f` always defaults to six decimal places. If you want a different number, you must say so with a precision: `%.2f` for two decimal places, `%.0f` for zero.\n\n`%n` isn't a newline character. It's a directive that asks Java to insert the platform-appropriate line separator: `\\n` on Linux and macOS, `\\r\\n` on Windows. Prefer `%n` inside format strings over hard-coding `\\n`. It avoids subtle bugs when the same code runs on different operating systems.\n\n`%%` is the only way to put a literal percent sign in a format string. A single `%` always starts a specifier, so to print `15% off`, you write `15%% off`.\n\n\n```java\npublic class CommonConversions {\n public static void main(String[] args) {\n System.out.printf(\"Product: %s%n\", \"Wireless Mouse\");\n System.out.printf(\"Quantity: %d%n\", 3);\n System.out.printf(\"Price: %f%n\", 24.5);\n System.out.printf(\"Tax rate: %.2f%n\", 0.085);\n System.out.printf(\"In stock: %b%n\", true);\n System.out.printf(\"Grade: %c%n\", 'A');\n System.out.printf(\"Hex code: %x%n\", 255);\n System.out.printf(\"Discount: %d%% off%n\", 15);\n }\n}\n```\n\n\nThe `Price: 24.500000` line shows why you almost never want a bare `%f`. Six decimals on a currency value looks wrong. The fix is precision, which is the next topic.\n\n---\n\n# Width, Precision, and Flags\n\nWidth sets the minimum number of characters the value should occupy. If the value is shorter than the width, Java pads it. If the value is longer, the width is ignored and the full value prints. Width never truncates.\n\n\n```java\npublic class WidthExample {\n public static void main(String[] args) {\n System.out.printf(\"[%10s]%n\", \"Mouse\");\n System.out.printf(\"[%10s]%n\", \"Wireless Mouse\");\n System.out.printf(\"[%-10s]%n\", \"Mouse\");\n System.out.printf(\"[%5d]%n\", 42);\n System.out.printf(\"[%5d]%n\", 1234567);\n }\n}\n```\n\n\nBy default, strings and numbers are right-aligned, which is why `Mouse` sits at the far end of the bracket. The `-` flag flips that to left-align. When the value is wider than the column (`Wireless Mouse` in a width of 10), Java prints the whole thing rather than chopping it. Width is a minimum, not a hard limit.\n\nPrecision means different things for different conversions:\n\n- For `%f` and `%e`, precision is the number of digits **after** the decimal point.\n- For `%s`, precision is the maximum number of characters to print, and longer strings are truncated.\n- For `%d`, precision isn't allowed and causes an `IllegalFormatPrecisionException`.\n\n\n```java\npublic class PrecisionExample {\n public static void main(String[] args) {\n System.out.printf(\"[%.2f]%n\", 24.567);\n System.out.printf(\"[%.0f]%n\", 24.567);\n System.out.printf(\"[%10.2f]%n\", 24.567);\n System.out.printf(\"[%-10.2f]%n\", 24.567);\n System.out.printf(\"[%.5s]%n\", \"Wireless Mouse\");\n }\n}\n```\n\n\n`%.2f` rounds half-to-even (banker's rounding) internally, but most everyday values round the expected way. The value `24.567` becomes `24.57` because the third decimal is `7`, well above the halfway point. `%.5s` truncates `Wireless Mouse` to its first five characters. That's useful for fitting long product names into a fixed column, although adding an ellipsis manually is a common follow-up.\n\nFlags modify the padding and the sign. The four most useful ones for everyday code:\n\n\n| Flag | Meaning | Example | Output |\n| ---- | ------- | ------- | ------ |\n| `-` | Left-align within the width | `%-10s` with `\"Mouse\"` | `Mouse ` |\n| `0` | Pad with zeros instead of spaces (numbers only) | `%05d` with `42` | `00042` |\n| `,` | Group digits with locale-specific thousand separators | `%,d` with `1234567` | `1,234,567` |\n| `+` | Always show the sign on numbers | `%+d` with `5` | `+5` |\n| `(` | Wrap negative numbers in parentheses | `%(d` with `-5` | `(5)` |\n\n\nYou can combine flags. `%+,d` shows a thousand separator and a forced sign. `%-10.2f` left-aligns a two-decimal float in a ten-character column. The order of the flags relative to each other doesn't matter, but they must all sit between the `%` and the width.\n\n\n```java\npublic class FlagsExample {\n public static void main(String[] args) {\n int profit = 1234567;\n int loss = -1234567;\n\n System.out.printf(\"Profit: %,d%n\", profit);\n System.out.printf(\"Profit: %+,d%n\", profit);\n System.out.printf(\"Loss: %,d%n\", loss);\n System.out.printf(\"Loss: %(,d%n\", loss);\n System.out.printf(\"Order: %05d%n\", 42);\n }\n}\n```\n\n\nThe `(` flag is a small accounting convention. Negative numbers print as `(1,234,567)` instead of `-1,234,567`. It's still numeric, just rendered in a way that matches how financial reports usually display losses. The `0` flag is what fixes the order-ID padding problem we saw at the start of the lesson.\n\nPadding is cheap. Every format call does a length check and copies characters into a buffer. Precision on `%f` triggers a rounding step but is still O(1). None of this is something to worry about for ordinary code.\n\n---\n\n# Argument Index and Locale\n\nWhen you need to reuse the same argument in multiple positions, the argument index syntax `n$` lets you point at a specific value instead of consuming arguments in order. The first argument is `1$`, the second is `2$`, and so on. Note that the index is **one-based**, not zero-based.\n\n\n```java\npublic class ArgumentIndex {\n public static void main(String[] args) {\n String customerName = \"Alice\";\n\n // Without index: each %s consumes the next argument\n String greeting1 = String.format(\"Hi %s, welcome back %s!\", customerName, customerName);\n\n // With index: 1$s reuses the first argument\n String greeting2 = String.format(\"Hi %1$s, welcome back %1$s!\", customerName);\n\n System.out.println(greeting1);\n System.out.println(greeting2);\n }\n}\n```\n\n\nBoth produce the same result, but the second version only passes the name once. That matters when the same value appears three or four times in a long template, or when the values are expensive to compute. Argument indexes also let you reorder values, which is the main reason translators need them. A French translation might want the customer name in a different position than the English source, and `%2$s` lets the translator move it without touching the code.\n\nLocale is the part of formatting that often causes issues in production. The default `String.format` uses the JVM's default locale, which depends on the operating system, the user, and sometimes the environment variables. The same code produces different output in different places, which breaks tests and makes log files inconsistent across machines.\n\nThe two most common locale-sensitive behaviors:\n\n- The thousand separator changes. US locale uses a comma (`1,234.56`). German locale uses a period (`1.234,56`). French locale uses a non-breaking space (`1 234,56`).\n- The decimal point changes. US locale uses a period. Most of continental Europe uses a comma.\n\n\n```java\nimport java.util.Locale;\n\npublic class LocaleExample {\n public static void main(String[] args) {\n double price = 1234.56;\n\n System.out.println(String.format(Locale.US, \"Price: %,.2f\", price));\n System.out.println(String.format(Locale.GERMANY, \"Price: %,.2f\", price));\n System.out.println(String.format(Locale.FRANCE, \"Price: %,.2f\", price));\n System.out.println(String.format(\"Price: %,.2f\", price)); // default locale\n }\n}\n```\n\n\n**Output (on a US-locale JVM):**\n\n\n```shell\nPrice: 1,234.56\nPrice: 1.234,56\nPrice: 1 234,56\nPrice: 1,234.56\n```\n\n\nThe last line, with no explicit locale, happens to match the US line **only because the JVM running this example is set to US locale**. Run the same code on a JVM whose default is German, and the last line flips to `1.234,56`. This is the bug that breaks tests in CI.\n\nThe fix is to always pass an explicit `Locale` when the output is going to be parsed by another program, compared against a fixed expected value, or written to a file that other systems will read. Use `Locale.US` when you want a stable, machine-readable format. Use `Locale.ROOT` when you want a locale-neutral one (similar to US but considered the formal \"no locale\" choice).\n\n\n```java\nimport java.util.Locale;\n\npublic class StableFormat {\n public static void main(String[] args) {\n double price = 1234.56;\n\n // For logs, IDs, or anything machine-readable, fix the locale\n String stable = String.format(Locale.ROOT, \"PRICE=%.2f\", price);\n System.out.println(stable);\n\n // For user-facing output, use the user's locale\n String userFacing = String.format(Locale.US, \"Price: $%,.2f\", price);\n System.out.println(userFacing);\n }\n}\n```\n\n\n`printf` accepts a locale the same way: `System.out.printf(Locale.US, \"%,.2f%n\", price)`. The instance method `formatted` doesn't accept a locale and always uses the default, which is one reason to use `String.format` instead when locale matters.\n\n---\n\n# Text Blocks with Format Strings\n\nJava 15 added **text blocks**, multi-line string literals that use triple quotes. They pair naturally with `formatted` when you need a multi-line template with embedded values, like a receipt or an email body.\n\nThe syntax is a string opened and closed with `\"\"\"`. Java strips the common leading whitespace based on the position of the closing `\"\"\"`, so the indentation in your source doesn't end up in the string.\n\n\n```java\npublic class TextBlockReceipt {\n public static void main(String[] args) {\n String customerName = \"Alice\";\n int orderId = 42;\n double total = 89.5;\n\n String receipt = \"\"\"\n ORDER RECEIPT\n -------------\n Customer: %s\n Order #: %05d\n Total: $%.2f\n \"\"\".formatted(customerName, orderId, total);\n\n System.out.println(receipt);\n }\n}\n```\n\n\nThe text block reads top to bottom like the output. Newlines inside the block are real newlines in the string. The `.formatted(...)` call substitutes the three placeholders. You could also pass this same text block to `String.format` or `System.out.printf`, but `formatted` keeps the template and the substitution next to each other.\n\nText blocks aren't a separate formatting feature. They're just a friendlier way to write a multi-line format string. Every specifier you've seen so far works inside one without any change.\n\n---\n\n# Pitfalls and Common Exceptions\n\nFormat strings push more checks to runtime than to compile time. The compiler can't tell whether `%d` matches the type of the third argument, so you only find out when the code runs. The exceptions are specific enough that the message usually tells you exactly what went wrong, but knowing the failure modes in advance saves a lot of time.\n\n**Wrong conversion for the value.**\n\n\n```java\npublic class WrongConversion {\n public static void main(String[] args) {\n double price = 19.99;\n System.out.printf(\"Price: %d%n\", price); // %d expects int, got double\n }\n}\n```\n\n\nThe message says `d != java.lang.Double`. The conversion `%d` expects an integer type, and the argument is a `Double`. The fix is to match the conversion to the value: `%f` for a `double`, `%d` for an integer, or convert the value first with `(int) price`.\n\n**Too few arguments.**\n\n\n```java\npublic class TooFewArgs {\n public static void main(String[] args) {\n System.out.printf(\"%s costs $%.2f%n\", \"Mouse\"); // missing the price\n }\n}\n```\n\n\nThe format string has two specifiers (`%s` and `%.2f`) but only one argument was passed. The message names the specifier that was left without a value. Count your specifiers and your arguments, especially after editing a long format string.\n\n**Argument order mixed up.**\n\n\n```java\npublic class WrongOrder {\n public static void main(String[] args) {\n double price = 19.99;\n int quantity = 3;\n System.out.printf(\"Bought %d items at $%.2f each%n\", price, quantity);\n }\n}\n```\n\n\nThis is the same exception as the wrong-conversion case, because that's what the swap looks like to Java. The first specifier `%d` got a `Double` instead of an `Integer`. The fix is to pass the arguments in the order the format string expects, or to use argument indexes (`%2$d items at $%1$.2f each`) to point at each one explicitly.\n\n**Forgetting `%%` for a literal percent.**\n\n\n```java\npublic class LiteralPercent {\n public static void main(String[] args) {\n System.out.printf(\"Discount: 15%%n\"); // probably meant 15% off, with a newline\n }\n}\n```\n\n\nThere's no exception here, just wrong output. `%%` produces a single `%`, and then `n` is just the letter `n`, not a format directive. The fix is `15%% off%n` if you want `Discount: 15% off` followed by a newline. To be precise, `%%` consumes the two-character sequence as a single literal percent.\n\n**Locale-dependent decimal point breaking tests.**\n\nWe covered this in the locale section, but it's the bug that hides longest. Tests pass locally and fail in CI, or vice versa. Always pass an explicit `Locale` for any output that will be parsed, compared, or written to a file.\n\n**What's wrong with this code?**\n\n\n```java\npublic class CartSummaryBug {\n public static void main(String[] args) {\n int itemCount = 3;\n double total = 89.5;\n System.out.printf(\"Cart has %s items, total $%.2d%n\", itemCount, total);\n }\n}\n```\n\n\nThere are two problems. First, `%s` for an `int` happens to work because `%s` accepts anything, but it bypasses the integer check that `%d` would do, hiding type bugs. Second, `%.2d` is illegal because precision isn't allowed on `%d`. The code throws `IllegalFormatPrecisionException: 2` before it ever produces output.\n\n**Fix:**\n\n\n```java\npublic class CartSummaryFixed {\n public static void main(String[] args) {\n int itemCount = 3;\n double total = 89.5;\n System.out.printf(\"Cart has %d items, total $%.2f%n\", itemCount, total);\n }\n}\n```\n\n\nMatch each specifier to the value's type: `%d` for the integer count, `%.2f` for the dollar total. Use `%s` when you actually want the `toString` of an arbitrary object, not as a \"works for everything\" shortcut.","pageType":"java"}

String Formatting

Get Premium