SourcePro® API Reference Guide

 
Loading...
Searching...
No Matches
RWLocale Class Referenceabstract

Defines an interface that formats the conversion of strings to and from dates and times. More...

#include <rw/locale.h>

Inheritance diagram for RWLocale:
RWAnsiLocale RWLocaleSnapshot

Public Types

enum  CurrSymbol { NONE , LOCAL , INTL }
 

Public Member Functions

virtual RWCString asString (const struct tm *tmbuf, char format, const RWZone &zone=RWZone::local()) const =0
 
RWCString asString (const struct tm *tmbuf, const char *format, const RWZone &zone=RWZone::local()) const
 
virtual RWCString asString (double f, int precision=6, bool showpoint=0) const =0
 
virtual RWCString asString (long double val, int precision=10, bool showpoint=0) const =0
 
virtual RWCString asString (long i) const =0
 
virtual RWCString asString (unsigned long i) const =0
 
const RWLocaleimbue (std::ios &stream) const
 
virtual const RWCStringlocale_name () const =0
 
virtual RWCString moneyAsString (double value, RWLocale::CurrSymbol sym=LOCAL) const =0
 
virtual int monthIndex (const RWCString &str) const =0
 
virtual bool stringToDate (const RWCString &str, struct tm *tmbuf) const =0
 
virtual bool stringToMoney (const RWCString &str, double *d, RWLocale::CurrSymbol=LOCAL) const =0
 
virtual bool stringToNum (const RWCString &str, double *fp) const =0
 
virtual bool stringToNum (const RWCString &str, long *ip) const =0
 
virtual bool stringToNum (const RWCString &str, unsigned long *ip) const =0
 
virtual bool stringToTime (const RWCString &str, struct tm *tmbuf) const =0
 
virtual int weekdayIndex (const RWCString &str) const =0
 

Static Public Member Functions

static const RWLocaledefaultLocale ()
 
static const RWLocaleglobal ()
 
static const RWLocaleglobal (const RWLocale *loc)
 
static const RWLocaleof (std::ios &stream)
 
static const RWLocaleunimbue (std::ios &stream)
 

Detailed Description

RWLocale 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 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(const 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 RWDateTime or RWDate is written to a stream using operator<<(), the appropriate formatting is automatically used.

The library provides two main implementations of RWLocale. These subclasses each allow more than one locale to be active at a time, and they also support conversion from strings to other types. They include:

  • Class RWAnsiLocale which encapsulates the C++ Standard Library locale, std::locale.
  • Class RWLocaleSnapshot which encapsulates the C Standard Library locale facility.
Synopsis
#include <rw/locale.h>
#include <locale.h>
(Abstract base class)
Persistence
None

Member Enumeration Documentation

◆ CurrSymbol

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).

Enumerator
NONE 

No currency symbol

LOCAL 

Local currency symbol

INTL 

International currency symbol

Member Function Documentation

◆ asString() [1/6]

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

Converts components of tmbuf to a string, according to the format character format. The meanings assigned to the format character are identical to those used in the C++ Standard Library function std::strftime(). The members of tmbuf should be set consistently.

The following table contains examples of formatting characters used by the C++ Standard Library function std::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]

Format character Meaning
%a Replaced by the locale's abbreviated weekday name [from tm::tm_wday]
%A Replaced by the locale's full weekday name [from tm::tm_wday]
%b Replaced by the locale's abbreviated month name
%B Replaced by the locale's full month name
%c Replaced by the locale's appropriate date and time representation. (See the Base Definitions volume of IEEE Std 1003 1-2001, <time.h>.)
%C Replaced by the year divided by 100 and truncated to an integer, as a decimal number [00,99]
%d Replaced by the day of the month as a decimal number [01,31]
%D Equivalent to %m/%d/%y
%e Replaced by the day of the month as a decimal number [1,31]; a single digit is preceded by a space
%F Equivalent to %Y-%m-%d (the ISO 8601:2000 standard date format)
%g Replaced by the last 2 digits of the week-based year (see below) as a decimal number [00,99]
%G Replaced by the week-based year (see below) as a decimal number (for example, 1977)
%h Equivalent to %b
%H Replaced by the hour (24-hour clock) as a decimal number [00,23]
%I Replaced by the hour (12-hour clock) as a decimal number [01,12]
%j Replaced by the day of the year as a decimal number [001,366]
%m Replaced by the month as a decimal number [01,12]
%M Replaced by the minute as a decimal number [00,59]
%n Replaced by a newline character
%p Replaced by the locale's equivalent of either a.m. or p.m.
%r Replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to %I:%M:%S %p
%R Replaced by the time in 24-hour notation (%H:%M)
%s The number of seconds since the Epoch 1970-01-01 00:00:00 UTC
%S Replaced by the second as a decimal number [00,60]. The range is up to 60 to allow for occasional leap seconds.
%t Replaced by a tab character
%T Replaced by the time (%H:%M:%S)
%u Replaced by the weekday as a decimal number [1,7], with 1 representing Monday
%U Replaced by the week number of the year as a decimal number [00,53] The first Sunday of January is the first day of week 1; days in the new year before this are in week 0
%V Replaced by the week number of the year (Monday as the first day of the week) as a decimal number [01,53]. If the week containing 1 January has four or more days in the new year, then it is considered week 1. Otherwise, it is the last week of the previous year, and the next week is week 1. Both January 4th and the first Thursday of January are always in week 1.
%w Replaced by the weekday as a decimal number [0,6], with 0 representing Sunday
%W Replaced by the week number of the year as a decimal number [00,53]. The first Monday of January is the first day of week 1; days in the new year before this are in week 0.
%x Replaced by the locale's appropriate date representation. (See the Base Definitions volume of IEEE Std 1003 1-2001, <time.h>.)
%X Replaced by the locale's appropriate time representation. (See the Base Definitions volume of IEEE Std 1003 1-2001, <time.h>.)
%y Replaced by the last two digits of the year as a decimal number [00,99]
%Y Replaced by the year as a decimal number (for example, 1997)
%z Replaced by the offset from UTC in the ISO 8601:2000 standard format (+hhmm or -hhmm), or by no characters if no time zone is determinable. For example, -0430 means 4 hours 30 minutes behind UTC (west of Greenwich).
%Z Replaced by the time zone name or abbreviation, or by no bytes if no time zone information exists
%% Replaced by %

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ asString() [2/6]

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

