RWLocale

• Data Type and Member Function Indexes
• Synopsis
• Description
• Persistence
• Enumeration
• Public Member Functions
• Static Public Member Functions

Data Types

CurrSymbol

Member Functions
asString() defaultLocale() global() imbue() moneyAsString() monthIndex()	of() stringToDate() stringToMoney() stringToNum() stringToTime() weekdayIndex()

#include <locale.h>
#include <rw/locale.h>

(Abstract base class)

RWLocale is an abstract base class. It defines an interface for formatting dates (including day and month names), times, numbers (including digit grouping), and currency, to and from strings.

Note that because it is an abstract base class, there is no way to actually enforce these goals -- the description here is merely the model of how a class derived from RWLocale should act.

There are three ways to use an RWLocale object:

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

• By specifying a "global" locale using the static member function RWLocale::global(RWLocale*). This locale is passed as the default argument to functions that use a locale.

• By "imbuing" a stream with the object, so that when an RWDate or RWTime is written to a stream using operator<<(), the appropriate formatting will be used automatically.

Two implementations of RWLocale are provided with the library:

• Class RWLocaleSnapshot encapsulates the Standard C library locale facility, with two additional advantages: more than one locale can be active at the same time; and it supports conversions from strings to other types.

• There is also an internal class that mimics RWLocaleSnapshot("C"). If your compiler does not have built-in support for locales, one is constructed automatically at program startup to be used as the default value of RWLocale::global(). If your compiler does support locales, RWLocale::global() returns a const reference to an instance of RWLocaleSnapshot("C").

None

enum 
CurrSymbol { NONE, LOCAL, INTL };

Controls whether no currency symbol, the local currency symbol, or the international currency symbol should be used to format currency.

virtual RWCString
asString(long) const = 0;
virtual RWCString
asString(unsigned long) const = 0;

Converts the number to a string (e.g., "3,456").

virtual RWCString
asString(double f, int precision = 6,
RWBoolean showpoint = 0) const = 0;

Converts the double f to a string. The variable precision is the number of digits to place after the decimal separator. If showpoint is TRUE, the decimal separator will appear regardless of the precision.

virtual RWCString
asString(const struct tm* tmbuf,char format, 
const RWZone& zone=RWZone::local()) const = 0;

Converts components of the struct tm object to a string, according to the format character. The meanings assigned to the format character are identical to those used in the Standard C Library function strftime(). The members of struct tm are assumed to be set consistently. See Table 1 for a summary of strftime() formatting characters.

RWCString
asString(const struct tm* tmbuf,const char* format, 
         const RWZone& zone) const;

Converts components of the struct tm object to a string, according to the format string. Each format character in the format string must be preceded by %. Any characters not preceded by % are treated as ordinary characters which are returned unchanged. You may represent the special character % with "%%". The meanings assigned to the format character are identical to those used in the Standard C Library function strftime(). The members of struct tm are assumed to be set consistently. See Table 1 for a summary of strftime() formatting characters. This function is not virtual in order to maintain link-compatibility with the previous version of the library.

const RWLocale*
imbue(ios& stream) const;

Installs self in the stream argument, for later use by the operators << and >> (e.g. in RWDate or RWTime). The pointer may be retrieved from the stream with the static member RWLocale::of(). In this way a locale may be passed transparently through many levels of control to be available where needed, without intruding elsewhere.

virtual RWCString
moneyAsString(double value,enum CurrSymbol = LOCAL) 
              const = 0;

Returns a string containing the value argument formatted according to monetary conventions for the locale. The value argument is assumed to contain an integer representing the number of units of currency (e.g., moneyAsString(1000., RWLocale::LOCAL) in a US locale would yield "$10.00"). The CurrSymbol argument determines whether the local (e.g., "$") or international (e.g., "USD ") currency symbol is applied, or none.

virtual int
monthIndex(const RWCString&) const = 0;

Interprets its argument as a full or abbreviated month name, returning values 1 through 12 to represent (respectively) January through December, or 0 for an error. Leading white space is ignored.

virtual RWBoolean
stringToNum(const RWCString&, double* fp) const = 0;

