Rogue Wave web site:  Home Page  |  Main Documentation Page

rwsf::Locale Class Reference
[Core Date/Time Manipulation]

Abstract base class to format conversion of strings to and from dates and times. More...

#include <rwsf/core/Locale.h>

Inheritance diagram for rwsf::Locale:

List of all members.

Public Types
enum	CurrSymbol { NONE, LOCAL, INTL }
Public Member Functions
virtual const std::string &	locale_name () const =0
virtual const std::string &	decimal_point () const =0
virtual const std::string &	thousands_sep () const =0
virtual const std::string &	grouping () const =0
virtual const std::string &	int_curr_symbol () const =0
virtual const std::string &	currency_symbol () const =0
virtual const std::string &	mon_decimal_point () const =0
virtual const std::string &	mon_thousands_sep () const =0
virtual const std::string &	mon_grouping () const =0
virtual const std::string &	positive_sign () const =0
virtual const std::string &	negative_sign () const =0
virtual char	int_frac_digits () const =0
virtual char	frac_digits () const =0
virtual char	p_cs_precedes () const =0
virtual char	p_sep_by_space () const =0
virtual char	n_cs_precedes () const =0
virtual char	n_sep_by_space () const =0
virtual char	p_sign_posn () const =0
virtual char	n_sign_posn () const =0
virtual std::string	asString (long) const =0
virtual std::string	asString (unsigned long) const =0
virtual std::string	asString (double d, int digits=6, bool sep=false) const =0
virtual std::string	asString (const struct tm *, char format, const rwsf::TimeZone &=rwsf::TimeZone::local()) const =0
std::string	asString (const struct tm *, const char *format, const rwsf::TimeZone &=rwsf::TimeZone::local()) const
virtual std::string	moneyAsString (double amt, CurrSymbol=LOCAL) const =0
virtual bool	stringToNum (const std::string &str, double *num) const =0
virtual bool	stringToNum (const std::string &str, long *num) const =0
virtual bool	stringToNum (const std::string &str, unsigned long *num) const =0
virtual bool	stringToDate (const std::string &str, struct tm *date) const =0
virtual bool	stringToTime (const std::string &str, struct tm *time) const =0
virtual bool	stringToMoney (const std::string &str, double *amt, CurrSymbol=LOCAL) const =0
virtual int	monthIndex (const std::string &month) const =0
virtual int	weekdayIndex (const std::string &day) const =0
Static Public Member Functions
static const Locale &	global ()
static const Locale *	global (const Locale *loc)
static const Locale *	defaultLocale ()
static void	releaseCache ()

---

Detailed Description

rwsf::Locale is an abstract base class defining 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:

Because this 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:

• Pass the object to functions that expect one, such as rwsf::DateTime::asString().
• Specify a global locale using the static member function global(const Locale*); This locale is passed as the default parameter to functions that use a locale.
• "Imbue" a stream with the object, so that when an rwsf::DateTime is written to a stream using operator<<(), the appropriate formatting will automatically be 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.

---

Member Enumeration Documentation

enum rwsf::Locale::CurrSymbol

Specifies how to format currency, using either no symbol, a local symbol, or an international symbol.

Enumerator:

NONE	No currency symbol.
LOCAL	The local currency symbol (such as $).
INTL	The international currency symbol (such as USD).

---

Member Function Documentation

std::string rwsf::Locale::asString	(	const struct tm *	,
		const char *	format,
		const rwsf::TimeZone &	= rwsf::TimeZone::local()
	)			const

Converts components of the struct tm object to a std::string according to the format character format. Each format character in the format string must be preceded by %. Any characters not preceded by % are treated as ordinary characters that 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 std::strftime().

Note:

This function is not virtual in order to maintain link-compatibility with the previous version of the library.

virtual std::string rwsf::Locale::asString	(	const struct tm *	,
		char	format,
		const rwsf::TimeZone &	= rwsf::TimeZone::local()
	)			const [pure virtual]

Converts components of the struct tm object to a std::string, according to the format character format. The meanings assigned to the format character are identical to those used in the pre-1999 Standard C Library function std::strftime().

virtual std::string rwsf::Locale::asString	(	double	d,
		int	digits = 6,
		bool	sep = false
	)			const [pure virtual]

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

virtual std::string rwsf::Locale::asString

(

unsigned

long

)

const [pure virtual]

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

virtual std::string rwsf::Locale::asString

(

long

)

const [pure virtual]

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

virtual const std::string& rwsf::Locale::currency_symbol

(

)

const [pure virtual]

Returns the string to use as the currency symbol for this locale.

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::decimal_point

(

)

const [pure virtual]

Returns the string to use as the numerical decimal separator.

Implemented in rwsf::LocaleSnapshot.

static const Locale* rwsf::Locale::defaultLocale

(

)

[static]

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

virtual char rwsf::Locale::frac_digits

(

)

const [pure virtual]

Returns the number of local fractional digits.

Implemented in rwsf::LocaleSnapshot.

static const Locale* rwsf::Locale::global

(

const Locale *

loc

)

[static]

Sets the global default locale object to loc, returning the previous locale 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& rwsf::Locale::global

(

)

[static]

Returns a reference to the present global default locale.

virtual const std::string& rwsf::Locale::grouping

(

)

const [pure virtual]

Returns the string identifying the number of digits to be included in a numerical group. A group is simply the digits between adjacent thousands separators. Each character of the string is an integer that specifies the number of digits in a group, starting with the right-most group.

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::int_curr_symbol

(

)

const [pure virtual]

Returns the string to use as the international currency symbol.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::int_frac_digits

(

)

const [pure virtual]

Returns the number of international fractional digits.

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::locale_name

