7.5 RWLocale and RWZone

The Essential Tools Module solves these problems with the classes RWLocale and RWZone. If you have used RWDateTime, you have already used RWLocale, perhaps unknowingly. Every time you convert a date or time to or from a string, a default argument carries along an RWLocale reference. Unless you change it, this is a reference to a global instance of a class derived from RWLocale at program startup to provide the effect of a C locale.

To use RWLocale explicitly, you can construct your own instance and pass it in place of the default. Similarly, when you manipulate times, you can substitute your own instance for the default RWZone reference.

You can also install your own instance of RWLocale or RWZone as the global default. Many streams even allow you to install your RWLocale instance in the stream so that dates and times transferred on and off that stream are formatted or parsed accordingly, without any special arguments. This is called imbuing the stream, a process described in more detail in the next section.

In the following sections, let us look at some examples of how to localize various data using RWLocale and RWZone. Let us begin by constructing a date, today's date:

RWDateTime today = RWDateTime::now();

We can display it the usual way using ordinary C-locale conventions:

cout << today << endl;

But what if you're outside your home locale? Or perhaps you have set your environment variable LANG to fr, because you want French formatting. (Despite the existing standard for locale names, many vendors provide variant naming schemes. Check your vendor's documentation for details.) To display the date in your preferred format, construct an RWLocaleSnapshot object:

RWLocaleSnapshot here ("");

This has the effect of creating an RWLocaleShapshot object which is constructed based on the information contained in the environment variables LC_* and LANG.

Classes RWLocaleSnapshot and RWAnsiLocale are two implementations of the interface defined by RWLocale. RWLocaleSnapshot extracts the information it needs from the global environment during construction with the help of such Standard C Library functions as strftime() and localeconv(). RWAnsiLocale wraps the C++ Standard Library std::locale, and can take advantage of the locales that are shipped with that implementation.

In discussion of the following examples, RWLocaleSnapshot and RWAnsiLocale are interchangeable.

The most straightforward way to use RWLocaleSnapshot is to pass it directly to the RWDateTime member function asString(), as follows. The first argument of the function asString() is a character, which may be any of the format options supported by the Standard C Library function strftime().

cout << today.asString('x', here) << endl;

There is, however, a more convenient way. You can install here as the global default locale so the insertion operator will use it:

RWLocale::global(&here); cout << today << endl;

There are three ways to use an RWAnsiLocale object:

• By passing the object to functions that expect one, such as RWDateTime::asString().

• By using the object to specify a global locale using the static member function RWLocale::global(). This locale is then used as the default argument to functions that use a locale.

• By imbuing a stream with the object, so that when an RWDateTime is written to a stream using operator <<(), the appropriate formatting is used automatically.

See the definition of x in the Reference Guide entry for RWLocale.

Would you like to read in a German date string? Again, the straightforward way is to call everything explicitly:

RWCString str; cout << "enter a date in German: " << flush; str.readLine(cin); today = RWDateTime (str, RWDateTime::setDate, german_locale); if (today.isValid()) cout << today << endl;

---

On your operating system, the name of the German locale may be different.

---

The interface defined by RWLocale handles more than dates. It can also convert times, numbers, and monetary values to and from strings. Each has its complications. Time conversions are complicated by the need to identify the time zone of the person who entered the time string, or the person who will read it. The mishmash of Daylight Saving Time jurisdictions can magnify the difficulty. Numbers are somewhat messy to format because their insertion and extraction operators (<< and >>) are already defined by <iostream.h>. For money, the main problem is that there is no standard internal representation for monetary values. Fortunately, none of these problems are overwhelming with the Essential Tools Module.

Let us first consider the time zone problem. We can easily see that there is no simple relationship between time zones and locales. All of Switzerland shares a single time zone, including Daylight Saving Time (DST) rules, but it has four official languages: French, German, Italian, and Romansch. On the other hand, Hawaii and New York share a common language, but occupy time zones five hours apart — sometimes six hours apart, because Hawaii does not observe DST. Furthermore, time zone formulas have little to do with cultural formatting preferences. For these reasons, the Essential Tools Module uses a separate time zone class RWZone, rather than letting RWLocale incorporate time zone responsibilities.

In the Essential Tools Module, the class RWZone encapsulates knowledge about time zones. It is an abstract base class, with a public implementation in the class RWZoneSimple. RWZone provides two instances by default, one that encapsulates the rules returned by the operating system, and a second representing the rules for Universal Coordinated Time (UTC). RWZone also allows your application to specify a local zone which, by default, represents the operating system rules. Whenever you convert an absolute time to or from a string, as in the class RWDateTime, an instance of RWZone is involved. By default, the local time is assumed, but you can pass a reference to any RWZone instance.If your primary need is to represent times in the current zone, you will likely not need to use the RWZone class directly. If, however, your application deals with multiple time zones or a zone that is not the system default, you can explicitly instantiate an RWZone instance to represent a different time zone. The easiest way to do so is through the RWZoneSimple class.

The code works even though your flight crosses several time zones and arrives on a different day than it departed; even though, on the day of the return trip in the following year, France has already begun observing DST, but the U.S. has not. None of these details are visible in the example code above — they are handled silently and invisibly by RWDateTime and RWZone.

All this is easy for places that follow the Essential Tools Module built-in DST rules for North America, Western Europe, and "no DST". But what about places that follow other rules, such as Argentina, where spring begins in September and summer ends in March? RWZoneSimple is table-driven; if the rule is simple enough, you can construct your own table of type RWDaylightRule, and specify it as you construct an RWZoneSimple. For example, imagine that DST begins at 2 a.m. on the last Sunday in September, and ends the first Sunday in March. Two rules are required for the southern hemisphere because DST starts later in a calendar year (September) than it ends (March), so the additional rule sets its initial starting point.

