RWLocale(3C++) RWLocale(3C++)
NameRWLocale - Rogue Wave library class
Synopsis
#include <locale.h>
#include <rw/locale.h>
(Abstract base class)
DescriptionRWLocale 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. .in -5
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")..in -5
Persistence
None
Enumeration
enum
CurrSymbol { NONE, LOCAL, INTL };
Page 1
RWLocale(3C++) RWLocale(3C++)
Controls whether no currency symbol, the local currency symbol, or the
international currency symbol should be used to format currency.
Public Member Functions
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) 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 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 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 RWCString
moneyAsString(double value,enum CurrSymbol = LOCAL)
const = 0;
Page 2
RWLocale(3C++) RWLocale(3C++)
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"
Page 3
RWLocale(3C++) RWLocale(3C++)
"1234545" "1,234,567"
Table 1. Formatting characters used by strftime(). 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].
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]
Page 4
RWLocale(3C++) RWLocale(3C++)
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 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
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.
Page 5
RWLocale(3C++) RWLocale(3C++)
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 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).
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 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 Public Member Functions
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().
Page 6
RWLocale(3C++) RWLocale(3C++)
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.
Page 7
