Implements the RWLocale interface, and encapsulates the C++ Standard Library locale. More...

#include <rw/tools/ansilocale.h>

Inheritance diagram for RWAnsiLocale:

Public Types
typedef std::money_base::pattern	money_pattern

enum	part { none, space, symbol, sign, value }

Public Types inherited from RWLocale
enum	CurrSymbol { NONE, LOCAL, INTL }

Public Member Functions
	RWAnsiLocale (const RWAnsiLocale &)

	RWAnsiLocale ()

	RWAnsiLocale (const char *localeName)

	RWAnsiLocale (const std::locale &)

	RWAnsiLocale (RWAnsiLocale &&locale)

virtual	~RWAnsiLocale ()

virtual RWCString	asString (long val) const

virtual RWCString	asString (unsigned long val) const

virtual RWCString	asString (double val, int precision=6, bool showpoint=0) const

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

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

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

virtual const RWCString &	currency_symbol () const

virtual const RWCString &	decimal_point () const

virtual char	frac_digits () const

virtual const RWCString &	grouping () const

virtual const RWCString &	int_curr_symbol () const

virtual char	int_frac_digits () const

virtual money_pattern	int_neg_format () const

virtual money_pattern	int_pos_format () const

virtual const RWCString &	locale_name () const

virtual const RWCString &	mon_decimal_point () const

virtual const RWCString &	mon_grouping () const

virtual const RWCString &	mon_thousands_sep () const

virtual RWCString	moneyAsString (double value, RWAnsiLocale::CurrSymbol=LOCAL) const

virtual int	monthIndex (const RWCString &month) const

virtual char	n_cs_precedes () const

virtual char	n_sep_by_space () const

virtual char	n_sign_posn () const

virtual money_pattern	neg_format () const

virtual const RWCString &	negative_sign () const

RWAnsiLocale &	operator= (const RWAnsiLocale &)

RWAnsiLocale &	operator= (RWAnsiLocale &&locale)

virtual char	p_cs_precedes () const

virtual char	p_sep_by_space () const

virtual char	p_sign_posn () const

virtual money_pattern	pos_format () const

virtual const RWCString &	positive_sign () const

virtual std::locale *	std ()

virtual bool	stringToDate (const RWCString &date, struct tm *) const

virtual bool	stringToMoney (const RWCString &, double *, RWAnsiLocale::CurrSymbol=LOCAL) const

virtual bool	stringToNum (const RWCString &value, double *) const

virtual bool	stringToNum (const RWCString &value, long *) const

virtual bool	stringToNum (const RWCString &value, unsigned long *) const

virtual bool	stringToTime (const RWCString &time, struct tm *) const

void	swap (RWAnsiLocale &rhs)

virtual const RWCString &	thousands_sep () const

virtual int	weekdayIndex (const RWCString &day) const

Public Member Functions inherited from RWLocale
RWCString	asString (const struct tm tmbuf, const char format, const RWZone &zone=RWZone::local()) const

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

Additional Inherited Members
Static Public Member Functions inherited from RWLocale
static const RWLocale *	defaultLocale ()

static const RWLocale &	global ()

static const RWLocale *	global (const RWLocale *loc)

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

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

Detailed Description

RWAnsiLocale implements the RWLocale interface. It encapsulates the C++ Standard Library locale, std::locale and adds functionality for date and time conversions. The C++ Standard Library std::locale provides localized representations of dates, numbers, and currencies. RWAnsiLocale offers a simple interface to std::locale so you can avoid working directly with std::locale facets. Additionally, RWAnsiLocale provides flexible conversions of strings to dates and times. While the C++ Standard Library std::locale accepts dates and times only in formats defined by the C++ Standard Library function std::strftime(), RWAnsiLocale accepts multiple date and time formats.

There are three ways to use an RWAnsiLocale object:

By passing the object to functions that expect one, such as RWDateTime::asString().
By using the object to specify a global locale using the static member function RWLocale::global(). This locale is then used as the default argument to functions that use a locale.
By imbuing a stream with the object, so that when an RWDateTime is written to a stream using operator<<(), the appropriate formatting is used automatically.

For a description of the static members of the RWLocale interface that operate on objects of type RWAnsiLocale, see the RWLocale class description.

