rwsf::Locale

• Local Index
• Header File
• Description
• Enumeration
• Public Member Functions
• Static Public Member Functions

Members

asString() CurrSymbol defaultLocale()

global() moneyAsString() monthIndex()

releaseCache() stringToDate() stringToMoney()

stringToNum() stringToTime() weekdayIndex()

#include <rwsf/core/Locale.h>

rwsf::Locale is an abstract base class. It defines an interface that formats the conversion of strings to and from dates and times. It formats dates (including day and month names), times, currency, and numbers (including digit grouping).

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 rwsf::Locale should act.

There are three ways to use an rwsf::Locale object:

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

• By specifying a "global" locale using the static member function rwsf::Locale::global(rwsf::Locale*). 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 rwsf::DateTime or rwsf::Date is written to a stream using operator<<(), the appropriate formatting will be automatically used.

The library provides rwsf::LocaleSnapshot, a subclass and implementation of rwsf::Locale. This subclass allows more than one locale to be active at a time, and also supports conversion from strings to other types.

enum 
CurrSymbol { NONE, LOCAL, INTL };

Controls how to format currency, specifying whether to use no currency symbol, the local currency symbol (such as $), or the international currency symbol (such as USD).

virtual std::string
asString(long) const = 0;
virtual std::string
asString(unsigned long) const = 0;

Converts the number to a string (For example, "3,456").

virtual std::string
asString(double, int = 6,
     bool = 0) const = 0;

Converts the double to a string. The int is the number of digits to place after the decimal separator. If bool is true, the decimal separator appears regardless of the setting of int. The default is false.

virtual std::string 
asString(const struct tm*, char, 
     const rwsf::TimeZone& = rwsf::TimeZone::
     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 pre-1999 Standard C Library function strftime(). The members of struct tm should be set consistently. See Table 3 for a summary of strftime() formatting characters.

std::string
asString(const struct tm*, const char*, 
     const rwsf::TimeZone& = rwsf::TimeZone::
     local()) 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 pre-1999 Standard C Library function strftime(). The members of struct tm should be set consistently. See Table 3 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.

virtual std::string 
moneyAsString(double, CurrSymbol = LOCAL) const = 0;
virtual std::string 
moneyAsString(double, Locale::CurrSymbol = LOCAL) const = 0;

Returns a string containing the double argument formatted according to monetary conventions for the locale. The double argument should contain an integer representing the number of units of currency (for example, moneyAsString(1000., rwsf::Locale::LOCAL) in a US locale would yield "$10.00"). The CurrSymbol argument determines whether to apply the local currency symbol.

virtual int
monthIndex(const std::string&) 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. Ignores leading white space.

virtual bool
stringToDate(const std::string&, struct tm*) const = 0;

Interprets the std::string 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 pre-1999 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 bool 
stringToMoney(const std::string&, double*,
     CurrSymbol=LOCAL) const = 0;

Interprets the std::string 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 (For example, cents, in a U.S. locale).

virtual bool
stringToNum(const std::string&, double* fp) const = 0;

Interprets the std::string 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 bool
stringToNum(const std::string&, long* ip) const = 0;

Interprets the std::string 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"

virtual bool 
stringToNum  (const std::string&, unsigned long*) const = 0;

Interprets the std::string argument as an integer. Allows spaces before and after the (optional) sign, and at the end. Allows digit group separators. 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.

---

NOTE -- If you are using the C locale, you must omit commas as thousands separators. Because the default locale is likely to be C for many English-speaking programmers, numbers with commas separating the thousands may be rejected. This is true even in a locale where English is the dominant language.

---

Table 3 contains examples of formatting characters used by the pre-1999 version of strftime(). For any format that does not use all members of the struct tm, only those members that are actually used are noted [in brackets]

Table 3: Formatting characters used by pre-1999 strftime()

Format character	Meaning	Example
a	Abbreviated weekday name [from tm::tm_wday]	Sun
A	Full weekday name [from tm::tm_wday]	Sunday
b	Abbreviated month name	Feb
B	Full month name	February
c	Date and time [may use all members]	Feb 29 14:34:56 1984
d	Day of the month	29
H	Hour of the 24-hour day	14
I	Hour of the 12-hour day	02
j	Day of the year, from 001 [from tm::tm_yday]	60
m	Month of the year, from 01	02
M	Minutes after the hour	34
p	AM/PM indicator, if any	AM
S	Seconds after the minute	56
U	Sunday week of the year, from 00 [from tm::tm_yday and tm::tm_wday]
w	Day of the week, with 0 for Sunday	0
W	Monday week of the year, from 00 [from tm::tm_yday and tm::tm_wday]
x	Date [uses tm::tm_yday in some locales]	Feb 29 1984
X	Time	14:34:56
y	Year of the century, from 00 (deprecated)	84
Y	Year	1984
Z	Time zone name [from tm::tm_isdst]	PST or PDT

virtual bool
stringToTime(const std::string&, struct tm*) const = 0;

Interprets the std::string 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
monthIndex(const std::string&) 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.

virtual int
weekdayIndex(const std::string&) 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 Locale*
defaultLocale();

Returns a pointer to a new instance of rwsf::LocaleSnapshot("C").

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

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

static const Locale&
global();

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

static void 
releaseCache();

Deletes the timezone and the locale.

©2004-2007 Copyright Quovadx, Inc. All Rights Reserved.
Quovadx and Rogue Wave are registered trademarks and HydraSDO is a trademark of Quovadx, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.