HydraExpress™ C++ API Reference Guide

Product Documentation:
   HydraExpress C++
Documentation Home
List of all members | Public Types | Public Member Functions | Static Public Member Functions
rwsf::Locale Class Referenceabstract

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:
rwsf::LocaleSnapshot

Public Types

enum  CurrSymbol { NONE, LOCAL, INTL }
 

Public Member Functions

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 const std::string & currency_symbol () const =0
 
virtual const std::string & decimal_point () const =0
 
virtual char frac_digits () const =0
 
virtual const std::string & grouping () const =0
 
virtual const std::string & int_curr_symbol () const =0
 
virtual char int_frac_digits () const =0
 
virtual const std::string & locale_name () const =0
 
virtual const std::string & mon_decimal_point () const =0
 
virtual const std::string & mon_grouping () const =0
 
virtual const std::string & mon_thousands_sep () const =0
 
virtual std::string moneyAsString (double amt, CurrSymbol=LOCAL) const =0
 
virtual int monthIndex (const std::string &month) const =0
 
virtual char n_cs_precedes () const =0
 
virtual char n_sep_by_space () const =0
 
virtual char n_sign_posn () const =0
 
virtual const std::string & negative_sign () const =0
 
virtual char p_cs_precedes () const =0
 
virtual char p_sep_by_space () const =0
 
virtual char p_sign_posn () const =0
 
virtual const std::string & positive_sign () const =0
 
virtual bool stringToDate (const std::string &str, struct tm *date) const =0
 
virtual bool stringToMoney (const std::string &str, 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 stringToTime (const std::string &str, struct tm *time) const =0
 
virtual const std::string & thousands_sep () const =0
 
virtual int weekdayIndex (const std::string &day) const =0
 

Static Public Member Functions

static const LocaledefaultLocale ()
 
static const Localeglobal ()
 
static const Localeglobal (const Locale *loc)
 
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:

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

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

virtual std::string rwsf::Locale::asString ( long  ) const
pure virtual

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

Implemented in rwsf::LocaleSnapshot.

virtual std::string rwsf::Locale::asString ( unsigned  long) const
pure virtual

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

Implemented in rwsf::LocaleSnapshot.

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.

Implemented in rwsf::LocaleSnapshot.

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

Implemented in rwsf::LocaleSnapshot.

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 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 ( )
static

Returns a reference to the present global default locale.

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

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., rwsf::Locale::LOCAL) in a U.S. locale would yield "$10.00"). The CurrSymbol parameter determines whether to apply the local currency symbol.

Implemented in rwsf::LocaleSnapshot.

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.

Implemented in rwsf::LocaleSnapshot.

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

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

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"

Implemented in rwsf::LocaleSnapshot.

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

Implemented in rwsf::LocaleSnapshot.

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"

Implemented in rwsf::LocaleSnapshot.

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"

Implemented in rwsf::LocaleSnapshot.

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.

Implemented in rwsf::LocaleSnapshot.

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"

Implemented in rwsf::LocaleSnapshot.

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.

Implemented in rwsf::LocaleSnapshot.

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.