Globalization is part of the Tangere.Net Internationalization (i18n) module and based on JQuery Globalize.
When formatting a number with format(), the main purpose is to convert the number into a human readable string using the culture's standard grouping and decimal rules. The rules between cultures can vary a lot. For example, in some cultures, the grouping of numbers is done unevenly. In the "te-IN" culture (Telugu in India), groups have 3 digits and then 2 digits. The number 1000000 (one million) is written as "10,00,000". Some cultures do not group numbers at all.
There are four main types of number formatting:
- n for number
- d for decimal digits
- p for percentage
- c for currency
Even within the same culture, the formatting rules can vary between these four types of numbers. For example, the expected number of decimal places may differ from the number format to the currency format. Each format token may also be followed by a number. The number determines how many decimal places to display for all the format types except decimal, for which it means the minimum number of digits to display, zero padding it if necessary. Also note that the way negative numbers are represented in each culture can vary, such as what the negative sign is, and whether the negative sign appears before or after the number. This is especially apparent with currency formatting, where many cultures use parentheses instead of a negative sign.
// just for example - will vary by culture
Globalize.format( 123.45, "n" ); // 123.45
Globalize.format( 123.45, "n0" ); // 123
Globalize.format( 123.45, "n1" ); // 123.5
Globalize.format( 123.45, "d" ); // 123
Globalize.format( 12, "d3" ); // 012
Globalize.format( 123.45, "c" ); // $123.45
Globalize.format( 123.45, "c0" ); // $123
Globalize.format( 123.45, "c1" ); // $123.5
Globalize.format( -123.45, "c" ); // ($123.45)
Globalize.format( 0.12345, "p" ); // 12.35 %
Globalize.format( 0.12345, "p0" ); // 12 %
Globalize.format( 0.12345, "p4" ); // 12.3450 %
Parsing with parseInt and parseFloat also accepts any of these formats.
Date formatting varies wildly by culture, not just in the spelling of month and day names, and the date separator, but by the expected order of the various date components, whether to use a 12 or 24 hour clock, and how months and days are abbreviated. Many cultures even include "genitive" month names, which are different from the typical names and are used only in certain cases.
Also, each culture has a set of "standard" or "typical" formats. For example, in "en-US", when displaying a date in its fullest form, it looks like "Saturday, November 05, 1955". Note the non-abbreviated day and month name, the zero padded date, and four digit year. So, Globalize expects a certain set of "standard" formatting strings for dates in the "patterns" property of the "standard" calendar of each culture, that describe specific formats for the culture. The third column shows example values in the neutral English culture "en-US"; see the second table for the meaning tokens used in date formats.
||Long Date, Short Time
||dddd, MMMM dd, yyyy h:mm tt
||Long Date, Long Time
||dddd, MMMM dd, yyyy h:mm:ss tt
||dddd, MMMM dd, yyyy
In addition to these standard formats, there is the "S" format. This is a sortable format that is identical in every culture: "yyyy'-'MM'-'dd'T'HH':'mm':'ss".
When more specific control is needed over the formatting, you may use any format you wish by specifying the following custom tokens:
||Day of month (no leading zero)
||Day of month (leading zero)
||Day name (abbreviated)
||Day name (full)
||Month of year (no leading zero)
||Month of year (leading zero)
||Month name (abbreviated)
||Month name (full)
||Year (two digits)
||Year (four digits)
||'of the clock'
||Minutes (no leading zero)
||Minutes (leading zero)
||Hours (12 hour time, no leading zero)
||Hours (12 hour time, leading zero)
||Hours (24 hour time, no leading zero)
||5 (5am) 15 (3pm)
||Hours (24 hour time, leading zero)
||05 (5am) 15 (3pm)
||Seconds (no leading zero)
||Seconds (leading zero)
||AM/PM indicator (first letter)
||A or P
||AM/PM indicator (full)
||AM or PM
||Timezone offset (hours only, no leading zero)
||Timezone offset (hours only, leading zero)
||Timezone offset (full hours/minutes)
|g or gg