Converts components of tmbuf to a string, according to the format string format. 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 %%. Format specifiers are converted to a string representation using asString().

◆ asString() [3/6]

virtual RWCString RWLocale::asString ( double f,
int precision = 6,
bool showpoint = 0 ) const
pure virtual

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 appears regardless of the precision.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ asString() [4/6]

virtual RWCString RWLocale::asString ( long double val,
int precision = 10,
bool showpoint = 0 ) const
pure virtual

Converts the value of val to a string. The variable precision is the number of digits to place after the decimal separator. If showpoint is true, the decimal separator appears regardless of the precision.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ asString() [5/6]

virtual RWCString RWLocale::asString ( long i) const
pure virtual

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

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ asString() [6/6]

virtual RWCString RWLocale::asString ( unsigned long i) const
pure virtual

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

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ defaultLocale()

static const RWLocale * RWLocale::defaultLocale ( )
static

Returns a pointer to a new instance of RWLocaleSnapshot("C").

◆ global() [1/2]

static const RWLocale & RWLocale::global ( )
static

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

◆ global() [2/2]

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

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

◆ imbue()

const RWLocale * RWLocale::imbue ( std::ios & stream) const

Replaces the locale installed in stream with the current locale and returns the old locale.

◆ locale_name()

virtual const RWCString & RWLocale::locale_name ( ) const
pure virtual

Returns the name of the encapsulated locale.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ moneyAsString()

virtual RWCString RWLocale::moneyAsString ( double value,
RWLocale::CurrSymbol sym = LOCAL ) const
pure virtual

Returns a string containing the value argument formatted according to monetary conventions for the locale. The value argument should contain an integer representing the number of units of currency (for example, moneyAsString(1000., RWLocale::LOCAL) in a US locale would yield "$10.00"). The sym argument determines which currency symbol to use.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ monthIndex()

virtual int RWLocale::monthIndex ( const RWCString & str) const
pure virtual

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.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ of()

static const RWLocale & RWLocale::of ( std::ios & stream)
static

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

◆ stringToDate()

virtual bool RWLocale::stringToDate ( const RWCString & str,
struct tm * tmbuf ) const
pure virtual

Interprets the RWCString as a date, and extracts the month, day, and year components to tmbuf. It returns true for a valid date, otherwise false. If it returns false, then tmbuf is untouched; otherwise it sets the tm_mday, tm_mon, and tm_year members. The date entered is expected to be in the format indicated by the current locale (%x). If that is not the case, the algorithm attempts to detect the different parts of the date string.

Note
This function cannot reject all invalid date strings.

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

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

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ stringToMoney()

virtual bool RWLocale::stringToMoney ( const RWCString & str,
double * d,
RWLocale::CurrSymbol = LOCAL ) const
pure virtual

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, then 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).

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ stringToNum() [1/3]

virtual bool RWLocale::stringToNum ( const RWCString & str,
double * fp ) const
pure virtual

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, then 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"

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ stringToNum() [2/3]

virtual bool RWLocale::stringToNum ( const RWCString & str,
long * ip ) const
pure virtual

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, then 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"

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ stringToNum() [3/3]

virtual bool RWLocale::stringToNum ( const RWCString & str,
unsigned long * ip ) const
pure virtual

Interprets the RWCString 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, then the long* argument is untouched. All valid numeric strings are accepted; all others are rejected.

Note
If you are using the C locale (likely the default for English-speaking programmers), you must omit commas as thousands separators because these numbers may be rejected. This is true even in a locale where English is the dominant language.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ stringToTime()

virtual bool RWLocale::stringToTime ( const RWCString & str,
struct tm * tmbuf ) const
pure virtual

Interprets str as a time, with hour, minute, and optional second. The time string is expected to be formatted according to the locale's %X format specifier. If that is not the case, the algorithm attempts to detect the different parts of the time string. 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, then tmbuf is untouched; otherwise it sets the tm_hour, tm_min, and tm_sec members.

Note
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"

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

◆ unimbue()

static const RWLocale * RWLocale::unimbue ( std::ios & stream)
static

Removes the locale that was installed in stream by a previous call to RWLocale::imbue(). If no locale was previously installed, returns the result of RWLocale::global().

◆ weekdayIndex()

virtual int RWLocale::weekdayIndex ( const RWCString & str) const
pure virtual

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.

Implemented in RWAnsiLocale, and RWLocaleSnapshot.

Copyright © 2024 Rogue Wave Software, Inc., a Perforce company. All Rights Reserved.