Note: For both RWAnsiLocale and std::locale, the default global locale is the locale defined in the C Standard Library file <locale.h>.

Synopsis: #include <rw/locale.h> // for RWLocale

RWAnsiLocale loc; // sets loc to the current global locale

RWAnsiLocale loc("") // sets loc to the default system locale

Persistence: None

Example

#include <rw/cstring.h>
#include <rw/locale.h>
#include <rw/tools/datetime.h>
#include <iostream>
#if defined(_WIN32)
   // french should be a valid French locale name on Windows
#  define FRENCH_LOCALE_NAME "french"
#elif defined(__HP_aCC)
#  define FRENCH_LOCALE_NAME "fr_FR.utf8"
#else
   // fr_FR should be a valid French locale name on most Unices
#  define FRENCH_LOCALE_NAME "fr_FR"
#endif
int main() {
  try {
    // Create an ansi locale object
    RWAnsiLocale frenchLoc(FRENCH_LOCALE_NAME);
    // Change global locale
    const RWLocale* previousLoc = RWLocale::global(&frenchLoc);
    // Print global locale name and the current time in a
    // locale specific format
    std::cout << RWLocale::global().locale_name() << ' '
              << RWDateTime::now().asString('c') << std::endl;
    // Restore the global locale
    RWLocale::global(previousLoc);
  }
  catch (...) {
    std::cout << "failed to create locale." << std::endl;
  }
  return 0;
}

Program output:

Actual output will depend on the time the example is run, and on the platform.

fr_FR 10 juillet 2009 21:24:29 GMT

Member Typedef Documentation

typedef std::money_base::pattern RWAnsiLocale::money_pattern

Typedef for a locale-specific rule for formatting monetary outputs.

Member Enumeration Documentation

enum RWAnsiLocale::part

Specifies syntactic elements used to indicate monetary formats, defined as follows:

Enumerator
none	No grouping separator
space	Use space for grouping separator
symbol	Currency symbol
sign	Sign of monetary value
value	The monetary value itself

Constructor & Destructor Documentation

RWAnsiLocale::RWAnsiLocale ( const RWAnsiLocale & )

Copy constructor.

RWAnsiLocale::RWAnsiLocale ( )

Constructs an RWAnsiLocale object with locale information extracted from the current C++ Standard Library global locale.

RWAnsiLocale::RWAnsiLocale ( const char * localeName )

Constructs an RWAnsiLocale object using the locale name localeName.

Valid values for localeName are NULL, "", "C", and any value that is accepted by std::locale.

If the value for localeName is NULL, the required locale information is extracted from the current C++ Standard Library global locale. Otherwise, localeName is used to construct a C++ Standard Library std::locale object to be queried for the necessary locale information.

Exceptions

std::runtime_error If the locale name localeName is not recognized by std::locale.

RWAnsiLocale::RWAnsiLocale ( const std::locale & )

Constructs an RWAnsiLocale object from a C++ Standard Library std::locale.

virtual RWAnsiLocale::~RWAnsiLocale ( )

virtual

Virtual destructor.

RWAnsiLocale::RWAnsiLocale ( RWAnsiLocale && locale )

Move constructor. The constructed instance takes ownership of the data owned by locale.

Condition:: This method is available only on platforms with rvalue reference support.

Member Function Documentation

virtual RWCString RWAnsiLocale::asString ( long val ) const

virtual

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

Implements RWLocale.

virtual RWCString RWAnsiLocale::asString ( unsigned long val ) const

virtual

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

Implements RWLocale.

virtual RWCString RWAnsiLocale::asString	(	double	val,
		int	precision = `6`,
		bool	showpoint = `0`
	)		const

virtual

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

Implements RWLocale.

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

virtual

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

Implements RWLocale.

virtual RWCString RWAnsiLocale::asString	(	const struct tm *	ptm,
		char	format,
		const RWZone &	zone = `RWZone::local()`
	)		const

virtual

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

See http://en.cppreference.com/w/cpp/chrono/c/strftime for a summary of std::strftime() formatting characters.

Implements RWLocale.

RWCString RWAnsiLocale::asString	(	const struct tm *	ptm,
		const char *	format,
		const RWZone &	zone = `RWZone::local()`
	)		const