(

)

const [pure virtual]

Returns the name of the locale.

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::mon_decimal_point

(

)

const [pure virtual]

Returns the string to use as the monetary decimal separator.

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::mon_grouping

(

)

const [pure virtual]

Returns the string identifying the number of digits to be included in a numerical group. A group is simply the digits between adjacent thousands separators. Each character of the string is an integer that specifies the number of digits in a group, starting with the right-most group.

If the value is equal to CHAR_MAX, no further grouping is to be performed.

See Example under grouping().

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::mon_thousands_sep

(

)

const [pure virtual]

Returns the string to use as the monetary thousands separator.

Implemented in rwsf::LocaleSnapshot.

virtual std::string rwsf::Locale::moneyAsString	(	double	amt,
		CurrSymbol	= LOCAL
	)			const [pure virtual]

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

virtual int rwsf::Locale::monthIndex

(

const std::string &

month

)

const [pure virtual]

Interprets the std::string parameter month 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 char rwsf::Locale::n_cs_precedes

(

)

const [pure virtual]

Returns 1 if the return from currency_symbol() precedes a negative value, or 0 if it succeeds a negative value.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::n_sep_by_space

(

)

const [pure virtual]

Returns 1 if the return from currency_symbol() must be separated by a space from a negative value, or 0 if no space is required.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::n_sign_posn

(

)

const [pure virtual]

Returns one of the following values, depending on the local currency system's requirements (for negative quantities):

• 0 Parentheses surround both the quantity and the return from currency_symbol().
• 1 The string returned by negative_sign() precedes both the quantity and the return from currency_symbol().
• 2 The string returned by negative_sign() succeeds both the quantity and the return from currency_symbol().
• 3 The string returned by negative_sign() immediately precedes the return from currency_symbol().
• 4 The string returned by negative_sign() immediately succeeds the return from currency_symbol().

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::negative_sign

(

)

const [pure virtual]

Returns the string to use as the negative sign.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::p_cs_precedes

(

)

const [pure virtual]

Returns 1 if the return from currency_symbol() precedes a positive value, or 0 if it succeeds a positive value.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::p_sep_by_space

(

)

const [pure virtual]

Returns 1 if the return from currency_symbol() must be separated by a space from a positive value, or 0 if no space is required.

Implemented in rwsf::LocaleSnapshot.

virtual char rwsf::Locale::p_sign_posn

(

)

const [pure virtual]

Returns one of the following values, depending on the local currency system's requirements (for positive quantities):

• 0 Parentheses surround both the quantity and the return from currency_symbol().
• 1 The string returned by positive_sign() precedes both the quantity and the return from currency_symbol().
• 2 The string returned by positive_sign() succeeds both the quantity and the return from currency_symbol().
• 3 The string returned by positive_sign() immediately precedes the return from currency_symbol().
• 4 The string returned by positive_sign() immediately succeeds the return from currency_symbol().

Implemented in rwsf::LocaleSnapshot.

virtual const std::string& rwsf::Locale::positive_sign

(

)

const [pure virtual]

Returns the string to use as the positive sign.

Implemented in rwsf::LocaleSnapshot.

static void rwsf::Locale::releaseCache

(

)

[static]

Deletes the timezone and the locale.

virtual bool rwsf::Locale::stringToDate	(	const std::string &	str,
		struct tm *	date
	)			const [pure virtual]

Interprets the std::string parameter str as a date and extracts the year, month, and day into the struct tm* parameter date. Returns true for a valid date, false otherwise. If false, the date parameter 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 std::strftime().

Note:

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 rwsf::Locale::stringToMoney	(	const std::string &	str,
		double *	amt,
		CurrSymbol	= LOCAL
	)			const [pure virtual]

Interprets the std::string parameter str as a monetary value and stores the result in the double* parameter amt. 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 false, the parameter amt is untouched; otherwise it is set to the integral number of monetary units entered (For example, cents, in a U.S. locale).

virtual bool rwsf::Locale::stringToNum	(	const std::string &	str,
		unsigned long *	num
	)			const [pure virtual]

Interprets the std::string parameter str as an unsigned long integer and stores it in the unsigned long* parameter num. Spaces are allowed before and after the (optional) sign, and at the end. Digit group separators are allowed. Returns true for a valid number, false for an error. If false, num is untouched. All valid numeric strings are accepted; all others are rejected.

virtual bool rwsf::Locale::stringToNum	(	const std::string &	str,
		long *	num
	)			const [pure virtual]

Interprets the std::string parameter str as a signed long integer and stores that number in the long* parameter num. Spaces are allowed before and after the (optional) sign, and at the end. Digit group separators are allowed. Returns true for a valid number, false for an error. If false, num 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. "     "+ 1,234"
 "1234545"     "1,234,567"

virtual bool rwsf::Locale::stringToNum	(	const std::string &	str,
		double *	num
	)			const [pure virtual]

Interprets the std::string parameter str as a double and stores it in num. 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, num 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 rwsf::Locale::stringToTime	(	const std::string &	str,
		struct tm *	time
	)			const [pure virtual]

Interprets the std::string parameter str as a time, with hour, minute, and optional second and extracts the hour, minute, and second into the struct tm* parameter time. 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 false, the parameter time 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"

virtual const std::string& rwsf::Locale::thousands_sep

(

)

const [pure virtual]

Returns the string to use as the numerical thousands separator.

Implemented in rwsf::LocaleSnapshot.

virtual int rwsf::Locale::weekdayIndex

(

const std::string &

day

)

const [pure virtual]

Interprets the std::string parameter day as a full or abbreviated weekday name, returning values 1 through 7 to represent (respectively) Monday through Sunday, or 0 for an error.