HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Member Functions
rwsf::LocaleSnapshot Class Reference

Creates a snapshot of a locale by querying the program's environment to determine the formatting conventions in effect at the moment of instantiation. More...

#include <rwsf/core/LocaleSnapshot.h>

Inheritance diagram for rwsf::LocaleSnapshot:
rwsf::Locale

Public Member Functions

 LocaleSnapshot (const char *localeName=0)
 
virtual std::string asString (long) const
 
virtual std::string asString (unsigned long) const
 
virtual std::string asString (double f, int precision=6, bool showpoint=0) const
 
virtual std::string asString (const struct tm *tmbuf, char format, const rwsf::TimeZone &=rwsf::TimeZone::local()) const
 
virtual const std::string & currency_symbol () const
 
virtual const std::string & decimal_point () const
 
virtual char frac_digits () const
 
virtual const std::string & grouping () const
 
virtual const std::string & int_curr_symbol () const
 
virtual char int_frac_digits () const
 
virtual const std::string & locale_name () const
 
virtual const std::string & mon_decimal_point () const
 
virtual const std::string & mon_grouping () const
 
virtual const std::string & mon_thousands_sep () const
 
virtual std::string moneyAsString (double, CurrSymbol=LOCAL) const
 
virtual int monthIndex (const std::string &) const
 
virtual char n_cs_precedes () const
 
virtual char n_sep_by_space () const
 
virtual char n_sign_posn () const
 
virtual const std::string & negative_sign () const
 
virtual char p_cs_precedes () const
 
virtual char p_sep_by_space () const
 
virtual char p_sign_posn () const
 
virtual const std::string & positive_sign () const
 
virtual bool stringToDate (const std::string &, struct tm *) const
 
virtual bool stringToMoney (const std::string &, double *, CurrSymbol=LOCAL) const
 
virtual bool stringToNum (const std::string &, double *) const
 
virtual bool stringToNum (const std::string &, long *) const
 
virtual bool stringToNum (const std::string &, unsigned long *) const
 
virtual bool stringToTime (const std::string &, struct tm *) const
 
virtual const std::string & thousands_sep () const
 
virtual int weekdayIndex (const std::string &) const
 
- Public Member Functions inherited from rwsf::Locale
std::string asString (const struct tm *, const char *format, const rwsf::TimeZone &=rwsf::TimeZone::local()) const
 

Additional Inherited Members

- Public Types inherited from rwsf::Locale
enum  CurrSymbol { NONE, LOCAL, INTL }
 
- Static Public Member Functions inherited from rwsf::Locale
static const LocaledefaultLocale ()
 
static const Localeglobal ()
 
static const Localeglobal (const Locale *loc)
 
static void releaseCache ()
 

Detailed Description

The class rwsf::LocaleSnapshot implements the rwsf::Locale interface using Standard C Library facilities. To use it, the program creates an rwsf::LocaleSnapshot instance. The constructor of the instance queries the program's environment (using Standard C Library functions such as localeconv(), strftime(), and, if available, vendor specific library functions) to determine the formatting conventions in effect at the moment of instantiation. When done, the locale can then be switched and another instance of rwsf::LocaleSnapshot created.

By creating multiple instances of rwsf::LocaleSnapshot, your program can have more than one locale active at the same time, something that is difficult to do with the Standard C Library facilities.

Note
rwsf::LocaleSnapshot does not encapsulate character set, collation, or message information.

Class rwsf::LocaleSnapshot contains a set of public data members initialized by its constructor with information extracted from its execution environment.

For a description of the static members of the rwsf::Locale interface that operate on objects of type rwsf::LocaleSnapshot, see the rwsf::Locale class description.

For more information on using locales, see the chapter on internationalization in the Web Service Development Guide.

Constructor & Destructor Documentation

rwsf::LocaleSnapshot::LocaleSnapshot ( const char *  localeName = 0)

