License:
BSD style: see license.txtVersion:
Initial release: 2005Author:
John Chapman Contains classes that provide information about locales, such as the language and calendars, as well as cultural conventions used for formatting dates, currency and numbers. Use these classes when writing applications for an international audience.Interface | Description |
---|---|
IFormatService | Retrieves an object to control formatting. |
Class | Description |
---|---|
Calendar | Represents time in week, month and year divisions. |
Culture | Provides information about a culture, such as its name, calendar and date and number format patterns. |
DateTimeFormat | Determines how Time values are formatted, depending on the culture. |
DaylightSavingTime | Represents a period of daylight-saving time. |
Gregorian | Represents the Gregorian calendar. |
Hebrew | Represents the Hebrew calendar. |
Hijri | Represents the Hijri calendar. |
Japanese | Represents the Japanese calendar. |
Korean | Represents the Korean calendar. |
NumberFormat | Determines how numbers are formatted, according to the current culture. |
Region | Provides information about a region. |
Taiwan | Represents the Taiwan calendar. |
ThaiBuddhist | Represents the Thai Buddhist calendar. |
Struct | Description |
---|---|
Time | Represents time expressed as a date and time of day. |
TimeSpan | Represents a time interval. |
Remarks:
IFormatService is implemented by Culture, NumberFormat and DateTimeFormat to provide locale-specific formatting of numbers and date and time values.Remarks:
tango.text.locale adopts the RFC 1766 standard for culture names in the format <language>"-"<region>. <language> is a lower-case two-letter code defined by ISO 639-1. <region> is an upper-case two-letter code defined by ISO 3166. For example, "en-GB" is UK English.Examples:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | import tango.io.Stdout, tango.text.locale.Core; void main() { Culture culture = new Culture("it-IT"); Stdout.formatln("englishName: {}", culture.englishName); Stdout.formatln("nativeName: {}", culture.nativeName); Stdout.formatln("name: {}", culture.name); Stdout.formatln("parent: {}", culture.parent.name); Stdout.formatln("isNeutral: {}", culture.isNeutral); } // Produces the following output: // englishName: Italian (Italy) // nativeName: italiano (Italia) // name: it-IT // parent: it // isNeutral: false |
Params:
cultureName | The name of the Culture. |
Params:
cultureID | The identifer (LCID) of the Culture. |
Remarks:
Culture identifiers correspond to a Windows LCID.Params:
type | The TypeInfo of the resulting formatting object. |
Returns:
If type is typeid(NumberFormat), the value of the numberFormat property. If type is typeid(DateTimeFormat), the value of the dateTimeFormat property. Otherwise, null.Remarks:
Implements IFormatService.getFormat.Params:
cultureID | The identifier of the culture. |
Returns:
A read-only culture instance.Remarks:
Instances returned by this method are cached.Params:
cultureName | The name of the culture. |
Returns:
A read-only culture instance.Remarks:
Instances returned by this method are cached.Params:
name | The name of the language. |
Returns:
A read-only culture instance.Params:
types | A combination of CultureTypes. |
Returns:
An array of Culture instances containing cultures specified by types.Returns:
A string containing the name of the Culture in the format <language>"-"<region>.Returns:
The Culture instance representing the user's current culture.Params:
value | The Culture instance representing the user's _current culture. |
Examples:
The following examples shows how to change the _current culture.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | import tango.io.Print, tango.text.locale.Common; void main() { // Displays the name of the current culture. Println("The current culture is %s.", Culture.current.englishName); // Changes the current culture to el-GR. Culture.current = new Culture("el-GR"); Println("The current culture is now %s.", Culture.current.englishName); } // Produces the following output: // The current culture is English (United Kingdom). // The current culture is now Greek (Greece). |
Returns:
The Culture instance that is invariant.Remarks:
The invariant culture is culture-independent. It is not tied to any specific region, but is associated with the English language.Returns:
The culture identifier of the current instance.Remarks:
The culture identifier corresponds to the Windows locale identifier (LCID). It can therefore be used when interfacing with the Windows NLS functions.Returns:
The name of the current instance. For example, the name of the UK English culture is "en-GB".Returns:
The name of the current instance in English. For example, the englishName of the UK English culture is "English (United Kingdom)".Returns:
The name of the current instance in its native language. For example, if Culture.name is "de-DE", nativeName is "Deutsch (Deutschland)".Returns:
The two-letter language code of the Culture instance. For example, the twoLetterLanguageName for English is "en".Returns:
The three-letter language code of the Culture instance. For example, the threeLetterLanguageName for English is "eng".Returns:
A string representing the RFC 3066 language identification.Returns:
The Culture representing the parent of the current instance.Returns:
true is the current Culture represents a neutral culture; otherwise, false.Examples:
The following example displays which cultures using Chinese are neutral.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 | import tango.io.Print, tango.text.locale.Common; void main() { foreach (c; Culture.getCultures(CultureTypes.All)) { if (c.twoLetterLanguageName == "zh") { Print(c.englishName); if (c.isNeutral) Println("neutral"); else Println("specific"); } } } // Produces the following output: // Chinese (Simplified) - neutral // Chinese (Taiwan) - specific // Chinese (People's Republic of China) - specific // Chinese (Hong Kong S.A.R.) - specific // Chinese (Singapore) - specific // Chinese (Macao S.A.R.) - specific // Chinese (Traditional) - neutral |
Returns:
true if the instance is read-only; otherwise, false.Remarks:
If the culture is read-only, the dateTimeFormat and numberFormat properties return read-only instances.Returns:
A Calendar instance respresenting the calendar used by the culture.Returns:
An array of type Calendar representing the calendars that can be used by the culture.Returns:
A NumberFormat defining the culturally appropriate format for displaying numbers and currency.Params:
values | A NumberFormat defining the culturally appropriate format for displaying numbers and currency. |
Returns:
A DateTimeFormat defining the culturally appropriate format for displaying dates and times.Params:
values | A DateTimeFormat defining the culturally appropriate format for displaying dates and times. |
Remarks:
Region does not represent user preferences. It does not depend on the user's language or culture.Examples:
The following example displays some of the properties of the Region class:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 | import tango.io.Print, tango.text.locale.Common; void main() { Region region = new Region("en-GB"); Println("name: %s", region.name); Println("englishName: %s", region.englishName); Println("isMetric: %s", region.isMetric); Println("currencySymbol: %s", region.currencySymbol); Println("isoCurrencySymbol: %s", region.isoCurrencySymbol); } // Produces the following output. // name: en-GB // englishName: United Kingdom // isMetric: true // currencySymbol: £ // isoCurrencySymbol: GBP |
Params:
cultureID | A culture indentifier. |
Remarks:
The name of the Region instance is set to the ISO 3166 two-letter code for that region.Params:
name | A two-letter ISO 3166 code for the region. Or, a culture _name consisting of the language and region. |
Returns:
The Region instance associated with the current Culture.Returns:
An int uniquely identifying the geographical location.Returns:
The value specified by the name parameter of the Region(char[]) constructor.Returns:
The full name of the region in English.Returns:
The full name of the region in the language associated with the region code.Returns:
The two-letter ISO 3166 code of the region.Returns:
The three-letter ISO 3166 code of the region.Returns:
The currency symbol of the region.Returns:
The three-character currency symbol of the region.Returns:
The name in English of the currency used in the region.Returns:
The name in the native language of the region of the currency used in the region.Returns:
true is the region uses the metric system; otherwise, false.Returns:
A string containing the ISO 3166 code, or the name, of the current Region.Remarks:
Numbers are formatted using format patterns retrieved from a NumberFormat instance. This class implements IFormatService.getFormat.Examples:
The following example shows how to retrieve an instance of NumberFormat for a Culture and use it to display number formatting information.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 | import tango.io.Print, tango.text.locale.Common; void main(char[][] args) { foreach (c; Culture.getCultures(CultureTypes.Specific)) { if (c.twoLetterLanguageName == "en") { NumberFormat fmt = c.numberFormat; Println("The currency symbol for %s is '%s'", c.englishName, fmt.currencySymbol); } } } // Produces the following output: // The currency symbol for English (United States) is '$' // The currency symbol for English (United Kingdom) is '£' // The currency symbol for English (Australia) is '$' // The currency symbol for English (Canada) is '$' // The currency symbol for English (New Zealand) is '$' // The currency symbol for English (Ireland) is '€' // The currency symbol for English (South Africa) is 'R' // The currency symbol for English (Jamaica) is 'J$' // The currency symbol for English (Caribbean) is '$' // The currency symbol for English (Belize) is 'BZ$' // The currency symbol for English (Trinidad and Tobago) is 'TT$' // The currency symbol for English (Zimbabwe) is 'Z$' // The currency symbol for English (Republic of the Philippines) is 'Php' |
Remarks:
Modify the properties of the new instance to define custom formatting.Params:
type | The TypeInfo of the resulting formatting object. |
Returns:
If type is typeid(NumberFormat), the current NumberFormat instance. Otherwise, null.Remarks:
Implements IFormatService.getFormat.Params:
formatService | The IFormatService used to retrieve NumberFormat. |
Returns:
The NumberFormat for the specified IFormatService.Remarks:
The method calls IFormatService.getFormat with typeof(NumberFormat). If formatService is null, then the value of the current property is returned.Returns:
A read-only NumberFormat instance from the current culture.Returns:
The read-only, culturally independent NumberFormat instance.Returns:
true if the instance is read-only; otherwise, false.Returns:
The number of decimal places used for numbers. For invariantFormat, the default is 2.Params:
value | The number of decimal places used for numbers. |
Throws:
Exception if the property is being set and the instance is read-only.Examples:
The following example shows the effect of changing numberDecimalDigits.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | import tango.io.Print, tango.text.locale.Common; void main() { // Get the NumberFormat from the en-GB culture. NumberFormat fmt = (new Culture("en-GB")).numberFormat; // Display a value with the default number of decimal digits. int n = 5678; Println(Formatter.format(fmt, "{0:N}", n)); // Display the value with six decimal digits. fmt.numberDecimalDigits = 6; Println(Formatter.format(fmt, "{0:N}", n)); } // Produces the following output: // 5,678.00 // 5,678.000000 |
Returns:
The format pattern for negative numbers. For invariantFormat, the default is 1 (representing "-n").Remarks:
The following table shows valid values for this property.Value | Pattern |
---|---|
0 | (n) |
1 | -n |
2 | - n |
3 | n- |
4 | n - |
Params:
value | The format pattern for negative numbers. |
Examples:
The following example shows the effect of the different patterns.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 | import tango.io.Print, tango.text.locale.Common; void main() { NumberFormat fmt = new NumberFormat; int n = -5678; // Display the default pattern. Println(Formatter.format(fmt, "{0:N}", n)); // Display all patterns. for (int i = 0; i <= 4; i++) { fmt.numberNegativePattern = i; Println(Formatter.format(fmt, "{0:N}", n)); } } // Produces the following output: // (5,678.00) // (5,678.00) // -5,678.00 // - 5,678.00 // 5,678.00- // 5,678.00 - |
Returns:
The number of decimal digits to use in currency values.Params:
value | The number of decimal digits to use in currency values. |
Returns:
The format pattern to use for negative currency values.Params:
value | The format pattern to use for negative currency values. |
Returns:
The format pattern to use for positive currency values.Returns:
The format pattern to use for positive currency values.Returns:
The number of digits int each group to the left of the decimal place in numbers.Params:
value | The number of digits int each group to the left of the decimal place in numbers. |
Returns:
The number of digits int each group to the left of the decimal place in currency values.Params:
value | The number of digits int each group to the left of the decimal place in currency values. |
Returns:
The string separating groups of digits to the left of the decimal place in numbers. For example, ",".Params:
value | The string separating groups of digits to the left of the decimal place in numbers. |
Returns:
The string used as the decimal separator in numbers. For example, ".".Params:
value | The string used as the decimal separator in numbers. |
Returns:
The string separating groups of digits to the left of the decimal place in currency values. For example, ",".Params:
value | The string separating groups of digits to the left of the decimal place in currency values. |
Returns:
The string used as the decimal separator in currency values. For example, ".".Params:
value | The string used as the decimal separator in currency values. |
Returns:
The string used as the currency symbol. For example, "£".Params:
value | The string used as the currency symbol. |
Returns:
The string denoting that a number is negative. For example, "-".Params:
value | The string denoting that a number is negative. |
Returns:
The string denoting that a number is positive. For example, "+".Params:
value | The string denoting that a number is positive. |
Returns:
The string representing the NaN value. For example, "NaN".Params:
value | The string representing the NaN value. |
Returns:
The string representing negative infinity. For example, "-Infinity".Params:
value | The string representing negative infinity. |
Returns:
The string representing positive infinity. For example, "Infinity".Params:
value | The string representing positive infinity. |
Returns:
A string array of native equivalents of the digits 0 to 9.Params:
value | A string array of native equivalents of the digits 0 to 9. |
Remarks:
To create a DateTimeFormat for a specific culture, create a Culture for that culture and retrieve its dateTimeFormat property. To create a DateTimeFormat for the user's current culture, use the current property.Params:
type | The TypeInfo of the resulting formatting object. |
Returns:
If type is typeid(DateTimeFormat), the current DateTimeFormat instance. Otherwise, null.Remarks:
Implements IFormatService.getFormat.Returns:
An array of strings containing the standard patterns in which Time values can be formatted.Returns:
An array of strings containing the standard patterns in which Time values can be formatted using the specified format character.Params:
dayOfWeek | A DayOfWeek value. |
Returns:
The abbreviated name of the day of the week represented by dayOfWeek.Params:
dayOfWeek | A DayOfWeek value. |
Returns:
The full name of the day of the week represented by dayOfWeek.Params:
month | An integer between 1 and 13 indicating the name of the _month to return. |
Returns:
The abbreviated name of the _month represented by month.Params:
month | An integer between 1 and 13 indicating the name of the _month to return. |
Returns:
The full name of the _month represented by month.Params:
formatService | The IFormatService used to retrieve DateTimeFormat. |
Returns:
The DateTimeFormat for the specified IFormatService.Remarks:
The method calls IFormatService.getFormat with typeof(DateTimeFormat). If formatService is null, then the value of the current property is returned.Returns:
A read-only DateTimeFormat instance from the current culture.Returns:
A read-only DateTimeFormat instance that is culturally independent.Returns:
true is the instance is read-only; otherwise, false.Returns:
The Calendar determining the calendar used by the current culture. For example, the Gregorian.Params:
value | The Calendar determining the calendar to be used by the current culture. |
Exceptions:
If value is not valid for the current culture, an Exception is thrown.Returns:
A DayOfWeek value indicating the first day of the week.Params:
valie | A DayOfWeek value indicating the first day of the week. |
Returns:
A CalendarWeekRule _value determining the first week of the year.Params:
value | A CalendarWeekRule _value determining the first week of the year. |
Returns:
The native name of the calendar associated with the current instance.Returns:
The string separating date components.Params:
value | The string separating date components. |
Returns:
The string separating time components.Params:
value | The string separating time components. |
Returns:
The string designator for hours before noon. For example, "AM".Params:
value | The string designator for hours before noon. |
Returns:
The string designator for hours after noon. For example, "PM".Params:
value | The string designator for hours after noon. |
Returns:
The format pattern for a short date value.Params:
value | The format pattern for a short date _value. |
Returns:
The format pattern for a short time value.Params:
value | The format pattern for a short time _value. |
Returns:
The format pattern for a long date value.Params:
value | The format pattern for a long date _value. |
Returns:
The format pattern for a long time value.Params:
value | The format pattern for a long time _value. |
Returns:
The format pattern for a month and day value.Params:
value | The format pattern for a month and day _value. |
Returns:
The format pattern for a year and month value.Params:
value | The format pattern for a year and month _value. |
Returns:
A string array containing the abbreviated names of the days of the week. For invariantFormat, this contains "Sun", "Mon", "Tue", "Wed", "Thu", "Fri" and "Sat".Params:
value | A string array containing the abbreviated names of the days of the week. |
Returns:
A string array containing the full names of the days of the week. For invariantFormat, this contains "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday" and "Saturday".Params:
value | A string array containing the full names of the days of the week. |
Returns:
A string array containing the abbreviated names of the months. For invariantFormat, this contains "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" and "".Params:
value | A string array containing the abbreviated names of the months. |
Returns:
A string array containing the full names of the months. For invariantFormat, this contains "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December" and "".Params:
value | A string array containing the full names of the months. |
Returns:
The format pattern for a long date and a long time value.Params:
value | The format pattern for a long date and a long time _value. |
Returns:
The format pattern based on the IETF RFC 1123 specification, for a time value.Returns:
The format pattern for a sortable date and time value.Returns:
The format pattern for a universal date and time value.