Title: Exploring Patterns 3 - The Adapter

char *strpbrk(char const *s1, char const *s2);

char const *
      strpbrk(char const *s1, char const *s2);
char *strpbrk(char * s1, char const * s2);

inline char *
strpbrk(char * s1, char const * s2)
{
  return const_cast<char *>
    (strpbrk(const_cast<char const *>
                              (s1), s2));
}

MyType & MyType::func()
{
  // functionality
  return *this;
}

MyType const & MyType::func() const
{
  // functionality
  return *this;
}

MyType & func()
{  
  return
    const_cast<MyType> 
    (const_cast<MyType const *>
    (this)->func());
}

The coming version of C will include support libraries for both float and long double as well as the already existing support for double. Leaving aside what some will consider an elegant method to avoid overloading in C (others will consider it an atrocious hack) the true names of the maths functions will identify their precision. For example sin() will take and return a double, fsin() will take and return a float and lsin() will take and return a long double. (By the way, if the introduction of these extra identifiers breaks your code, the problem is yours because ISO/IEC 9899:1990 7.13.4 reserved all the names of existing functions in math.h when prefixed with f or l).

The problem for C++ is that C's fancy footwork to allow the compiler to choose what it thinks you want when you write sin(0.12F) is far from how we would do it in C++. What we need is some adapter functions to take the C distinct names and create a C++ overloaded set of functions. So we will have:

double sin (double);  // implemented as in C
inline float sin (float angle)
{ return fsin(angle);}
inline long double sin(long double angle) 
{ return lsin(angle);}

In other words, if you need a set of overloaded functions that can be used in C you must first write them with distinct names (qualified as extern "C") and then add adapter functions to provide the overloading if you want to use them in C++.

As these adapter functions are straight forwarding functions (sometimes called wrappers) I cannot think of a good reason to not inline them.

As a general principle, when I want a function to be useable in both C and C++ I would give careful consideration to declaring and defining a C version with a distinct name and then using an adapter to provide an equivalent type-safe C++ version. I think that this would reduce surprises when naïve C programmers do not realise that the version of an overloaded function they are calling will have been name mangled in the object code. Please note, I said careful consideration not that this is the only correct way to do it.

Let me start with a very simple adapter (mainly because it includes a nasty gotcha pointed out to me by Michael Ball). Suppose I have a class that I want to use as a base class for a polymorphic hierarchy but the original author failed to provide any virtual functions. In particular it does not include a virtual destructor. A simple solution comes to mind:

class PolyBase: public Base
{
public:
  virtual ~PolyBase(){};
};

This is about the simplest class adapter that you can imagine. Of course, in practice, you will add quite a few virtual qualified forwarding functions (adapter functions) to provide polymorphism for existing functionality. Note that you haven't apparently added any data to PolyBase, so you might think that you could happily use this global/namespace function:

Base & func();

Which returns a Base object by reference. You might try this for example:

PolyBase & pb = func();

When the compiler declines to compile this on the basis that a Base is not a PolyBase you stop, think for a moment and come to the conclusion that while this is true a downcast will be OK because you have not added any data. So you amend your code to:

PolyBase & pb = static_cast<PolyBase>(PolyBase) func();

WRONG. The chances are very high that your program is now irredeemably broken. You did (almost certainly) add data when you derived PolyBase from Base. PolyBase will include a vftptr. Worse still, most implementers put this at the beginning of the class object data. Adding polymorphic behaviour to a class changes its data layout. Fixing this problem requires a bit more care. You might try writing an adapter function:

PolyBase pfunc()
{
  return PolyBase(func());
};

to construct a PolyBase object that can be returned by value (the copy constructor will be optimised away by any respectable compiler). Unfortunately that will not work as we need a constructor that takes a Base by reference (or value) (neither the default nor copy constructor will do). So we must add:

PolyBase(Base const & data): Base(data){}

to our class interface. That has a side affect in that it will suppress the default constructor which we must now make explicit:

PolyBase(){}

if we wish to restore that behaviour.

So even our small adaptation to make a class suitable for use as a polymorphic base class (assuming that there are no contra-indicators) requires:

class PolyBase: public Base
{
public:
  virtual ~PolyBase(){};
  PolyBase(Base const & data)
    :Base(data){}
  // duplication of an explicit 
  // constructors in Base
  // if none then
  // PolyBase(){}
};

Design Patterns gives an example of this where you might want to add an existing text object into a hierarchy of displayable objects. You certainly wish to reuse the existing code for text but you need to supply an interface that conforms to that for the displayable hierarchy so that you will get appropriate polymorphic behaviour. They propose something such as:

class DisplayText :
  public Displayable,
  private Text
{
  // implement Displayable's public 
  // interface
};

While I understand the rationale for not using public inheritance for Text I think that using private inheritance is also an error. I think that if you decide to use the multiple inheritance route, that the interface should be inherited publicly and the implementation mechanism should use protected inheritance. The decision between private and protected inheritance comes down to whether inheritance is being used purely for implementation (when it should be private) or because the implementation choice might be useful in more derived classes. There are benefits and costs both ways. So you should think about it rather than just follow the crowd.

I can see little if any advantage to using private inheritance rather than simple composition or layering. True, you can import functionality with using declarations, but you can do the same thing with forwarding functions to make functionality of the data object available in the protected or public interfaces.

