Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท java.lang

Java String.format() method

Reference for Java String.format(): build formatted text with %s, %d and %.2f, control width, padding and locale, and avoid common format exceptions.

String.format() builds a string from a template and a list of arguments. The template contains plain text and format specifiers such as %s (any value as text), %d (an integer) and %.2f (a decimal with two digits). It is the same engine that powers System.out.printf() and String.formatted(); the difference is that you get the result as a string instead of printing it.

Use it whenever you need aligned columns, fixed decimals, zero padding or hex output. For simple joins, plain concatenation is shorter.

Java
String line = String.format("%-6s|%5d|%8.2f", "tea", 3, 4.5);
// "tea   |    3|    4.50"

Try it

Java Common specifiers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Argument indexes and errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public static String format(String format, Object... args)
public static String format(Locale l, String format, Object... args)

A specifier has the form %[argument_index$][flags][width][.precision]conversion.

Name Description
format The template with text and specifiers.
args Values for the specifiers, in order (unless an index is given). Extra arguments are ignored.
l The Locale used for digits, separators and decimal marks. The one-argument form uses Locale.getDefault(Locale.Category.FORMAT).

Returns: the formatted String.

Throws: NullPointerException if format is null; a subclass of IllegalFormatException for a bad template, for example MissingFormatArgumentException, UnknownFormatConversionException or IllegalFormatConversionException.

Conversion Meaning
%s / %S Text via toString() (upper-cased with S).
%d Integer (byte, short, int, long, BigInteger).
%f / %e Decimal / scientific notation (float, double, BigDecimal). Default precision is 6.
%x / %o Hexadecimal / octal integer.
%c / %b A character / a boolean (false only for null or false).
%n / %% Platform line separator / a literal percent sign.

Useful flags: - left-justify, 0 zero-pad, , grouping separators, + always show the sign, ( negative numbers in parentheses, # alternate form (such as 0x).

Usage notes

  • The default locale matters. %,d and %f use the JVM's locale, so the same code can print 1,234.50 on one machine and 1.234,50 on another. Pass Locale.ROOT or Locale.US for machine-readable output.
  • Types must fit the conversion. %d with a double or a String throws IllegalFormatConversionException; %f with an int does too. Cast or convert first.
  • %s never fails. It works with any object and prints null for null, which makes it a safe default.
  • Rounding is half-up. %.2f of 2.675 gives 2.68 because the formatter works from the decimal expansion of the value, not the binary one; use BigDecimal for money.
  • Use %n, not \n, when you want the platform line separator; \n is fine for fixed newlines.
  • Not cheap in hot loops. Each call parses the template. For repeated use, build a Formatter once or use concatenation.
  • Escape a literal % as %%. A stray % is an UnknownFormatConversionException.