Formats number according to given rules in format string. Documentation taken from java.text.DecimalFormat.

Structure of the pattern:

 pattern    := subpattern{;subpattern}
 subpattern := {prefix}integer{.fraction}{suffix}

 prefix     := 'u0000'..'uFFFD' - specialCharacters
 suffix     := 'u0000'..'uFFFD' - specialCharacters
 integer    := '#'* '0'* '0'
 fraction   := '0'* '#'*

 Notation:
  X*       0 or more instances of X
  (X | Y)  either X or Y.
  X..Y     any character from X up to Y, inclusive.
  S - T    characters in S, except those in T
 

The first subpattern is for positive numbers. The second (optional) subpattern is for negative numbers. (In both cases, ',' can occur inside the integer portion--it is just too messy to indicate in BNF.)

Here are the special characters used in the parts of the subpattern, with notes on their usage.

 Symbol Meaning
 0      a digit
 #      a digit, zero shows as absent
 .      placeholder for decimal separator
 ,      placeholder for grouping separator.
 E      separates mantissa and exponent for exponential formats.
 ;      separates formats.
 -      default negative prefix.
 %      multiply by 100 and show as percentage
 ? multiply by 1000 and show as per mille
 ¤ currency sign; replaced by currency symbol; if
        doubled, replaced by international currency symbol.
        If present in a pattern, the monetary decimal separator
        is used instead of the decimal separator.
 X      any other characters can be used in the prefix or suffix
 '      used to quote special characters in a prefix or suffix.
 

Notes

If there is no explicit negative subpattern, - is prefixed to the positive form. That is, "0.00" alone is equivalent to "0.00;-0.00". If there is an explicit negative subpattern, it serves only to specify the negative prefix and suffix; the number of digits, minimal digits, and other characteristics are all the same as the positive pattern. That means that "#,##0.0#;(#)" has precisely the same result as "#,##0.0#;(#,##0.0#)".

If the maximum number of fraction digits is lower than the actual number of fraction digits, then format() will round the result to the maximum number of fraction digits. The rounding is performed according to the IEEE 754 default rounding mode known as half even: Numbers are rounded toward the nearest truncated value, unless both truncated values are equidistant, in which case the value ending in an even digit is chosen.

For example, formatting the number 1.2499 with a maximum of two fraction digits gives two possible values, 1.24 and 1.25. The distance to 1.24 is 0.0099 and the distance to 1.25 is 0.0001, so 1.25 is chosen. On the other hand, when rounding 1.245 to two fraction digits, the two possible values are again 1.24 and 1.25, but the distance to each is the same: 0.005. In this case 1.24 is chosen because it ends in an even digit.

The exponent character must be immediately followed by one or more digit characters. Example: "0.###E0". The number of digit characters after the exponent character gives the minimum exponent digit count; there is no maximum. Negative exponents are denoted using the same prefix and/or suffix specified for the number itself. The minimum number of integer digits is achieved by adjusting the exponent. The maximum number of integer digits, if any, specifies the exponent grouping. For example, 12345 is formatted using "##0.###E0" as "12.345E3".

Illegal patterns, such as "#.#.#" or mixing '_' and '*' in the same pattern, will cause an IllegalArgumentException to be thrown. From the message of IllegalArgumentException, you can find the place in the string where the error occurred.

The grouping separator is commonly used for thousands, but in some countries for ten-thousands. The interval is a constant number of digits between the grouping characters, such as 100,000,000 or 1,0000,0000. If you supply a pattern with multiple grouping characters, the interval between the last one and the end of the integer is the one that is used. So "#,##,###,####" == "######,####" == "##,####,####".

When parsing fails, null is returned.