NOTE: Currently all formatters MUST have a default constructor.
Convenience methods for common formatting requests exist as illustrated by the following invocations:
// Writes a formatted string to System.out. System.out.format("Local time: %tT", Calendar.getInstance()); // > "Local time: 13:34:18" // Writes formatted output to System.err. System.err.printf("Unable to open file '%1$s': %2$s", fileName, exception.getMessage()); // > "Unable to open file 'food': No such file or directory"
Like C's sprintf(3), Strings may be formatted using the static method {@link String#format(String,Object) String.format}:
// Format a string containing a date. import java.util.Calendar; import java.util.GregorianCalendar; import static java.util.Calendar.*; Calendar c = new GregorianCalendar(1995, MAY, 23); String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); // > s == "Duke's Birthday: May 23, 1995"
This specification is divided into two sections. The first section, Summary, covers the basic formatting concepts. This section is intended for users who want to get started quickly and are familiar with formatted printing in other programming languages. The second section, Details, covers the specific implementation details. It is intended for users who want more precise specification of formatting behavior.
This section is intended to provide a brief overview of formatting concepts. For precise behavioral details, refer to the Details section.
Every method which produces formatted output requires a format string and an argument list. The format string is a {@link String} which may contain fixed text and one or more embedded formatspecifiers. Consider the following example:
This format string is the first argument to the format method. It contains three format specifiers "%1$tm", "%1$te", and "%1$tY" which indicate how the arguments should be processed and where they should be inserted in the text. The remaining portions of the format string are fixed text including "Dukes Birthday: " and any other spaces or punctuation. The argument list consists of all arguments passed to the method after the format string. In the above example, the argument list is of size one and consists of the {@link java.util.Calendar Calendar} object c.Calendar c = ...; String s = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c);
%[argument_index$][flags][width][.precision]conversion
The optional argument_index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc.
The optional flags is a set of characters that modify the output format. The set of valid flags depends on the conversion.
The optional width is a nonnegative decimal integer indicating the minimum number of characters to be written to the output.
The optional precision is a nonnegative decimal integer usually used to restrict the number of characters. The specific behavior depends on the conversion.
The required conversion is a character indicating how the argument should be formatted. The set of valid conversions for a given argument depends on the argument's data type.
%[argument_index$][flags][width]conversion
The optional argument_index, flags and width are defined as above.
The required conversion is a two character sequence. The first character is 't' or 'T'. The second character indicates the format to be used. These characters are similar to but not completely identical to those defined by GNU date and POSIX strftime(3c).
%[flags][width]conversion
The optional flags and width is defined as above.
The required conversion is a character indicating content to be inserted in the output.
Conversions are divided into the following categories:
The following table summarizes the supported conversions. Conversions denoted by an uppercase character (i.e. 'B', 'H', 'S', 'C', 'X', 'E', 'G', 'A', and 'T') are the same as those for the corresponding lowercase conversion characters except that the result is converted to upper case according to the rules of the prevailing {@link java.util.Locale Locale}. The result is equivalent to the following invocation of {@link String#toUpperCase()}
out.toUpperCase()
Conversion  Argument Category  Description 

'b', 'B'  general  If the argument arg is null, then the result is "false". If arg is a boolean or {@link Boolean}, then the result is the string returned by {@link String#valueOf(boolean) String.valueOf()}. Otherwise, the result is "true". 
'h', 'H'  general  If the argument arg is null, then the result is "null". Otherwise, the result is obtained by invoking Integer.toHexString(arg.hashCode()). 
's', 'S'  general  If the argument arg is null, then the result is "null". If arg implements {@link Formattable}, then {@link Formattable#formatTo arg.formatTo} is invoked. Otherwise, theresult is obtained by invoking arg.toString(). 
'c', 'C'  character  The result is a Unicode character 
'd'  integral  The result is formatted as a decimal integer 
'o'  integral  The result is formatted as an octal integer 
'x', 'X'  integral  The result is formatted as a hexadecimal integer 
'e', 'E'  floating point  The result is formatted as a decimal number in computerized scientific notation 
'f'  floating point  The result is formatted as a decimal number 
'g', 'G'  floating point  The result is formatted using computerized scientific notation or decimal format, depending on the precision and the value after rounding. 
'a', 'A'  floating point  The result is formatted as a hexadecimal floatingpoint number with a significand and an exponent 
't', 'T'  date/time  Prefix for date and time conversion characters. See Date/Time Conversions. 
'%'  percent  The result is a literal '%' ('\u0025') 
'n'  line separator  The result is the platformspecific line separator 
Any characters not explicitly defined as conversions are illegal and are reserved for future extensions.
The following date and time conversion suffix characters are defined for the 't' and 'T' conversions. The types are similar to but not completely identical to those defined by GNU date and POSIX strftime(3c). Additional conversion types are provided to access Javaspecific functionality (e.g. 'L' for milliseconds within the second).
The following conversion characters are used for formatting times:
'H'  Hour of the day for the 24hour clock, formatted as two digits with a leading zero as necessary i.e. 00  23. 
'I'  Hour for the 12hour clock, formatted as two digits with a leading zero as necessary, i.e. 01  12. 
'k'  Hour of the day for the 24hour clock, i.e. 0  23. 
'l'  Hour for the 12hour clock, i.e. 1  12. 
'M'  Minute within the hour formatted as two digits with a leading zero as necessary, i.e. 00  59. 
'S'  Seconds within the minute, formatted as two digits with a leading zero as necessary, i.e. 00  60 ("60" is a special value required to support leap seconds). 
'L'  Millisecond within the second formatted as three digits with leading zeros as necessary, i.e. 000  999. 
'N'  Nanosecond within the second, formatted as nine digits with leading zeros as necessary, i.e. 000000000  999999999. 
'p'  Localespecific {@linkplain java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} markerin lower case, e.g."am" or "pm". Use of the conversion prefix 'T' forces this output to upper case. 
'z'  RFC 822 style numeric time zone offset from GMT, e.g. 0800. 
'Z'  A string representing the abbreviation for the time zone. The Formatter's locale will supersede the locale of the argument (if any). 
's'  Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC, i.e. Long.MIN_VALUE/1000 to Long.MAX_VALUE/1000. 
'Q'  Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC, i.e. Long.MIN_VALUE to Long.MAX_VALUE. 
The following conversion characters are used for formatting dates:
'B'  Localespecific {@linkplain java.text.DateFormatSymbols#getMonths full month name}, e.g. "January", "February". 
'b'  Localespecific {@linkplain java.text.DateFormatSymbols#getShortMonths abbreviated month name}, e.g. "Jan", "Feb". 
'h'  Same as 'b'. 
'A'  Localespecific full name of the {@linkplain java.text.DateFormatSymbols#getWeekdays day of the week}, e.g. "Sunday", "Monday" 
'a'  Localespecific short name of the {@linkplain java.text.DateFormatSymbols#getShortWeekdays day of the week}, e.g. "Sun", "Mon" 
'C'  Fourdigit year divided by 100, formatted as two digits with leading zero as necessary, i.e. 00  99 
'Y'  Year, formatted as at least four digits with leading zeros as necessary, e.g. 0092 equals 92 CE for the Gregorian calendar. 
'y'  Last two digits of the year, formatted with leading zeros as necessary, i.e. 00  99. 
'j'  Day of year, formatted as three digits with leading zeros as necessary, e.g. 001  366 for the Gregorian calendar. 
'm'  Month, formatted as two digits with leading zeros as necessary, i.e. 01  13. 
'd'  Day of month, formatted as two digits with leading zeros as necessary, i.e. 01  31 
'e'  Day of month, formatted as two digits, i.e. 1  31. 
The following conversion characters are used for formatting common date/time compositions.
'R'  Time formatted for the 24hour clock as "%tH:%tM" 
'T'  Time formatted for the 24hour clock as "%tH:%tM:%tS". 
'r'  Time formatted for the 12hour clock as "%tI:%tM:%tS %Tp". The location of the morning or afternoon marker ('%Tp') may be localedependent. 
'D'  Date formatted as "%tm/%td/%ty". 
'F'  ISO 8601 complete date formatted as "%tY%tm%td". 
'c'  Date and time formatted as "%ta %tb %td %tT %tZ %tY", e.g. "Sun Jul 20 16:17:00 EDT 1969". 
Any characters not explicitly defined as date/time conversion suffixes are illegal and are reserved for future extensions.
The following table summarizes the supported flags. y means the flag is supported for the indicated argument types.
Flag  General  Character  Integral  Floating Point  Date/Time  Description 

''  y  y  y  y  y  The result will be leftjustified. 
'#'  y^{1}    y^{3}  y    The result should use a conversiondependent alternate form 
'+'      y^{4}  y    The result will always include a sign 
' '      y^{4}  y    The result will include a leading space for positive values 
'0'      y  y    The result will be zeropadded 
','      y^{2}  y^{5}    The result will include localespecific {@linkplain java.text.DecimalFormatSymbols#getGroupingSeparator grouping separators} 
'('      y^{4}  y^{5}    The result will enclose negative numbers in parentheses 
^{1} Depends on the definition of {@link Formattable}.
^{2} For 'd' conversion only.
^{3} For 'o', 'x', and 'X' conversions only.
^{4} For 'd', 'o', 'x', and 'X' conversions applied to {@link java.math.BigInteger BigInteger}or 'd' applied to byte, {@link Byte}, short, {@link Short}, int and {@link Integer}, long, and {@link Long}.
^{5} For 'e', 'E', 'f', 'g', and 'G' conversions only.
Any characters not explicitly defined as flags are illegal and are reserved for future extensions.
The width is the minimum number of characters to be written to the output. For the line separator conversion, width is not applicable; if it is provided, an exception will be thrown.
For general argument types, the precision is the maximum number of characters to be written to the output.
For the floatingpoint conversions 'e', 'E', and 'f' the precision is the number of digits after the decimal separator. If the conversion is 'g' or 'G', then the precision is the total number of digits in the resulting magnitude after rounding. If the conversion is 'a' or 'A', then the precision must not be specified.
For character, integral, and date/time argument types and the percent and line separator conversions, the precision is not applicable; if a precision is provided, an exception will be thrown.
The argument index is a decimal integer indicating the position of the argument in the argument list. The first argument is referenced by "1$", the second by "2$", etc.
Another way to reference arguments by position is to use the '<' ('\u003c') flag, which causes the argument for the previous format specifier to be reused. For example, the following two statements would produce identical strings:
Calendar c = ...; String s1 = String.format("Duke's Birthday: %1$tm %1$te,%1$tY", c); String s2 = String.format("Duke's Birthday: %1$tm %<te,%<tY", c);
This section is intended to provide behavioral details for formatting, including conditions and exceptions, supported data types, localization, and interactions between flags, conversions, and data types. For an overview of formatting concepts, refer to the Summary
Any characters not explicitly defined as conversions, date/time conversion suffixes, or flags are illegal and are reserved for future extensions. Use of such a character in a format string will cause an {@link UnknownFormatConversionException} or {@link UnknownFormatFlagsException} to be thrown.
If the format specifier contains a width or precision with an invalid value or which is otherwise unsupported, then a {@link IllegalFormatWidthException} or {@link IllegalFormatPrecisionException}respectively will be thrown.
If a format specifier contains a conversion character that is not applicable to the corresponding argument, then an {@link IllegalFormatConversionException} will be thrown.
All specified exceptions may be thrown by any of the format methods of Formatter as well as by any format convenience methods such as {@link String#format(String,Object) String.format} and{@link java.io.PrintStream#printf(String,Object) PrintStream.printf}.
Conversions denoted by an uppercase character (i.e. 'B', 'H', 'S', 'C', 'X', 'E', 'G', 'A', and 'T') are the same as those for the corresponding lowercase conversion characters except that the result is converted to upper case according to the rules of the prevailing {@link java.util.Locale Locale}. The result is equivalent to the following invocation of {@link String#toUpperCase()}
out.toUpperCase()
The following general conversions may be applied to any argument type:
'b'  '\u0062'  Produces either "true" or "false" as returned by {@link Boolean#toString(boolean)}. If the argument is null, then the result is "false". If the argument is a boolean or {@link Boolean}, then the result is the string returned by {@link String#valueOf(boolean) String.valueOf()}. Otherwise, the result is "true". If the '#' flag is given, then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'B'  '\u0042'  The uppercase variant of 'b'. 
'h'  '\u0068'  Produces a string representing the hash code value of the object. If the argument, arg is null, then the result is "null". Otherwise, the result is obtained by invoking Integer.toHexString(arg.hashCode()). If the '#' flag is given, then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'H'  '\u0048'  The uppercase variant of 'h'. 
's'  '\u0073'  Produces a string. If the argument is null, then the result is "null". If the argument implements {@link Formattable}, then its {@link Formattable#formatTo formatTo} method is invoked.Otherwise, the result is obtained by invoking the argument's toString() method. If the '#' flag is given and the argument is not a {@link Formattable} , then a {@link FormatFlagsConversionMismatchException}will be thrown. 
'S'  '\u0053'  The uppercase variant of 's'. 
The following flags apply to general conversions:
''  '\u002d'  Left justifies the output. Spaces ('\u0020') will be added at the end of the converted value as required to fill the minimum width of the field. If the width is not provided, then a {@link MissingFormatWidthException} will be thrown. If this flag is not giventhen the output will be rightjustified. 
'#'  '\u0023'  Requires the output use an alternate form. The definition of the form is specified by the conversion. 
The width is the minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by ' ' (\u0020') until the total number of characters equals the width. The padding is on the left by default. If the '' flag is given, then the padding will be on the right. If the width is not specified then there is no minimum.
The precision is the maximum number of characters to be written to the output. The precision is applied before the width, thus the output will be truncated to precision characters even if the width is greater than the precision. If the precision is not specified then there is no explicit limit on the number of characters.
'c'  '\u0063'  Formats the argument as a Unicode character as described in Unicode Character Representation. This may be more than one 16bit char in the case where the argument represents a supplementary character. If the '#' flag is given, then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'C'  '\u0043'  The uppercase variant of 'c'. 
The '' flag defined for General conversions applies. If the '#' flag is given, then a {@link FormatFlagsConversionMismatchException} will be thrown.
The width is defined as for General conversions.
The precision is not applicable. If the precision is specified then an {@link IllegalFormatPrecisionException} will be thrown.
Numeric conversions are divided into the following categories:
Numeric types will be formatted according to the following algorithm:
After digits are obtained for the integer part, fractional part, and exponent (as appropriate for the data type), the following transformation is applied:
If the value is NaN or positive infinity the literal strings "NaN" or "Infinity" respectively, will be output. If the value is negative infinity, then the output will be "(Infinity)" if the '(' flag is given otherwise the output will be "Infinity". These values are not localized.
Byte, Short, Integer, and Long
The following conversions may be applied to byte, {@link Byte}, short, {@link Short}, int and {@link Integer}, long, and {@link Long}.
'd'  '\u0054'  Formats the argument as a decimal integer. The localization algorithm is applied. If the '0' flag is given and the value is negative, then the zero padding will occur after the sign. If the '#' flag is given then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'o'  '\u006f'  Formats the argument as an integer in base eight. No localization is applied. If x is negative then the result will be an unsigned value generated by adding 2^{n} to the value where n is the number of bits in the type as returned by the static SIZE field in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}classes as appropriate. If the '#' flag is given then the output will always begin with the radix indicator '0'. If the '0' flag is given then the output will be padded with leading zeros to the field width following any indication of sign. If '(', '+', ' ', or ',' flags are given then a {@link FormatFlagsConversionMismatchException} will bethrown. 
'x'  '\u0078'  Formats the argument as an integer in base sixteen. No localization is applied. If x is negative then the result will be an unsigned value generated by adding 2^{n} to the value where n is the number of bits in the type as returned by the static SIZE field in the {@linkplain Byte#SIZE Byte}, {@linkplain Short#SIZE Short}, {@linkplain Integer#SIZE Integer}, or {@linkplain Long#SIZE Long}classes as appropriate. If the '#' flag is given then the output will always begin with the radix indicator "0x". If the '0' flag is given then the output will be padded to the field width with leading zeros after the radix indicator or sign (if present). If '(', ' ', '+', or ',' flags are given then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'X'  '\u0058'  The uppercase variant of 'x'. The entire string representing the number will be converted to {@linkplain String#toUpperCase upper case} including the 'x' (if any) andall hexadecimal digits 'a'  'f' ('\u0061'  '\u0066'). 
If the conversion is 'o', 'x', or 'X' and both the '#' and the '0' flags are given, then result will contain the radix indicator ('0' for octal and "0x" or "0X" for hexadecimal), some number of zeros (based on the width), and the value.
If the '' flag is not given, then the space padding will occur before the sign.
The following flags apply to numeric integral conversions:
'+'  '\u002b'  Requires the output to include a positive sign for all positive numbers. If this flag is not given then only negative values will include a sign. If both the '+' and ' ' flags are given then an {@link IllegalFormatFlagsException} will be thrown. 
' '  '\u0020'  Requires the output to include a single extra space ('\u0020') for nonnegative values. If both the '+' and ' ' flags are given then an {@link IllegalFormatFlagsException} will be thrown. 
'0'  '\u0030'  Requires the output to be padded with leading {@linkplain java.text.DecimalFormatSymbols#getZeroDigit zeros} to the minimum fieldwidth following any sign or radix indicator except when converting NaN or infinity. If the width is not provided, then a {@link MissingFormatWidthException} will be thrown. If both the '' and '0' flags are given then an {@link IllegalFormatFlagsException} will be thrown. 
','  '\u002c'  Requires the output to include the localespecific {@linkplain java.text.DecimalFormatSymbols#getGroupingSeparator group separators} asdescribed in the "group" section of the localization algorithm. 
'('  '\u0028'  Requires the output to prepend a '(' ('\u0028') and append a ')' ('\u0029') to negative values. 
If no flags are given the default formatting is as follows:
The width is the minimum number of characters to be written to the output. This includes any signs, digits, grouping separators, radix indicator, and parentheses. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If '' flag is given then the padding will be on the right. If width is not specified then there is no minimum.
The precision is not applicable. If precision is specified then an {@link IllegalFormatPrecisionException} will be thrown.
The following conversions may be applied to {@link java.math.BigInteger}.
'd'  '\u0054'  Requires the output to be formatted as a decimal integer. The localization algorithm is applied. If the '#' flag is given {@link FormatFlagsConversionMismatchException} will be thrown. 
'o'  '\u006f'  Requires the output to be formatted as an integer in base eight. No localization is applied. If x is negative then the result will be a signed value beginning with '' ('\u002d'). Signed output is allowed for this type because unlike the primitive types it is not possible to create an unsigned equivalent without assuming an explicit datatype size. If x is positive or zero and the '+' flag is given then the result will begin with '+' ('\u002b'). If the '#' flag is given then the output will always begin with '0' prefix. If the '0' flag is given then the output will be padded with leading zeros to the field width following any indication of sign. If the ',' flag is given then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'x'  '\u0078'  Requires the output to be formatted as an integer in base sixteen. No localization is applied. If x is negative then the result will be a signed value beginning with '' ('\u002d'). Signed output is allowed for this type because unlike the primitive types it is not possible to create an unsigned equivalent without assuming an explicit datatype size. If x is positive or zero and the '+' flag is given then the result will begin with '+' ('\u002b'). If the '#' flag is given then the output will always begin with the radix indicator "0x". If the '0' flag is given then the output will be padded to the field width with leading zeros after the radix indicator or sign (if present). If the ',' flag is given then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'X'  '\u0058'  The uppercase variant of 'x'. The entire string representing the number will be converted to {@linkplain String#toUpperCase upper case} including the 'x' (if any) andall hexadecimal digits 'a'  'f' ('\u0061'  '\u0066'). 
If the conversion is 'o', 'x', or 'X' and both the '#' and the '0' flags are given, then result will contain the base indicator ('0' for octal and "0x" or "0X" for hexadecimal), some number of zeros (based on the width), and the value.
If the '0' flag is given and the value is negative, then the zero padding will occur after the sign.
If the '' flag is not given, then the space padding will occur before the sign.
All flags defined for Byte, Short, Integer, and Long apply. The default behavior when no flags are given is the same as for Byte, Short, Integer, and Long.
The specification of width is the same as defined for Byte, Short, Integer, and Long.
The precision is not applicable. If precision is specified then an {@link IllegalFormatPrecisionException} will be thrown.
The following conversions may be applied to float, {@link Float}, double and {@link Double}.
'e'  '\u0065'  Requires the output to be formatted using computerized scientific notation. The localization algorithm is applied. The formatting of the magnitude m depends upon its value. If m is NaN or infinite, the literal strings "NaN" or "Infinity", respectively, will be output. These values are not localized. If m is positivezero or negativezero, then the exponent will be "+00". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in the localization algorithm. The formatting of the magnitude m depends upon its value. Let n be the unique integer such that 10^{n} <= m < 10^{n+1}; then let a be the mathematically exact quotient of m and 10^{n} so that 1 <= a < 10. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by the decimal separator followed by decimal digits representing the fractional part of a, followed by the exponent symbol 'e' ('\u0065'), followed by the sign of the exponent, followed by a representation of n as a decimal integer, as produced by the method {@link Long#toString(long,int)}, and zeropadded to include at least two digits. The number of digits in the result for the fractional part of m or a is equal to the precision. If the precision is not specified then the default value is 6. If the precision is less than the number of digits which would appear after the decimal point in the string returned by {@link Float#toString(float)} or {@link Double#toString(double)} respectively, then the value will be roundedusing the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half upalgorithm}. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, use {@link Float#toString(float)} or {@link Double#toString(double)} asappropriate. If the ',' flag is given, then an {@link FormatFlagsConversionMismatchException} will be thrown. 
'E'  '\u0045'  The uppercase variant of 'e'. The exponent symbol will be 'E' ('\u0045'). 
'g'  '\u0067'  Requires the output to be formatted in general scientific notation as described below. The localization algorithm is applied. After rounding for the precision, the formatting of the resulting magnitude m depends on its value. If m is greater than or equal to 10^{4} but less than 10^{precision} then it is represented in decimal format. If m is less than 10^{4} or greater than or equal to 10^{precision}, then it is represented in computerized scientific notation. The total number of significant digits in m is equal to the precision. If the precision is not specified, then the default value is 6. If the precision is 0, then it is taken to be 1. If the '#' flag is given then an {@link FormatFlagsConversionMismatchException} will be thrown. 
'G'  '\u0047'  The uppercase variant of 'g'. 
'f'  '\u0066'  Requires the output to be formatted using decimal format. The localization algorithm is applied. The result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in the localization algorithm. The formatting of the magnitude m depends upon its value. If m NaN or infinite, the literal strings "NaN" or "Infinity", respectively, will be output. These values are not localized. The magnitude is formatted as the integer part of m, with no leading zeroes, followed by the decimal separator followed by one or more decimal digits representing the fractional part of m. The number of digits in the result for the fractional part of m or a is equal to the precision. If the precision is not specified then the default value is 6. If the precision is less than the number of digits which would appear after the decimal point in the string returned by {@link Float#toString(float)} or {@link Double#toString(double)} respectively, then the value will be roundedusing the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half upalgorithm}. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value,use {@link Float#toString(float)} or {@link Double#toString(double)} asappropriate. 
'a'  '\u0061'  Requires the output to be formatted in hexadecimal exponential form. No localization is applied. The result is a string that represents the sign and magnitude (absolute value) of the argument x. If x is negative or a negativezero value then the result will begin with '' ('\u002d'). If x is positive or a positivezero value and the '+' flag is given then the result will begin with '+' ('\u002b'). The formatting of the magnitude m depends upon its value.
If the '(' or ',' flags are given, then a {@link FormatFlagsConversionMismatchException} will be thrown. 
'A'  '\u0041'  The uppercase variant of 'a'. The entire string representing the number will be converted to upper case including the 'x' ('\u0078') and 'p' ('\u0070' and all hexadecimal digits 'a'  'f' ('\u0061'  '\u0066'). 
All flags defined for Byte, Short, Integer, and Long apply.
If the '#' flag is given, then the decimal separator will always be present.
If no flags are given the default formatting is as follows:
The width is the minimum number of characters to be written to the output. This includes any signs, digits, grouping separators, decimal separators, exponential symbol, radix indicator, parentheses, and strings representing infinity and NaN as applicable. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If the '' flag is given then the padding will be on the right. If width is not specified then there is no minimum.
If the conversion is 'e', 'E' or 'f', then the precision is the number of digits after the decimal separator. If the precision is not specified, then it is assumed to be 6.
If the conversion is 'g' or 'G', then the precision is the total number of significant digits in the resulting magnitude after rounding. If the precision is not specified, then the default value is 6. If the precision is 0, then it is taken to be 1.
If the conversion is 'a' or 'A', then the precision is the number of hexadecimal digits after the decimal separator. If the precision is not provided, then all of the digits as returned by {@link Double#toHexString(double)} will be output.
The following conversions may be applied {@link java.math.BigDecimal BigDecimal}.
'e'  '\u0065'  Requires the output to be formatted using computerized scientific notation. The localization algorithm is applied. The formatting of the magnitude m depends upon its value. If m is positivezero or negativezero, then the exponent will be "+00". Otherwise, the result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in the localization algorithm. The formatting of the magnitude m depends upon its value. Let n be the unique integer such that 10^{n} <= m < 10^{n+1}; then let a be the mathematically exact quotient of m and 10^{n} so that 1 <= a < 10. The magnitude is then represented as the integer part of a, as a single decimal digit, followed by the decimal separator followed by decimal digits representing the fractional part of a, followed by the exponent symbol 'e' ('\u0065'), followed by the sign of the exponent, followed by a representation of n as a decimal integer, as produced by the method {@link Long#toString(long,int)}, and zeropadded to include at least two digits. The number of digits in the result for the fractional part of m or a is equal to the precision. If the precision is not specified then the default value is 6. If the precision is less than the number of digits which would appear after the decimal point in the string returned by {@link Float#toString(float)} or {@link Double#toString(double)} respectively, then the value will be roundedusing the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half upalgorithm}. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, use {@link BigDecimal#toString()}. If the ',' flag is given, then an {@link FormatFlagsConversionMismatchException} will be thrown. 
'E'  '\u0045'  The uppercase variant of 'e'. The exponent symbol will be 'E' ('\u0045'). 
'g'  '\u0067'  Requires the output to be formatted in general scientific notation as described below. The localization algorithm is applied. After rounding for the precision, the formatting of the resulting magnitude m depends on its value. If m is greater than or equal to 10^{4} but less than 10^{precision} then it is represented in decimal format. If m is less than 10^{4} or greater than or equal to 10^{precision}, then it is represented in computerized scientific notation. The total number of significant digits in m is equal to the precision. If the precision is not specified, then the default value is 6. If the precision is 0, then it is taken to be 1. If the '#' flag is given then an {@link FormatFlagsConversionMismatchException} will be thrown. 
'G'  '\u0047'  The uppercase variant of 'g'. 
'f'  '\u0066'  Requires the output to be formatted using decimal format. The localization algorithm is applied. The result is a string that represents the sign and magnitude (absolute value) of the argument. The formatting of the sign is described in the localization algorithm. The formatting of the magnitude m depends upon its value. The magnitude is formatted as the integer part of m, with no leading zeroes, followed by the decimal separator followed by one or more decimal digits representing the fractional part of m. The number of digits in the result for the fractional part of m or a is equal to the precision. If the precision is not specified then the default value is 6. If the precision is less than the number of digits which would appear after the decimal point in the string returned by {@link Float#toString(float)} or {@link Double#toString(double)} respectively, then the value will be roundedusing the {@linkplain java.math.BigDecimal#ROUND_HALF_UP round half upalgorithm}. Otherwise, zeros may be appended to reach the precision. For a canonical representation of the value, use {@link BigDecimal#toString()}. 
All flags defined for Byte, Short, Integer, and Long apply.
If the '#' flag is given, then the decimal separator will always be present.
The default behavior when no flags are given is the same as for Float and Double.
The specification of width and precision is the same as defined for Float and Double.
This conversion may be applied to long, {@link Long}, {@link Calendar}, and {@link Date}.
't'  '\u0074'  Prefix for date and time conversion characters. 
'T'  '\u0054'  The uppercase variant of 't'. 
The following date and time conversion character suffixes are defined for the 't' and 'T' conversions. The types are similar to but not completely identical to those defined by GNU date and POSIX strftime(3c). Additional conversion types are provided to access Javaspecific functionality (e.g. 'L' for milliseconds within the second).
The following conversion characters are used for formatting times:
'H'  '\u0048'  Hour of the day for the 24hour clock, formatted as two digits with a leading zero as necessary i.e. 00  23. 00 corresponds to midnight. 
'I'  '\u0049'  Hour for the 12hour clock, formatted as two digits with a leading zero as necessary, i.e. 01  12. 01 corresponds to one o'clock (either morning or afternoon). 
'k'  '\u006b'  Hour of the day for the 24hour clock, i.e. 0  23. 0 corresponds to midnight. 
'l'  '\u006c'  Hour for the 12hour clock, i.e. 1  12. 1 corresponds to one o'clock (either morning or afternoon). 
'M'  '\u004d'  Minute within the hour formatted as two digits with a leading zero as necessary, i.e. 00  59. 
'S'  '\u0053'  Seconds within the minute, formatted as two digits with a leading zero as necessary, i.e. 00  60 ("60" is a special value required to support leap seconds). 
'L'  '\u004c'  Millisecond within the second formatted as three digits with leading zeros as necessary, i.e. 000  999. 
'N'  '\u004e'  Nanosecond within the second, formatted as nine digits with leading zeros as necessary, i.e. 000000000  999999999. The precision of this value is limited by the resolution of the underlying operating system or hardware. 
'p'  '\u0070'  Localespecific {@linkplain java.text.DateFormatSymbols#getAmPmStrings morning or afternoon} markerin lower case, e.g."am" or "pm". Use of the conversion prefix 'T' forces this output to upper case. (Note that 'p' produces lowercase output. This is different from GNU date and POSIX strftime(3c) which produce uppercase output.) 
'z'  '\u007a'  RFC 822 style numeric time zone offset from GMT, e.g. 0800. 
'Z'  '\u005a'  A string representing the abbreviation for the time zone. 
's'  '\u0073'  Seconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC, i.e. Long.MIN_VALUE/1000 to Long.MAX_VALUE/1000. 
'Q'  '\u004f'  Milliseconds since the beginning of the epoch starting at 1 January 1970 00:00:00 UTC, i.e. Long.MIN_VALUE to Long.MAX_VALUE. The precision of this value is limited by the resolution of the underlying operating system or hardware. 
The following conversion characters are used for formatting dates:
'B'  '\u0042'  Localespecific {@linkplain java.text.DateFormatSymbols#getMonths full month name}, e.g. "January", "February". 
'b'  '\u0062'  Localespecific {@linkplain java.text.DateFormatSymbols#getShortMonths abbreviated month name}, e.g. "Jan", "Feb". 
'h'  '\u0068'  Same as 'b'. 
'A'  '\u0041'  Localespecific full name of the {@linkplain java.text.DateFormatSymbols#getWeekdays day of the week}, e.g. "Sunday", "Monday" 
'a'  '\u0061'  Localespecific short name of the {@linkplain java.text.DateFormatSymbols#getShortWeekdays day of the week}, e.g. "Sun", "Mon" 
'C'  '\u0043'  Fourdigit year divided by 100, formatted as two digits with leading zero as necessary, i.e. 00  99 
'Y'  '\u0059'  Year, formatted to at least four digits with leading zeros as necessary, e.g. 0092 equals 92 CE for the Gregorian calendar. 
'y'  '\u0079'  Last two digits of the year, formatted with leading zeros as necessary, i.e. 00  99. 
'j'  '\u006a'  Day of year, formatted as three digits with leading zeros as necessary, e.g. 001  366 for the Gregorian calendar. 001 corresponds to the first day of the year. 
'm'  '\u006d'  Month, formatted as two digits with leading zeros as necessary, i.e. 01  13, where "01" is the first month of the year and ("13" is a special value required to support lunar calendars). 
'd'  '\u0064'  Day of month, formatted as two digits with leading zeros as necessary, i.e. 01  31, where "01" is the first day of the month. 
'e'  '\u0065'  Day of month, formatted as two digits, i.e. 1  31 where "1" is the first day of the month. 
The following conversion characters are used for formatting common date/time compositions.
'R'  '\u0052'  Time formatted for the 24hour clock as "%tH:%tM" 
'T'  '\u0054'  Time formatted for the 24hour clock as "%tH:%tM:%tS". 
'r'  '\u0072'  Time formatted for the 12hour clock as "%tI:%tM:%tS %Tp". The location of the morning or afternoon marker ('%Tp') may be localedependent. 
'D'  '\u0044'  Date formatted as "%tm/%td/%ty". 
'F'  '\u0046'  ISO 8601 complete date formatted as "%tY%tm%td". 
'c'  '\u0063'  Date and time formatted as "%ta %tb %td %tT %tZ %tY", e.g. "Sun Jul 20 16:17:00 EDT 1969". 
The '' flag defined for General conversions applies. If the '#' flag is given, then a {@link FormatFlagsConversionMismatchException} will be thrown.
The width is the minimum number of characters to be written to the output. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left by default. If the '' flag is given then the padding will be on the right. If width is not specified then there is no minimum.
The precision is not applicable. If the precision is specified then an {@link IllegalFormatPrecisionException} will be thrown.
The conversion does not correspond to any argument.
'%'  The result is a literal '%' ('\u0025') The width is the minimum number of characters to be written to the output including the '%'. If the length of the converted value is less than the width then the output will be padded by spaces ('\u0020') until the total number of characters equals width. The padding is on the left. If width is not specified then just the '%' is output. The '' flag defined for General conversions applies. If any other flags are provided, then a {@link FormatFlagsConversionMismatchException} will be thrown. The precision is not applicable. If the precision is specified an {@link IllegalFormatPrecisionException} will be thrown. 
The conversion does not correspond to any argument.
'n'  the platformspecific line separator as returned by {@link System#getProperty System.getProperty("line.separator")}. 
Flags, width, and precision are not applicable. If any are provided an {@link IllegalFormatFlagsException}, {@link IllegalFormatWidthException}, and {@link IllegalFormatPrecisionException}, respectively will be thrown.
Format specifiers can reference arguments in three ways:
For example:
formatter.format("%4$s %3$s %2$s %1$s %4$s %3$s %2$s %1$s", "a", "b", "c", "d") // > "d c b a d c b a"
formatter.format("%s %s %<s %<s", "a", "b", "c", "d") // > "a b b b" // "c" and "d" are ignored because they are not referenced
formatter.format("%s %s %s %s", "a", "b", "c", "d") // > "a b c d"
It is possible to have a format string which uses all forms of indexing, for example:
formatter.format("%2$s %s %<s %s", "a", "b", "c", "d") // > "b a a b" // "c" and "d" are ignored because they are not referenced
The maximum number of arguments is limited by the maximum dimension of a Java array as defined by the Java Virtual Machine Specification. If the argument index is does not correspond to an available argument, then a {@link MissingFormatArgumentException} is thrown.
If there are more arguments than format specifiers, the extra arguments are ignored.
Unless otherwise specified, passing a null argument to any method or constructor in this class will cause a {@link NullPointerException} to be thrown. @author Iris Clark @version 1.27, 02/04/09 @since 1.5
Typically each logging Handler will have a Formatter associated with it. The Formatter takes a LogRecord and converts it to a string.
Some formatters (such as the XMLFormatter) need to wrap head and tail strings around a set of formatted records. The getHeader and getTail methods can be used to obtain these strings. @version 1.17, 11/17/05 @since 1.4
Interface that is used to provide a relatively simple formatting interface to the rest of the system. Designed to wrap the complexity of the java.text format classes in an interface that can take two (or three if you include Locale) parameters from tags and apply formats in an intelligent way.
In terms of lifecycle, a formatter will be instantiated, have setFormatType(), setFormatString() and setLocale() called in rapid succession. If no values were supplied, setFormatType() and setFormatString() may not be called  and implementations should select reasonable defaults. Locale will always be provided. After the setters have been called, init() will be called, and the Formatter should use this opportunity to construct any internal objects necessary to perform formatting. The format() method will then be called one or more times before the Formatter is eventually dereferenced.
@author Tim Fennellformatters are very powerful because not only do they have access to the record's value for that column's field, but they also receive the rest of the record's data, the record Model instance itself, and the column configuration object. This allows you to include any extra configurations in your column configuration that might be useful to customizing how cells in the column are rendered.
function currency(o) { return Y.DataType.Number.format(o.value, { prefix : o.column.currencySymbol  '$', decimalPlaces : o.column.decimalPlaces  2, decimalSeparator : o.column.decimalSeparator  '.', thousandsSeparator: o.column.thousandsSeparator  ',' }); } var cols = [ { key: "price", formatter: currency, decimalPlaces: 3 }, ...@author sg



















