Package com.smartgwt.client.docs

# Interface FormatString

public interface FormatString
A String to be used as a format specifier for a date, datetime, time or numeric field, via the `format` and `exportFormat` properties.

For fields with a numeric type, the format string is similar to java.text.NumberFormat (see DecimalFormat JavaDoc), and for date, time, and datetime types, the format string is similar to java.text.SimpleDateFormat (see SimpleDateFormat JavaDoc).

Note that all the client-side formatting described in this section is is done by the `NumberUtil.format()` and `com.smartgwt.client.util.DateUtil#format()` methods. These are static utility methods that your own code can call if you need to programmatically format a date or number using a `FormatString`

There are 3 possible contexts where a `FormatString` may be interpreted, and each has slightly different limitations:

#### in-browser rendering & client-driven exports

Almost complete support for Java's SimpleDateFormat/DecimalFormat, as described below, with some small extensions for formatting with awareness of a `FiscalCalendar`.

This category includes cases where code running in the browser does the rendering and the rendered result is passed to the server, such as `client-driven export` and `PDF export of the printed view`.

#### Excel export

Almost the same as in-browser rendering, with minor limitations due to missing features in Excel. Exact differences are described under `DataSourceField.exportFormat`.

#### non-Excel server export

For example, CSV, XML or JSON `export formats` provided via `DataSource.exportData()`. Full support for SimpleDateFormat/DecimalFormat as provided by whichever Java version you have installed on the server. However note that depending on the context of the export, the default behavior may be to ignore format strings, since formatting intended for end users wouldn't be desirable if data exchange is the goal. See the `Export Formatting overview` for details.

### Date Format

Format token | Description | Sample value
yy | Year as a two-digit number | "99" or "07"
yyyy | Year as a four-digit number | "1999" or "2007"
YY | Week year as a two-digit number (week year is the year associated with the entire week deemed to contain a given date, and it may differ from calendar year. For example, the week year of December 31 2012 is 2013) | "99" or "07"
YYYY | Week year as a four-digit number | "1999" or "2007"
LL | Fiscal year as a two-digit number (`FiscalCalendar`) | "99" or "07"
LLLL | Fiscal year as a four-digit number | "1999" or "2007"
M | Month in year | "1" to "12"
MM | Month in year with leading zero if required | "01" to "12"
MMM | Short month name (`com.smartgwt.client.util.DateUtil#setShortMonthNames()`) | "Jan" to "Dec"
MMMM | Full month name (`com.smartgwt.client.util.DateUtil#setMonthNames()`) | "January" to "December"
w | Week in year | "1" to "52"
ww | Week in year with leading zero if required | "01" to "52"
C | Week in fiscal year (`FiscalCalendar`) | "7" or "29"
CC | Week in fiscal year with leading zero if required | "07" or "29"
d | Day of the month | "1" to "31"
dd | Day of the month with leading zero if required | "01" to "31"
ddd | Short day name (`shortDayNames`) | "Mon" to "Sun"
dddd | Full day name. (`dayNames`) | "Monday" to "Sunday"
E | Short day name ("EE" and "EEE" are equivalent; all are exactly the same as "ddd" - "E" is supported purely to conform with SimpleDateFormat) | "Mon" to "Sun"
EEEE | Full day name (exactly the same as "dddd") | "Monday" to "Sunday"
D | Day in year | "1" to "366"
DD | Day in year with leading zero if required | "01" to "366"
c | Day in fiscal year (`FiscalCalendar`) | "5" or "204"
cc | Day in fiscal year with leading zero if required | "05" or "204"
u | Day number in week (1 is Monday) | "1" to "7"
H | Hour in day, 0-23 (24-hour clock) | "0" to "23"
HH | Hour in day with leading zero if required (24-hour) | "00" to "23"
h | Hour in day, 1-12 (12-hour clock) | "1" to "12"
hh | Hour in day with leading zero if required (12-hour) | "01" to "12"
m | Minute in hour | "0" to "59"
mm | Minute in hour with leading zero if required | "00" to "59"
s | Second in minute | "0" to "59"
ss | Second in minute with leading zero if required | "00" to "59"
S | Millisecond in second | "0" to "999"
SSS | Millisecond in second with leading zero(s) if required | "000" to "999"
a | The AM/PM designator (String) | " am" or " pm"