Converts components of the tm struct object ptm 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 C++ Standard Library function std::strftime(). The members of ptm are assumed to be set consistently.

See http://en.cppreference.com/w/cpp/chrono/c/strftime for a summary of std::strftime() formatting characters.

virtual const RWCString& RWAnsiLocale::currency_symbol ( ) const

virtual

Returns a string to use as the local currency symbol.

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::decimal_point ( ) const

virtual

Returns a string to use as the numerical decimal separator.

Implements RWLocale.

virtual char RWAnsiLocale::frac_digits ( ) const

virtual

Returns the number of digits in the fractional part of the monetary representation.

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::grouping ( ) const

virtual

Returns a string identifying the number of digits to be included in a numerical group. A group is simply the digits between adjacent thousand's 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 0, the previous element is used repeatedly.
If the value is equal to CHAR_MAX, no further grouping is performed.

Example

"\3"       // Specifies the United States grouping system.
           // For example, "1,000,000". The "\00" acts as an
           // escape
"\3\2"     // Specifies the Nepalese grouping system.
           // For example, "1,00,00,000"

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::int_curr_symbol ( ) const

virtual

Returns an RWCString to use as the international currency symbol.

Implements RWLocale.

virtual char RWAnsiLocale::int_frac_digits ( ) const

virtual

Returns the number of digits in the fractional part of a particular national monetary representation.

Implements RWLocale.

virtual money_pattern RWAnsiLocale::int_neg_format ( ) const

virtual

Returns a money_pattern object specifying the location of the various syntactic elements in an international monetary representation. The restrictions listed for pos_format() and neg_format() apply.

virtual money_pattern RWAnsiLocale::int_pos_format ( ) const

virtual

Returns a money_pattern object specifying the location of the various syntactic elements in an international monetary representation. The restrictions listed for pos_format() and neg_format() apply.

virtual const RWCString& RWAnsiLocale::locale_name ( ) const

virtual

Returns the name of the encapsulated std::locale.

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::mon_decimal_point ( ) const

virtual

Returns a string to use as the monetary decimal separator.

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::mon_grouping ( ) const

virtual

Returns a string identifying the number of digits to be included in a numerical group. A group is simply the digits between adjacent thousand's 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 0, the previous element is used repeatedly.
If the value is equal to CHAR_MAX, no further grouping is performed.

See the example in the grouping() description.

Implements RWLocale.

virtual const RWCString& RWAnsiLocale::mon_thousands_sep ( ) const

virtual

Returns a string to use as the monetary thousands separator.

Implements RWLocale.

virtual RWCString RWAnsiLocale::moneyAsString	(	double	value,
		RWAnsiLocale::CurrSymbol	= `LOCAL`
	)		const

virtual

Returns a string containing the value parameter formatted according to monetary conventions for the locale. The value parameter is assumed to contain an integer representing the number of units of currency (for example, moneyAsString(1000., RWAnsiLocale::cs_local) in a US locale would yield "$10.00"). The CurrSymbol parameter determines which currency symbol should be applied if any – the local (for example, "$") or international (for example, "USD"), or none.

Implements RWLocale.

virtual int RWAnsiLocale::monthIndex ( const RWCString & month ) const

virtual

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

Implements RWLocale.

virtual char RWAnsiLocale::n_cs_precedes ( ) const

virtual

Gets the negative currency symbol location.

Implements RWLocale.

virtual char RWAnsiLocale::n_sep_by_space ( ) const

virtual

Gets the space separating the negative sign from its number, if any.

Implements RWLocale.

virtual char RWAnsiLocale::n_sign_posn ( ) const

virtual

Gets the negative sign position.

Implements RWLocale.

virtual money_pattern RWAnsiLocale::neg_format ( ) const

virtual

Returns a money_pattern object specifying the location of the various syntactic elements in a monetary representation. The enumeration values symbol, sign, and value appear exactly once in this pattern, with the remaining location taken by either none or space. none never occupies the first position in the money_pattern and space never occupies the first or last position. Beyond these restrictions, elements may appear in any order.

virtual const RWCString& RWAnsiLocale::negative_sign ( ) const

virtual

Returns a string to use as the negative sign for a monetary quantity.

Implements RWLocale.

RWAnsiLocale& RWAnsiLocale::operator= ( const RWAnsiLocale & )

