RWAnsiLocale

Module:  Essential Tools Module   Group:  Internationalization Classes

RWAnsiLocaleRWLocale

• Local Index
• Synopsis
• Description
• Persistence
• Example
• Enumerations
• Public Typedefs
• Public Constructors
• Public Destructor
• Public Member Functions

Members

asString() currency_symbol() CurrSymbol decimal_point() frac_digits() grouping() imbue() int_curr_symbol() int_frac_digits() int_neg_format()

int_pos_format() locale_name() moneyAsString() monthIndex() mon_decimal_point() mon_grouping() mon_thousands_sep() negative_sign() neg_format() n_cs_precedes()

n_sep_by_space() n_sign_posn() part positive_sign() pos_format() p_cs_precedes() p_sep_by_space() p_sign_posn() RWAnsiLocale() RWDateOrder

std() stringToDate() stringToMoney() stringToNum() stringToTime() thousands_sep() weekdayIndex() ~

#include <rw/locale.h>          /* for RWLocale */
RWAnsiLocale loc;     // sets loc to the current global locale
RWAnsiLocale loc("")  // sets loc to the default system locale

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 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 locale accepts dates and times only in formats defined by the Standard C Library function 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 Standard C Library file <locale.h>.

---

None

#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

enum RWDateOrder {do_dmy, do_mdy, do_ydm, do_ymd };

Specifies ordering for the day, month and year elements of a date.

enum CurrSymbol { NONE, LOCAL, INTL };

Controls how to format currency, specifying whether to use no currency symbol, the local currency symbol, or the international currency symbol.

enum part   { none, space. symbol, sign, };

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

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

typedef std::money_base::pattern pattern;

RWAnsiLocale(const char* localeName = 0);

Constructs an RWAnsiLocale object using Standard C locale names. If localeName is 0, creates an RWAnsiLocale from the current C++ Standard Library 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).

RWAnsiLocale(const std::locale& loc)

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

RWAnsiLocale(const RWAnsiLocale& loc)

Copy constructor

virtual ~RWAnsiLocale();

Destructor

virtual RWCString
asString(long) const;
virtual RWCString
asString(unsigned long) const;

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

virtual RWCString
asString(double f, int precision = 6,
         bool showpoint = false) const;

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.

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

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.

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

Converts components of the struct tm object to a string, according to the format character. The meanings assigned to the format character are identical to those used in the Standard C Library function strftime(). The members of struct tm are assumed to be set consistently. See http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html for a summary of strftime() formatting characters.

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

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

For a list of formatting characters used by strftime(), see the POSIX standard at
http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html

virtual RWCString 
currency_symbol() const

Returns a string to use as the local currency symbol.

virtual char 
decimal_point() const

Returns a char to use as the numerical decimal separator.

---

NOTE -- If you are using the C locale, you must omit commas as thousands separators. Because the default locale is likely to be C for many English-speaking programmers, numbers with commas separating the thousands may be rejected. This is true even in a locale where English is the dominant language.

---

virtual char 
frac_digits() const

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

virtual RWCString 
grouping() const

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 for the remainder of the digits.

• If the value is equal to CHAR_MAX, no further grouping is to be 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"

Note: When coding for an ASCII system, you must consider the values assigned to an integer by ASII. For instance, the digit 3 represents an ASCII character code of 51, not the value of 3. So if you want to define a grouping as 3, the value will be "\003", not "3"

RWAnsiLocale
imbue(std::ios& stream);

Sets the stream's locale to the encapsulated std::locale. Returns an RWAnsiLocale encapsulating the old std::locale.

virtual RWCString 
int_curr_symbol() const

Returns an RWCString to use as the international currency symbol.

virtual char 
int_frac_digits() const

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

virtual pattern 
int_neg_format() const
virtual pattern 
int_pos_format() const

Returns a 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 RWCString 
locale_name() const

Returns the name of the encapsulated std::locale.

virtual char 
mon_decimal_point() const

Returns a char to use as the monetary decimal separator.

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

Returns a string containing the value argument formatted according to monetary conventions for the locale. The value argument 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 argument determines which currency symbol should be applied if any -- the local (for example, "$") or international (for example, "USD"), or none.

virtual RWCString 
mon_grouping() const

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 for the remainder of the digits.

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

See Example under grouping().

virtual int
monthIndex(const RWCString&) const = 0;

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.

virtual RWCString 
mon_thousands_sep() const

Returns a string to use as the monetary thousands separator.

virtual char 
n_cs_precedes() const        

Sets the negative currency symbol location.

virtual char 
n_sep_by_space() const        

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

virtual char 
n_sign_posn() const      

Sets the negative sign position.

virtual RWCString 
negative_sign() const

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

virtual pattern 
neg_format() const
virtual pattern 
pos_format() const

Returns a 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 pattern and space never occupies the first or last position. Beyond these restrictions, elements may appear in any order.

virtual char 
p_cs_precedes() const  

Sets the positive currency symbol location.

virtual char 
p_sep_by_space() const        

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

virtual char 
p_sign_posn() const        

Sets the positive sign position.

virtual RWCString 
positive_sign() const

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

virtual std::locale*
std()

Returns a pointer to the encapsulated std::locale.

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

Interprets the RWCString as a date, and extract the month, day, and year components to the tm argument. Returns true for a valid date, false otherwise. If it returns false, the struct tm argument 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 strftime() character x in the current locale.

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

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

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

virtual bool
stringToNum(const RWCString&, double* fp) const;

Interprets the RWCString argument 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* 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"

virtual bool
stringToNum(const RWCString&, long* ip) const;

Interprets the RWCString argument 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* 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"

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

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

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

Interprets the RWCString argument as a time, with hour, minute, and optional second. 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 argument 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 strftime() character X (capital X) in the current locale.

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

virtual char 
thousands_sep() const

Returns a char to use as the numerical thousands separator.

virtual int
weekdayIndex(const RWCString&) const = 0;

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.

© Copyright Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave and SourcePro are registered trademarks of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.
Contact Rogue Wave about documentation or support issues.