For details on an RWDaylightRule instance, see the documentation for RWZoneSimple.

Then construct an RWZone object:

RWZoneSimple ciudadSud( RWZone::Atlantic, &sudAmerica );

Now you can use ciudadSud just like you used paris or newYork above.

But what about places where the DST rules are too complicated to describe with a simple table, such as Great Britain? There, DST begins on the morning after the third Saturday in April, unless that is Easter, in which case it begins the week prior! For such jurisdictions, you might best use standard time, properly labeled. If that just won't do, you can derive from RWZone and implement its interface for Britain alone. This strategy is much easier than trying to generalize a case to handle all possibilities including Britain, and it's smaller and faster besides.

As you can see, Daylight Saving Time rules are volatile, often reflecting geographical and political changes. In some cases, the hard-coded table-driven struct RWDaylightRule does not accurately reflect the locale installed on your machine. For these cases, RWZone::os() can create a new RWZone containing the daylight rule discovered from the underlying operating system. The onus of correctness for this DST rule is on the operating system itself.

In cases where you want more explicit control of the DST rule for the intended RWZoneSimple, you can build a DST rule with arbitrary begin and end times, and provide it as a parameter to RWZoneSimple.

The last time problem we will discuss here is that there is no standard way to discover what DST rules are in force for any particular place. In this the Standard C Library is no help; you must get the information you need from the local environment your application is running on, perhaps by asking the user.

One example of this problem is that the local wall clock time RWZone instance is constructed to use North American DST rules, if DST is observed at all. If the user is not in North America, the default local time zone probably performs DST conversions wrong, and you must replace it. If you are a user in Paris, for example, you could solve this problem as follows:

RWZone::local(new RWZoneSimple(RWZone::Europe, RWZone::WeEu));

If you look closely into <rw/locale.h>, you will find that RWDateTime is never mentioned. Instead, RWLocale uses the Standard C Library type struct tm. RWDateTime provides conversions to this type, and you may prefer using it directly rather than using RWDateTime::asString(). For example, suppose you must write out a time string containing only hours and minutes, such as 12:33. The standard formats defined for strftime() and implemented by RWLocale do not include that option, but you can work around it. Here's one way:

RWDateTime now = RWDateTime::now(); cout << now.hour() << ":" << now.minute() << endl;

Without using various manipulators, this code might produce a string like 9:5. Here is another option:

RWDateTime now = RWDateTime::now(); cout << now.asString('H') << ":" << now.asString('M') << endl;

This produces 09:05.

In each of the previous examples, now is disassembled into component parts twice, once to extract the hour and once to extract the minute. This is an expensive operation. If you expect to work often with the components of a time or date, you may be better off disassembling the time only once:

RWDateTime now = RWDateTime::now(); struct tm tmbuf; now.extract(&tmbuf); const RWLocale& here = RWLocale::global(); // the default // global locale cout << here.asString(&tmbuf, 'H') << ":" << here.asString(&tmbuf, 'M'); << endl;

RWLocale also provides you with an interface for conversions between strings and numbers, both integers and floating point values. RWLocaleSnapshot and RWAnsiLocale implement this interface. RWLocaleSnapshot provides the full range of capabilities defined by the Standard C Library type struct lconv, while RWAnsiLocale provides this functionality through the numerics facets as defined by the C++ Standard. The capabilities include using appropriate digit group separators, decimal "point", and currency notation. When converting from strings, both RWLocaleSnapshot and RWAnsiLocale allow and check the same digit group separators.

Unfortunately, stream operations of this class are clumsier than we might like, since the standard iostream library provides definitions for number insertion and extraction operators which cannot be overridden. Instead, we can use RWCString functions directly:

RWLocaleSnapshot french("fr"); double f = 1234567.89; long i = 987654; RWCString fs = french.asString(f, 2); RWCString is = french.asString(i); if (french.stringToNum(fs, &f) && french.stringToNum(is, &i)) // verify conversion cout << "C:\t" << f << "\t" << i << endl << "French:\t" << fs << "\t" << is << endl;

Since the French use periods for digit group separators, and commas to separate the integer from the fraction part of a number, this code might display as:

C: 1.234567e+07 987654 French: 1.234.567,89 987.654

You will notice that numbers with digit group separators are easier to read.

If you are using RWDecimalPortable to parse decimals, it is recommended that you first explicitly define a locale, rather than allowing RWLocale to provide a default locale. RWDecimalPortable's parsing behavior is locale-dependent, so may produce unexpected results. For example, the C locale does not use a comma as a thousands separator, and parsing would therefore recognize such a comma instead as a separator between groups of digits.

---

It is recommended that you explicitly define a locale when using RWDecimalPortable, as the default locale may produce unexpected results.

---

To ensure predictable and expected behavior, the program should explicitly specify the locale before using the RWDecimalPortable constructor, and input strings should be formatted according the numeric string facets for that locale.

Portability means simply that double is a standard type, unlike common 64-bit integer or BCD representations. Of course, you can perform financial calculations on such other representations, but because you can always convert between them and double, they are all supported. In the future, RWLocale may directly support some other common representations as well.

Copyright © Rogue Wave Software, Inc. All Rights Reserved.

The Rogue Wave name and logo, and SourcePro, are registered trademarks of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.