Note that all text that doesn't represent tokens specified above will be passed through to the output, but such unmapped character sequences are reserved for future use. To future-proof your code, you may single quote `"'"` any text to escape it to ensure no formatting is applied, guaranting that it's passed through unaltered. Thus, a format of `"h'h'"` might end up as `"5h"`. To create a single quote itself, use two in a row - for example `"h o''clock"`.

### Examples - various formatted versions of the datetime "2006-08-03 11:26:18"

"M/d/yy" | 8/3/06
"MMMM yyyy" | August 2006
"HH:mm" | 11:26
"d MMM yyyy, H:ma" | 3 Aug 2006, 11:26 am
"dd/MM/yyyy" | 03/08/2006
"CC/LLLL" | 53/2006 (assuming the fiscal year ends in the first week of August)

### `SimpleDateFormat` specifiers that we do not support:

- Era designator, BC/AD (G)
- Day of week in month (F)
- Hour in day, 24-hour, with 1-based instead of normal 0-based numbering (hours are 1-24) (k)
- Hour in day, 12-hour, with 0-based instead of normal 1-based numbering (hours are 0-11) (K)
- Timezone (z, Z, X)

### Number Format

Format char | Description
0 | Digit, zero is displayed
# | Digit, zero is not displayed
- | Minus sign
. | Decimal separator
% | Multiply by 100 and show as percentage
‰ (‰) | Multiply by 1000 and show as per mille. See below.
, | Indicates digit grouping should be used - eg 1,000,000. See below.
; | Separates positive and negative subpatterns. See below.
¤ (\\u00A4) | As a prefix or suffix, indicates the local currency symbol should be used. Note that you must use special notation to include this character in an XML file (such as a .ds.xml file). See below.
' | Used to quote special characters in a prefix or suffix, for example, "'#'#" formats 123 to "#123". To create a single quote itself, use two in a row: "# o''clock".

All other characters in the format string are taken literally and output unchanged.

### Examples

Format string | Zero value | Positive value: 12345.678 | Negative value: -2345.123
"0.00" | 0.00 | 12345.68 | -2345.12
",##0.00" | 0.00 | 12,345.68 | -2,345.12
"0.###" | 0 | 12345.678 | -2345.123
"¤,0.00" | $0.00 | $12,345.68 | -$2345.12
"0.0#%" | 0.0% | 1234567.8% | -234512.3%
"0.0#‰" | 0.0‰ | 12345678.0‰ | -2345123.0‰
"0.0#'%'" | 0.0% | 12345.68% | -2345.12%
"0.00;(0.00)" | 0.0% | 12345.68 | (2345.12)

Note, the above examples include cases where there are multiple '#' characters in the integer part of the number format (ie, to the left of the decimal separator, or the entire format if there is no separator). We support this pattern simply because `DecimalFormat` does: the extra '#' characters are not significant. In other words, the format "##0.00" produces exactly the same formatting as "0.00", and "##,###,###.##" produces exactly the same formatting as ",#.##". However, multiple '0' characters in the integer part of the format are significant, as are both '#' and '0' characters in the decimal part of the format (ie, to the right of any decimal separator).

The ";" character marks the boundary between two subpatterns - the first to be used for formatting positive numbers (and 0), the second for negative numbers. Specifying a separate pattern for negative numbers is optional: if no negative subpattern is specified, negative numbers are formatted like positive numbers, but with a leading "-" sign.

The "¤" symbol (¤) is documented in the Java DecimalFormat class as a placeholder for the currency symbol appropriate to the current locale. For client-driven exports, we replace it with whatever GWT's built-in NumberFormat's class uses. Likewise, the decimal symbol and grouping symbol will match what GWT's NumberFormat returns. Note that "¤" is the correct way to specify this character in Javascript code. If you need to specify the character in an XML file - the common requirement is in a .ds.xml DataSource descriptor file - you must use the code "&#x00A4;" instead.

The "‰" per mille symbol is specified as "‰" in Javascript code; in XML or HTML you can use either the equivalent notation "&#x2030;" or the special HTML code "&permil;".

### `DecimalFormat` features that we do not support:

- Scientific notation
- Doubled currency symbol means "use international currency symbol"
- We do not support arbitrary digit grouping, by providing patterns of the '#' and ',' characters, like `DecimalFormat` does. Grouping in Smart GWT FormatStrings is enabled with a single "," character somewhere before or within the number-formatting part of the string - extra "," characters within the number-formatting part of the string are tolerated, but they have no effect. Grouping in Smart GWT always causes digits to be gathered in groups of three