Constructs an rwsf::Locale object by extracting formats from the global locale environment. It uses the Standard C Library function setlocale() to set the named locale, and then restores the previous global locale after formats have been extracted. If localeName is 0, it uses the current locale. The most useful locale name is the empty string, "", which is a synonym for the user's chosen locale (usually specified by the environment variable LANG).

Member Function Documentation

virtual std::string rwsf::LocaleSnapshot::asString ( long  ) const
virtual

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

Implements rwsf::Locale.

virtual std::string rwsf::LocaleSnapshot::asString ( unsigned  long) const
virtual

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

Implements rwsf::Locale.

virtual std::string rwsf::LocaleSnapshot::asString ( double  d,
int  digits = 6,
bool  sep = 0 
) const
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.

Implements rwsf::Locale.

virtual std::string rwsf::LocaleSnapshot::asString ( const struct tm *  ,
char  format,
const rwsf::TimeZone = rwsf::TimeZone::local() 
) const
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().

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::currency_symbol ( ) const
virtual

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

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::decimal_point ( ) const
virtual

Returns a string to use as the numerical decimal separator.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::frac_digits ( ) const
virtual

Returns the number of local fractional digits.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::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 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 0, the previous element is used repeatedly for the remainder of the digits.
  • If the value is equal to CHAR_MAX, no further grouping is to be performed.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::int_curr_symbol ( ) const
virtual

Returns a string to use as the international currency symbol.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::int_frac_digits ( ) const
virtual

Returns the number of international fractional digits.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::locale_name ( ) const
virtual

Returns the name of the encapsulated std::locale.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::mon_decimal_point ( ) const
virtual

Returns a string to use as the monetary decimal separator.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::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 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 0, the previous element is used repeatedly for the remainder of the digits.
  • If the value is equal to CHAR_MAX, no further grouping is to be performed.

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::mon_thousands_sep ( ) const
virtual

Returns a string to use as the monetary thousands separator.

Implements rwsf::Locale.

virtual std::string rwsf::LocaleSnapshot::moneyAsString ( double  amt,
CurrSymbol  = LOCAL 
) const
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., rwsf::Locale::LOCAL) in a U.S. locale would yield "$10.00"). The CurrSymbol parameter determines whether to apply the local currency symbol.

Implements rwsf::Locale.

virtual int rwsf::LocaleSnapshot::monthIndex ( const std::string &  month) const
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.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::n_cs_precedes ( ) const
virtual

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

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::n_sep_by_space ( ) const
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.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::n_sign_posn ( ) const
virtual

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

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::negative_sign ( ) const
virtual

Returns the string to use as the negative sign.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::p_cs_precedes ( ) const
virtual

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

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::p_sep_by_space ( ) const
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.

Implements rwsf::Locale.

virtual char rwsf::LocaleSnapshot::p_sign_posn ( ) const
virtual

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

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::positive_sign ( ) const
virtual

Returns the string to use as the positive sign.

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToDate ( const std::string &  str,
struct tm *  date 
) const
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"

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToMoney ( const std::string &  str,
double *  amt,
CurrSymbol  = LOCAL 
) const
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).

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToNum ( const std::string &  str,
double *  num 
) const
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"

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToNum ( const std::string &  str,
long *  num 
) const
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"

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToNum ( const std::string &  str,
unsigned long *  num 
) const
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.

Implements rwsf::Locale.

virtual bool rwsf::LocaleSnapshot::stringToTime ( const std::string &  str,
struct tm *  time 
) const
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"

Implements rwsf::Locale.

virtual const std::string& rwsf::LocaleSnapshot::thousands_sep ( ) const
virtual

Returns a string to use as the numerical thousands separator.

Implements rwsf::Locale.

virtual int rwsf::LocaleSnapshot::weekdayIndex ( const std::string &  day) const
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.

Implements rwsf::Locale.

Copyright © 2019 Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is registered trademark of Rogue Wave Software, Inc. in the United States and other countries, and HydraExpress is a trademark of Rogue Wave Software. All other trademarks are the property of their respective owners.
Provide feedback to Rogue Wave about its documentation.