Working with Regional Data

Understanding how to work with and display data for various cultures is another key step to developing global applications. Different cultures have different number formats, currency symbols, ways of sorting data—even different calendars. In this section we'll detail how to work with data in a cross-cultural application.

Numbers and Currency

Fortunately, after a user's culture has been set, things such as decimal separators and numeric symbols work according to the rules of a given culture. These rules are defined by an instance of the NumberFormatInfo class. To obtain an instance of NumberFormatInfo based on the current executing thread, you call the CurrentCulture.NumberFormat property, as in the following:

myNumInfo = Threading.Thread.CurrentThread.CurrentCulture.NumberFormat

You can also set the same property from the CultureInfo object when working with custom culture objects.

To function with a given culture, the NumberFormatInfo class is not required by your application. Instead, it provides finite control over and access to how numbers get formatted. Let's use the following example: Suppose we have to display the price of our product in both yen and dollars. We can simply switch our application's culture and write out the price. The formatting is done for us automatically. Or suppose that the user's current culture is English-United States, but your requirement is to always display both dollars and yen. We can create a custom CultureInfo object and pass it as a provider to the ToString method when outputting our price. The following illustrates this example:

Imports System.Globalization

Module Module1

  Sub Main()

    Dim myPrice As Decimal = 38.99

    'set the current culture to English-United States
    Threading.Thread.CurrentThread.CurrentCulture = _
      New CultureInfo(name:="en-US")

    'display the price in dollars
    Console.WriteLine(myPrice.ToString(Format:="c"))

    'create a cultureInfo object for Japanese-Japan
    Dim myJapan As New CultureInfo(name:="ja-JP")

    'display the price in yen
    Console.WriteLine(myPrice.ToString(Format:="c", provider:=myJapan))

  End Sub

End Module

The result of this routine is the values $38.99 and ¥39 written to the console window. The value c passed as the first parameter to the ToString method is a format character that denotes currency. Some other common format characters include: d for decimal, e for exponential, f for fixed-point, and x for hexadecimal.

Of course, you can override the default behavior of the NumberFormatInfo class for a given culture. What if, for instance, you wanted to show the yen price from the preceding example using two digits after the decimal (¥38.99)? You would add the following line:

myJapan.NumberFormat.CurrencyDecimalDigits = 2

Other NumberFormatInfo properties include CurrencySymbol, NegativeSign, and PercentDecimalDigits, to name a few. The NumberFormatInfo class provides more than 25 properties that you can use to change the way in which a culture's numbers are formatted.

Dates and Times

Date and time formats are also defined by the current culture. The DateTimeFormat property of the CultureInfo class is of the type DateTimeFormatInfo class. This class defines the various patterns used to display dates and times based on a user's preferred culture. This class is primarily used for overriding or accessing these values to determine a given culture's specific default format.

The following is an example of the result of simply switching cultures and displaying the current date and time.

'set the current culture to English-US
Threading.Thread.CurrentThread.CurrentCulture = _
  New CultureInfo(name:="en-US")

'write out the date value
Console.WriteLine(Now)

'change the current culture to Japanese-Japan
Threading.Thread.CurrentThread.CurrentCulture = _
  New CultureInfo(name:="ja-JP")

'write out the date value
Console.WriteLine(Now)

The code outputs the English date of 9/24/2001 9:27:44 a.m. followed by the Japanese version of the same date and time of 2001/09/24 9:27:44. However, suppose you want to override the default date separate for the English-United States culture (“/”). You would do so using the DateSeparator property, as in the following:

Threading.Thread.CurrentThread. _
  CurrentCulture.DateTimeFormat.DateSeparator = "."

The DateFormatInfo class also enables you to return dates in various formats or patterns. These properties include LongDatePattern, LongTimePattern, MonthDayPattern, ShortDatePattern, ShortTimePattern, YearMonthPattern. Other notable properties of the DateFormatInfo class include the following:

• AMDesignator— Used to return or set a string value that indicates time that is “ante meridiem” (before noon).

• CalendarWeekRule— Specifies the rule to use (of type CalendarWeekRule enumeration) to determine the first calendar week of the year.

• DayNames— Used to return or set an array that indicates the culture's names for the days of the week.

• FirstDayOfWeek— Used to return or set the culture's accepted day that a week starts. The property is of the type DateTime.DayOfWeek enumeration.

• MonthNames— Used to return or set an array that indicates the culture's names for the months in a year.

• PMDesignator— Used to return or set a string value that indicates time that is “post meridiem” (after noon).

Calendars

A culture's calendar is another important item to consider when creating applications of a global scale. Calendar classes in .NET are used to divide time into a culture's recognized units. For instance, a year can be divided into a number of months, a month into days, and so on. Each calendar can represent these items differently. .NET provides the base class Calendar for creating classes that define a culture's calendar. The Framework Class Library defines the calendars listed in Table 21.3.

To access a given culture's calendar, you can use the Calendar property of the CultureInfo class. This will return its default calendar class. Some cultures, however, support multiple calendars. Access to these calendars can be gained through the CultureInfo class's OptionalCalendars property. As an example, the following code outputs the calendars used in the culture Hebrew-Israel. The output is HebrewCalendar followed by GregorianCalendar.

Dim myCulture As CultureInfo
Dim i As Short

'create new culture (Hebrew-Israel)
myCulture = New CultureInfo("he-IL")

'display optional calendars
For i = 0 To myCulture.OptionalCalendars.Length - 1
  Console.WriteLine(myCulture.OptionalCalendars(i).ToString)
Next

The calendar classes contain a number of methods for getting information about how a specific time is represented by a given calendar. These methods primarily use the DateTime class as a parameter. The methods of the DateTime class always use the Gregorian calendar to perform calculations. However, the results can be mapped directly to an instance of another calendar. For example, the GetDayOfWeek method returns a value of the type DayOfWeek enumeration for a given DateTime value. Other key methods include AddMonths, AddWeeks, AddYears, GetDayOfMonth, GetDayOfYear, GetDaysInMonth, GetDaysInYear, GetMonth, IsLeapDay, IsLeapMonth, and IsLeapYear.

Suggestions for Further Exploration

• If you need to format currency for countries supporting the Euro, check out: MSDN/Visual Studio .NET/.NET Framework/Programming with the .NET Framework/Developing World-Ready Applications/Formatting Numeric Data for a Specific Culture.

• Use the DateTime.ToUniversalTime method, the DateTimeStyles enumeration, and the System.TimeZone class to work with different time zones.

• Check out the System.Globalization.DaylightTime class for managing daylight saving time.

• The .NET Framework uses the Unicode Transformation Format with 16-bit encoding (Unicode UTF-16) to represent characters. Unicode is the universal standard for encoding characters and text. For more information, check out www.unicode.org.

• If you need to work with Unicode surrogate pairs and combining characters to represent characters from other languages, try the StringInfo class.