Interprets the RWCString argument as a floating point number. Spaces are allowed before and after the (optional) sign, and at the end. Digit group separators are allowed in the integer portion. Returns TRUE for a valid number, FALSE for an error. If it returns FALSE, the double* argument is untouched. All valid numeric strings are accepted; all others are rejected. The following are examples of valid numeric strings in an English-speaking locale:

     "1"          " -02. "     ".3"
     "1234.56"    "1e10"       "+ 19,876.2E+20"

virtual RWBoolean
stringToNum(const RWCString&, long* ip) const = 0;

Interprets the RWCString argument as an integer. Spaces are allowed before and after the (optional) sign, and at the end. Digit group separators are allowed. Returns TRUE for a valid integer, FALSE for an error. If it returns FALSE, the long* argument is untouched. All valid numeric strings are accepted; all others are rejected. The following are examples of valid integral strings in an English-speaking locale:

     "1"           " -02. "     "+ 1,234"
     "1234545"     "1,234,567"

Note: If you are using the C locale, you must omit commas as thousands separators. The default locale is very likely to be C for many English-speaking programmers -- meaning that even in a locale where English is the dominant language, numbers with commas separating the thousands may be rejected.

In Table 1 below, examples are given (in parenthesis). For those formats that do not use all members of the struct tm, only those members that are actually used are noted [in brackets].

Table 1. Formatting characters used by strftime()

virtual RWBoolean
stringToDate(const RWCString&, struct tm*) const = 0;

Interprets the RWCString as a date, and extracts the month, day, and year components to the tm argument. It returns TRUE for a valid date, FALSE otherwise. If it returns FALSE, the struct tm argument is untouched; otherwise it sets the tm_mday, tm_mon, and tm_year members. If the date is entered as three numbers, the order expected is the same as that produced by strftime(). Note that this function cannot reject all invalid date strings.

The following are examples of valid date strings in an English-speaking locale:

     "Jan 9, 62"     "1/9/62"     "January 9 1962"
     "09Jan62"       "010962"

virtual RWBoolean
stringToMoney(const RWCString&, double*,
              RWLocale::CurrSymbol=LOCAL) const = 0;

Interprets the RWCString argument as a monetary value. The currency symbol, if any, is ignored. Negative values may be specified by the negation symbol or by enclosing parentheses. Digit group separators are optional; if present they are checked. Returns TRUE for a valid monetary value, FALSE for an error. If it returns FALSE, the double* argument is untouched; otherwise it is set to the integral number of monetary units entered (e.g. cents, in a U.S. locale).

virtual RWBoolean
stringToTime(const RWCString&, struct tm*) const = 0;

Interprets the RWCString argument as a time, with hour, minute, and optional second. If the hour is in the range [1..12], the local equivalent of "AM" or "PM" is allowed. Returns TRUE for a valid time string, FALSE for an error. If it returns FALSE, the tm argument is untouched; otherwise it sets the tm_hour, tm_min, and tm_sec members. Note that this function cannot reject all invalid time strings. The following are examples of valid time strings in an English-speaking locale:

     "1:10 AM"     "13:45:30"     "12.30.45pm"
     "PM 3:15"     "1430"

virtual int
weekdayIndex(const RWCString&) const = 0;

Interprets its argument as a full or abbreviated weekday name, returning values 1 through 7 to represent (respectively) Monday through Sunday, or 0 for an error.

static const RWLocale&
of(ios&);

Returns the locale installed in the stream argument by a previous call to RWLocale::imbue() or, if no locale was installed, the result from RWLocale::global().

static const RWLocale*
global(const RWLocale* loc);

Sets the global "default" locale object to loc, returning the old object. This object is used by RWDate and RWTime string conversion functions as a default locale. It is set initially to refer to an instance of a class that provides the functionality of RWLocaleSnapshot("C").

static const RWLocale&
global();

Returns a reference to the present global "default" locale.

const RWLocale*
defaultLocale();

Returns a pointer to a new instance of either RWLocaleSnapshot("C"); or another class that provides the same behavior for compilers that don't fully support Standard C locales.