Chapter 36. String conversions

Index

Using x::value_string with custom classes
Convenience functions
#include <x/value_string.H>
#include <x/locale.H>

x::locale l;

std::string s;

std::wstring ws;

short n;

// ...

s=x::value_string<short>::toString(n, l);

// ...

n=x::value_string<short>::fromString(s.begin(), s.end(), l);

// ...

ws=x::value_string<short>::toWideString(n, l);

// ...

n=x::value_string<short>::fromWideString(ws.begin(), ws.end(), l);

The x::value_string defines the following functions:

std::string toString(value, locale)

toString() takes the instance of the template class parameter and converts it to a std::string using the locale given by the second parameter.

value fromString(string, locale)

fromString() is the opposite, taking a string parameter, and converting it to the value specified by the template class parameter.

toWideString() and fromWideString()

These functions are wide-character versions of toString() and fromString()

For all natural integer and floating types, x::value_string uses standard library functions to effect the conversion. The template parameter may also be a std::string, which results in a fromString() and toString() that are effectively no-ops. For a std::wstring, fromString() and toString() uses the locale object to implement conversion between narrow and wide characters. Similarly, if the template parameter is a std::wstring, which results in a fromWideString() and toWideString() are effective no-ops, and for a std::string the conversion gets implemented via the locale object.

Using x::value_string with custom classes

The x::value_string template class works with x::hms and x::ymd::interval, x::uriimpl, and x::uuid classes. To implement x::value_string for any class, define the stringable class member, and several member templates. This is done for the purpose of converting an object into some human readable form. Object serialization template API would be more appropriate for saving and storing objects where readability is not a concern.

#include <x/value_stringable.H>

// ...

class Widget {

public:

    static const x::stringable_t stringable=x::class_toboth;

    template<typename OutputIterator>
    OutputIterator toString(OutputIterator iter,
                            const x::const_locale &localeRef)
		const
    {
        //

        return iter;
    }
      

    template<typename InputIterator>
    static Widget fromString(InputIterator beg_iter,
                              InputIterator end_iter,
                              const const_locale &localeArg)
    {
        Widget w;

        //

        return w;
    }

    template<typename OutputIterator>
    OutputIterator toWideString(OutputIterator iter,
                                const x::const_locale &localeRef)
		const
    {
        //

        return iter;
    }
      

    template<typename InputIterator>
    static Widget fromWideString(InputIterator beg_iter,
                                 InputIterator end_iter,
                                 const const_locale &localeArg)
    {
        Widget w;

        //

        return w;
    }
};

// ...

Widget wInstance;
x::locale l;

std::string s=x::value_string<Winder>::toString(wInstance, l);

The stringable class defines toString() and fromString(); and/or toWideString() and fromWideString().

The static const stringable member, in the example above, must be set to one of the following values:

x::class_tostring

This class defines the toString() and fromString() template methods.

x::class_tostring_utf8

This class defines the toString() and fromString() template methods, that ignore their locale argument, and always use the UTF-8 codeset.

x::class_towstring

This class defines the toWideString() and fromWideString() template methods.

x::class_toboth

This class defines all four template methods.

The toString() and toWideString() const template methods take an output iterator and a locale object (which they may ignore, if it's irrelevant for this class), write the string (in toString()'s case) or the wide string (in toWideString()'s case) representation of the object into the output iterator, and returns the new iterator value. fromString() and fromWideString() must be a static methods that take a pair of iterators. The pair specifies the beginning and the end of a character or a wide character sequence. The third argument is a locale object. fromString() and fromWideString() convert the character sequence to a new object instance, and return it.

x::value_string's methods invoke the appropriate class methods, automatically converting between narrow and wide characters if the requested x::value_string method is not directly supported by the class.

fromString() and fromWideString() should throw an exception if they cannot parse the string. Furthermore, the beginning and ending iterator sequence should define the complete parsable sequence, and an exception should be thrown if the object gets converted without consuming the entire input sequence (however, the methods can allow this, if they want to).

Convenience functions

#include <x/tostring.H>

x::locale l;

class Widget;

// ...

Widget w;

// ...

std::string s=x::tostring(w, l);

std::string s=x::towstring(w, l);

x::tostring() and x::towstring() are convenience functions that invoke x::value_string<class>::toString() and x::value_string<class>::toWideString(). They are also overloaded for native character and wide character pointers, which become either effective no-ops, or a conversion call between narrow and wide characters, in the specified locale.