Assignment operator.

RWAnsiLocale& RWAnsiLocale::operator= ( RWAnsiLocale && locale )

Move assignment. Self takes ownership of the data owned by locale.

Condition:: This method is available only on platforms with rvalue reference support.

virtual char RWAnsiLocale::p_cs_precedes ( ) const

virtual

Gets the positive currency symbol location.

Implements RWLocale.

virtual char RWAnsiLocale::p_sep_by_space ( ) const

virtual

Gets the space separating the positive sign from its number, if any.

Implements RWLocale.

virtual char RWAnsiLocale::p_sign_posn ( ) const

virtual

Gets the positive sign position.

Implements RWLocale.

virtual money_pattern RWAnsiLocale::pos_format ( ) const

virtual

Returns a money_pattern object specifying the location of the various syntactic elements in a monetary representation. The enumeration values symbol, sign, and value appear exactly once in this pattern, with the remaining location taken by either none or space. none never occupies the first position in the money_pattern and space never occupies the first or last position. Beyond these restrictions, elements may appear in any order.

virtual const RWCString& RWAnsiLocale::positive_sign ( ) const

virtual

Returns a string to use as the positive sign for a monetary quantity.

Implements RWLocale.

virtual std::locale* RWAnsiLocale::std ( )

virtual

Returns a pointer to the encapsulated std::locale.

virtual bool RWAnsiLocale::stringToDate	(	const RWCString &	date,
		struct tm *
	)		const

virtual

Interprets date as a date, and extracts the month, day, and year components to the tm parameter. Returns true for a valid date, false otherwise. If it returns false, the struct tm object is untouched; otherwise it sets the tm_mday, tm_mon, and tm_year members. The expected format for the date string is the one specified by the std::strftime() character x in the current locale.

An example of a valid string in en_US locale is 09/12/1990.

Implements RWLocale.

virtual bool RWAnsiLocale::stringToMoney	(	const RWCString &	,
		double *	,
		RWAnsiLocale::CurrSymbol	= `LOCAL`
	)		const

virtual

Interprets the RWCString parameter value 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* parameter value is untouched; otherwise it is set to the integral number of monetary units entered (for example, cents in a U.S. locale).

Implements RWLocale.

virtual bool RWAnsiLocale::stringToNum	(	const RWCString &	value,
		double *
	)		const

virtual

Interprets value as a floating point number, by reading to the first non-numeric or non-punctuation character, then converting. 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* parameter 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"
"1"              "  -02."          ".3"
"1234.56"        "1e10"            "+  19,876.2E+20"
"1234.56"        "1e10"            "+  19,876.2E+20"

Implements RWLocale.

virtual bool RWAnsiLocale::stringToNum	(	const RWCString &	value,
		long *
	)		const

virtual

Interprets value as an integer, by reading to the first non-numeric or non-punctuation character, then converting. 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* parameter 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"
"1"                "  -02."          "+  1,234"
"1234545"          "1,234,567"
"1234545"          "1,234,567"

Implements RWLocale.

virtual bool RWAnsiLocale::stringToNum	(	const RWCString &	value,
		unsigned long *
	)		const

virtual

Interprets value as an integer, by reading to the first non-numeric or non-punctuation character, then converting. 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* parameter is untouched. All valid numeric strings are accepted; all others are rejected.

Implements RWLocale.

virtual bool RWAnsiLocale::stringToTime	(	const RWCString &	time,
		struct tm *
	)		const

virtual

Interprets time as a time, with hours, minutes, and optional seconds. 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 object is untouched; otherwise it sets the tm_hour, tm_min, and tm_sec members. The expected format for the date string is the one specified by std::strftime() character X (capital X) in the current locale.

An example of a valid string in en_US locale is 10:30:05.

Implements RWLocale.

void RWAnsiLocale::swap ( RWAnsiLocale & rhs )

Swaps the data owned by self with the data owned by rhs.

virtual const RWCString& RWAnsiLocale::thousands_sep ( ) const

virtual

Returns a char to use as the numerical thousands separator.

Implements RWLocale.

virtual int RWAnsiLocale::weekdayIndex ( const RWCString & day ) const

virtual

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

Implements RWLocale.

SourcePro® API Reference Guide

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation