Supporting Custom C++ Types

Traits, TypeConversion<T>, & Generalized Support for New Types

Adding support for new types in the manner just described is effective, but it requires you to have significant knowledge of the relevant library internals. After studying code that used the method in Listing Four, I realized that the implementation technique could be generalized. I therefore made several enhancements to the SOCI library to make defining new types simpler for library users. The key to the enhancements is a traits class called TypeConversion.

Defined in terms of its structure, a traits class is simply a class template, which contains only typedefs and static functions, and has no modifiable state or virtuals (see C++ Coding Standards by Herb Sutter and Andrei Alexandrescu, Addison-Wesley, 2004).

Nathan Meyers, who first introduced the traits concept, defines a traits class as: "A class used in place of template parameters. As a class, it aggregates useful types and constants; as a template, it provides an avenue for that 'extra level of indirection' that solves all software problems" (www.cantrip.org/traits.html).

Andrei Alexandrescu has written that traits are intended to "consolidate pieces of code that, depending upon a type...sport slight variations in terms of structure and/or behavior. To achieve this end, traits rely on explicit template specialization" (erdani.org/publications/traits.html).

There are three required class members for a valid TypeConversion trait class specialization:

• The base_type typedef, defining the base type.
• The from() static member function, converting from the base type.
• The to() static member function, converting to the base type.

Listing Five shows the relevant changes to the SOCI framework.

class StandardIntoType : public IntoTypeBase
{
public:
    StandardIntoType(void *data, eExchangeType type);
    virtual ~StandardIntoType();

private:
    virtual void define(Statement &st, int &position);
    virtual void preFetch();
    virtual void postFetch(bool gotData, bool calledFromFetch);
    virtual void cleanUp();

    // conversion hook (from base type to arbitrary user type)
    virtual void convertFrom() {}

    void *data_;
    eExchangeType type_;
    StandardIntoTypeBackEnd *backEnd_;
};

class StandardUseType : public UseTypeBase
{
public:
    StandardUseType(void *data, eExchangeType type,
        std::string const &name = std::string());

    virtual ~StandardUseType();
    virtual void bind(Statement &st, int &position);

private:
    virtual void preUse();
    virtual void postUse(bool gotData);
    virtual void cleanUp();

    // conversion hooks (from arbitrary user type to base type)
    virtual void convertTo() {}
    virtual void convertFrom() {}

    void *data_;
    eExchangeType type_;
    std::string name_;

    details::StandardUseTypeBackEnd *backEnd_;
};

struct BaseValueHolder
{
    typename TypeConversion<T>::base_type val_;
};

// Automatically create an IntoType from a TypeConversion
template <typename T> class IntoType
    : private BaseValueHolder<T>,
      public IntoType<typename TypeConversion<T>::base_type>
{
public:
    typedef typename TypeConversion<T>::base_type BASE_TYPE;

    IntoType(T &value)
        : IntoType<BASE_TYPE>(BaseValueHolder<T>::val_),
          value_(value) {}

private:
    void convertFrom()
    {
        value_ = TypeConversion<T>::from(BaseValueHolder<T>::val_);
    }

    T &value_;
};

// Automatically create a UseType from a TypeConversion
template <typename T>
class UseType
    : private details::BaseValueHolder<T>,
      public UseType<typename TypeConversion<T>::base_type>
{
public:
    typedef typename TypeConversion<T>::base_type BASE_TYPE;

    UseType(T &value)
        : UseType<BASE_TYPE>(BaseValueHolder<T>::val_),
          value_(value) {}

private:
    void convertFrom()
    {
        value_ = TypeConversion<T>::from(BaseValueHolder<T>::val_);
    }
    void convertTo()
    {
        details::BaseValueHolder<T>::val_ = 
		TypeConversion<T>::to(value_);
    }

    T &value_;
};

The first step to add support for TypeConversion within the framework was to use the Template Method pattern (www.ddj.com/dept/cpp/184401436) by adding private virtual functions convertFrom() and convertTo() to classes StandardIntoType and StandardUseType. These new member functions are called from StandardUseType::preUse(),StandardUseType::post Use(), and StandardIntoType::postFetch().

I used the Template Method pattern here to isolate the code, which is unique to UseType and IntoType subclasses inside the convertFrom() and convertTo() private member functions. This simplifies the implementation of subclasses because they no longer need to include calls to their corresponding base class methods.

The next step was to partially specialize classes IntoType and UseType so that they inherit from IntoType<TypeConversion<T>::base_type> and UseType<TypeConversion<T>:: base_type>, respectively. These new classes also override convertTo() and convertFrom() and call TypeConversion <T>::to() and TypeConversion<T>::from().

An additional implementation detail is that these new IntoType and UseType specializations also inherit from the BaseValueHolder struct, which is used to hold the val_ member of type TypeConversion<T>::base_type. This ensures the correct order of initialization for the relevant member variables.

With the framework enhanced in this way, if you want to add SOCI support for boost::gregorian::date, you need only provide the appropriate TypeConversion specialization. IntoType<date> and UseType<date> are automatically generated by the compiler.

Compare this new method for adding custom types (Listing Six) to the old method (Listing Four). The obvious advantages are simplicity and separation of responsibilities. With the new method, you are not burdened with knowing the details of the SOCI implementation. The code that you need to provide to add support for a new type is isolated to the TypeConversion class template.

#include <iostream>
#include <soci.h>
#include <boost/date_time/gregorian/gregorian.hpp>

using boost::gregorian::months_of_year;
using boost::gregorian::date;

namespace SOCI
{
template<> struct TypeConversion<date>
{
    typedef std::tm base_type;
    static date from(std::tm& t)
    {
        date d( t.tm_year + 1900, 
             static_cast<months_of_year>(t.tm_mon + 1), t.tm_mday );
        return d;
    }
    static std::tm to(date& d)
    {
        std::tm t;
        t.tm_isdst = -1;
        t.tm_year = d.year() - 1900;
        t.tm_mon = d.month() - 1;
        t.tm_mday = d.day();
        t.tm_hour = 0;
        t.tm_min = 0;
        t.tm_sec = 0;
        std::mktime(&t); 
        return t;
    }
};
};
#endif