11.3 Data Formatting

Programmers working with DBTools.h++ have several classes available for datatype normalization. (See Chapter 6). These classes provide data structures to hold complex types, yet allow them to be treated like simple types. These classes include:

RWDate from the Tools.h++ library;
RWDBDateTime and RWDecimalPortable from the DBTools.h++ library.

The data that these classes hold are locale sensitive; in other words, legal input and output of these types look different depending on the locale in effect. The issue here is input and output of the data from the point of view of the user of an application. DBTools.h++ automatically formats the data when sending to and retrieving from a database. The application programmer must be concerned only with the raw form of the data as it comes into the program or goes out to a program user.

The three classes all have techniques associated with them to allow input and output from various locales. The following section outlines the techniques used in each of the classes.

11.3.1 RWDBDateTime

The RWDBDateTime class encapsulates a point in time with a range from years down to microseconds. Its use is primarily associated with moving data in and out of DATETIME columns in databases.

Once an instance of RWDBDateTime is initialized, it can be used like any other datatype with DBTools.h++. DBTools.h++ takes care of any formatting or binding automatically in a locale neutral manner. The application programmer does not have to address localization issues in regards to getting this datatype in and out of the database.

However, getting a valid RWDBDateTime value from users in various locales is tricky. The example below demonstrates how to take a string representing a localized date time value and convert it into an RWDBDateTime instance. Following the conversion, the RWDBDateTime is streamed to standard output to demonstrate output in various locales.

void
demoI18NDateTimes ()
{
 RWCString germanDateString("04.05.98");
 RWCString germanTimeString("16:26:42");

  RWLocaleSnapshot germany("de");
  //If we're already in a german locale
  //the next line will work as an alternate
  //RWLocale& germany = *RWLocale::global();

  struct tm aTimeStruct;
  germany.stringToDate (germanDateString, &aTimeStruct);
  germany.stringToTime (germanTimeString, &aTimeStruct);

  RWDBDateTime aDateTime(&aTimeStruct);

  cout << "in France: "
       << aDateTime.asString('\0', RWZone::local(),
         RWLocaleSnapshot("fr"))
       << endl;
  cout << "in the US: "
       << aDateTime.asString('\0', RWZone::local(),
         RWLocaleSnapshot("en_US"))
       << endl;
}

The output for this example should look like this:

in France: 04.05.98 16:26:42.000
in the US: 05/04/98 16:26:42.000

DBTools.h++ does not include an operator<< for ostreams and instances of RWDBDateTime. The following example shows how to make an operator<< that outputs an RWDBDateTime correctly with whatever locale was imbued in the ostream.

ostream&
operator << (ostream& o, const RWDBDateTime& dt)
{
  const RWLocale& localeOfTheStream = RWLocale::of(o);
  return o << dt.asString ('\0', RWZone::local(),
         localeOfTheStream);
}

11.3.2 RWDate

RWDate is a class from Tools.h++ that can also be used as a database datatype. DBTools.h++ can handle any formatting issues without intervention when getting this type in and out of a database, as it can for RWDate. Of course, the trick again is getting localized information from a user to initialize an instance of RWDate. Tools.h++ gives several options.

First,there is a constructor that takes a reference to an istream and a reference to an RWLocale. This allows direct initialization of the RWDate instance from the istream.

A second technique is shown in the example below. A string initialized with a representation of a localized date is created and then converted to an RWDate with the assistance of an RWLocale reference.

void
demoI18NDate ()
{
  RWDate aDate ("26 Mai 1998", RWLocaleSnapshot("de"));

  cout << "in the US: "
       << aDate.asString("%d %b %Y", RWLocaleSnapshot("en_US"))
       << endl;
  cout << "in France: "
       << aDate.asString("%d %b %Y", RWLocaleSnapshot("fr"))
       << endl;
}

The output for this example should be:

in the US: 26 May 1998
in France: 26 mai 1998

11.3.3 RWDecimalPortable

RWDecimalPortable is used to hold monetary values. For this, it is more accurate than float or double. Float and double introduce errors in monetary values because binary is not entirely accurate for fractional base 10 values. RWDecimalPortable uses the less efficient but perfectly accurate ASCII method.

When an RWDecimalPortable instance is given to DBTools.h++ to be inserted into a table, DBTools.h++ handles any formatting required by the server automatically. You don't have to worry about that. However, you do need to get localized values into instances of RWDecimalPortable.

Unfortunately, there is no constructor for RWDecimalPortable that takes an RWLocale as a parameter. When an RWDecimalPortable is initialized from a string, it always assumes that the string is formatted in the style required by the current global locale.

void
demoI18NDecimal ()
{
  // this example is supposed to be French
  // these two lines make sure that's true
  RWLocaleSnapshot france("fr");
  const RWLocale* oldLocale = RWLocale::global(&france);

  RWCString frenchDecimalString("123.456,78");
  RWDecimalPortable x (frenchDecimalString);

  cout << "in France: " << x << endl;
  RWLocaleSnapshot USLocale ("en_us");
  USLocale.imbue (cout);
  cout << "in the US: " << x << endl;

  //restore previous locale
  RWLocale::global(oldLocale);
}

The output for this example should be:

in France: 123456,78
in the US: 123456.78

By itself, class RWDecimalPortable cannot produce output with embedded thousand separators. When used in conjunction with the Rogue Wave product Money.h++, it has that capability.

11.3.4 Formatting Raw Numbers

At times application programmers are faced with input from users in awkward formats. A simple formatting technique, such as using a thousand separator, adds greatly to the readability of data by people. Unfortunately, software rarely allows the use of thousand separators. This is probably because the tools for parsing such input have been unavailable, and programmers have not acutely felt a need to create them.

The class RWLocale from the Tools.h++ library provides a method for converting strings that represent numbers into the basic long or double datatypes. The strings can even contain the national equivalents of the thousand and decimal separators. The following example demonstrates the technique:

void
insertFrenchNumber (RWDBDatabase& aDB)
{
  RWLocaleSnapshot france("fr");
  //If we're already in a french locale - use this line instead
  //RWLocale& france= *RWLocale::global();

  RWCString aNumberAsAString("12.345,67");
  double aNumber(0.0);
  france.stringToNum(aNumberAsAString, &aNumber);

  RWDBInserter ins = aDB.table("t3").inserter();

  ins << aNumber;

  cout << ins.asString() << endl;
}

The output from this example should be an SQL insert statement like this:

INSERT INTO t3 VALUES ( 1.2345670000000e+04 )