One thought that crossed my mind was that you might want to use a dynamic_cast<> of a Displayable object to determine if it was a Text one and thereby access the full public interface of Text if appropriate. The thing that nags me here (and with the ACCU conference only days away, I have not time to check all the details) is that I do not know how dynamic_cast<> treats protected inheritance, nor do I know how it treats sub-objects that are non-polymorphic (in other words base objects that do not support RTTI). Perhaps someone else might contribute the answers for the next issue. (Some of you are going to have to start providing something pretty soon because Overload is being written by far too few people).

As well as adopting a single class into your polymorphic hierarchy with an appropriate adaptor you might also wish to adopt a whole hierarchy. In this case inheritance definitely is not what you want (I assume that you do not want to adopt the classes on a one by one basis). Straight layering does not help either. You have two choices, a pointer or a reference. Which you choose is a design decision. If you are happy for you DisplayText object to be specialised to the specific Text subtype (e.g. ColouredText) at construction time then you can use a reference member. With only the appropriate members listed something like:

class DisplayText: public Displayable
{
  Text & data
public:
  DisplayText(Text & d):data(d){}
};

Note that this uses an existing object. You will need to consider the Observer pattern as well because the display will need updating if changes are made to the referenced object. If you want the Text object contained in the DisplayText one you will need to investigate creational patterns.

If you want to allow your DisplayText to change the Text object to a different one you will need to use a pointer:

class DisplayText: public Displayable
{
  Text * data
public:
  DisplayText(Text & d):data(&d){}
};

Now you will need to consider what you want to do with assignment and copy construction. Note that the DisplayText object does not own the Text object and so you do not need to concern yourself with problems of deep copying. However your Text object might go away so you do need to implement some variation on the Observer pattern so that the destruction of your Text results in the pointer to Text in DisplayText being reset to null.

As long as you can get the intercommunication between Text objects and DisplayText working correctly then the pointer mechanism is much better than the reference for handling non-ownership semantics.

If you want to adopt a single object type into a hierarchy use either multiple inheritance with public inheritance of the hierarchy interface and protected inheritance of the adoptee

or

single inheritance of the hierarchy interface and layering for the adoptee.

These mechanisms make the object own the instance of the adoptee. You do not need to consider the complexity of providing communication between the adapter and the adoptee but you may need to consider how, if desirable, you are going to provide access to the adoptee's public interface.

If you want to adopt a whole hierarchy you must consider whether the adapter will own the adoptee (either through a pointer or a reference) or just access a free-standing instance.

Let me be entirely honest here; I have no idea what the authors of Design Patterns mean by these. I find their text incomprehensible. I would be delighted to read a simple exposition of this variety of adapter with a good clear example with reasonably full implementation in code. I understand the fundamental concept that I might want an adapter that makes minimal assumptions about the class it is adapting but that is as far as I can go. I doubt that I am the only one who is confused.

There are some interesting examples of adapters in the STL.

We even have examples of adapters that modify behaviour rather than interface. For example the reverse_iterator adapters simply reverse the direction in which a sequence is traversed. As you might expect, these are examples of templates that provide the new behaviour based on the old. The template argument used to instantiate a reverse_iterator must be an appropriate type of iterator.

Then we have a wide range of other function adapters such as the various binders. For example bind2nd<> is a template function that takes two parameters. The first is a binary function returning a bool and the second is a value for the second parameter of that function. Let me give you a simple non-template example.

Suppose I have a perfectly good function computes the product of two objects and I need a specific function (with its own distinct address) that doubles a value. The prototype of the original function might be:

value_t product(value_t, value_t);

Now I write:

inline value_t times2(value_t val)
{ 
  return product(val, 2);
}

Now this kind of adaptation is common (note that default arguments do not help because I might want to have several different constant values for the second parameter in different parts of my program. I could write a special adapter template such as:

template < int i>
inline value_t times_by(value_t)
{
  return product(val, i);
}

Now as long as my compiler supports explicit template arguments for functions I can write something like:

value_t val(12.8);
cout << times_by<3>(val)<< endl;

to get three times val sent to cout.

However this is far from being general enough. Suppose that I have a function that is something like:

template<typename T, typename S> 
  bool has_a_factor(T t, S s);

and I want to create a unary function that tests BigInt values to see if they are divisible by 37. The function I want is:

bind2nd(has_a_factor<BigInt, int>(), 37);

For a single instance this may seem pretty trivial but the STL is riddled with functions that need some form of test function as a template parameter. The existence of such template function adapters makes life much easier (once you get used to using them). As in my example, the test function itself is often a template function (STL provides such functions as greater() ready to plug and play, as long as your type meets the specified interface requirements)

In addition to a rich collection of function adapters, STL also includes a variety of class adapters. For example, when we describe a data structure as a FIFO queue we know exactly what interface we expect it to present to the user. However there are several different internal structures (deque, list etc.) that we might use to implement the necessary behaviour. As long as we stick to appropriate standard STL containers we can create queues with the whole interface generated for us. In deed we can go further if we wish, by creating our own specialist (either template or plain) data structures that can plug into the STL queue template. We have to check exactly what interface elements the STL queue requires of its template argument but as long as we meet those we have a queue available on demand.

Much of the power of the STL comes from a wide application of the adapter concept. It is well worth careful and thoughtful study. That way you will broaden the range of your programming skills. Do not waste time re-inventing wheels but do invest time understanding how wheels work and how to build your own.

Remember that the Amerind (Native American to be PC) never invented the wheel because wheels do not work well across the range of snow, ice, pine forest and prairie, runners work much better on that kind of terrain.

Sorry, but this is as far as I have time to go this time out. Please write in expanding, correcting etc. on what I have written.