Well, what I’m going to talk about today isn’t really magic, but it does illustrate some things you can do with C++ templates that, while certainly not uncommon, may not come immediately to mind. We’re going to use templates to implement some code for dealing with byte-swapping (endianness issues). I originally wrote this content as part of an upcoming post, but that post was already getting to be several pages long. So, I’ve pulled the info out into this post, and will finish that one soon. For quite a long time, I used a simple, but ugly, set of byte swapping functions I had written early in my C++ programming experience. It was filled with a million little functions like:

int hostToLittle(int);
unsigned int hostToLittle(unsigned int);
int hostToBig(int);
unsigned int hostToBig(unsigned int);

and on and on and on. Each function body has a preprocessor switch, determining whether it should actually swap the bytes or not. It was big, it was nasty, and it was a pain to maintain. But, it worked.

Now, I’m planning to put my code out for the whole wide world to see, and while maybe there’s only one or two of you who will actually look at it, I sure didn’t want to put that mess out there. So, I set out to clean it up.

The first step was simple, I just moved the actual byte swapping code out of the individual functions for each data type. The result was three new functions, one each for 2 bytes, 4 bytes, and 8 bytes. That at least opened up the possibility of creating platform specific implementations (such as using lwbrx on ppc, for instance). There’s still a ton of code, though, and lots of preprocessor conditionals.

So, I decided to consider using templates to simplify the code further. For some strange reason, my first thought was not to templatize all of those functions for each different supported data type. I know that is probably the more obvious first step, but it simply didn’t occur to me. Instead, I thought I could use templates to get rid of most of those preprocessor conditionals.

I use boost’s endian.hpp header to determine the host’s endianness. This header provides a handful of preprocessor macros that tell can help you determine the endianness of your host. The first step was to get this information out of the hands of the preprocessor, and give it to the compiler. That was easy:

enum Endianness
{
   BigEndian,
   LittleEndian,
#if defined(BOOST_BIG_ENDIAN)
   HostEndianness = BigEndian
#elif defined(BOOST_LITTLE_ENDIAN)
   HostEndianness = LittleEndian
#else
#error BeeLib only supports big and little endian systems.
#endif
};

You may notice that error condition and wonder “what the heck is that doing there, aren’t all machines big or little endian?” The truth is, any machine this code is likely to run on is, in fact, big or little endian. But there also exists a class of CPUs that are middle-endian, and perhaps even a few other oddities. While I doubt anyone will ever try to build this on something so exotic, if they do, this will show them exactly where and what the error is, instead of in some other part of code where they try to use HostEndianness.

Initially, I wrote a template class, with all of those same functions from before as static members, something like this:

template
class ByteSwapper
{
   static int swapBytes(int);
   static unsigned in swapBytes(unsigned int);
   ...
};

and then template specialization for each of the four possible combinations of endiannesses. That’s right, four implementations of each of those functions:

template<> int swapBytes(int in) { return in; }
template<> int swapBytes(int in) { return in; }
template<> int swapBytes(int in) { return swapBytes4(in); }
template<> int swapBytes(int in) { return swapBytes4(in); }

Ick! That is, I think, worse than the original! Surely we can do better than that!

Of course we can! The next iteration let me cut that list of functions in half, by adding a template parameter to decide if we should swap bytes or not. I never checked this version into source control, so this is from memory, and it almost certainly has some mistakes, but it looked something like this:

template
class ByteSwapper
...
template<> int swapBytes(int in) { return swapBytes4(in); }
template<> int swapBytes(int in) { return in; }

Now that’s not so bad, but, you guessed it, we can still do better! What’s stopping us, for instance, from templatizing on the type of data we’re being asked to swap, so we only need one pair of swap functions for each data size, instead of for each data type? As it turns out, nothing’s stopping us!

First things first, I made the actual byte swapping routines template functions. This reduced the complexity of the calling code, since there was no more need to do any casts or type punning:

template T swapBytes2(T in)
{
   BOOST_STATIC_ASSERT(sizeof(T) == 2); // Make sure this is actually a 2-byte data type
   // do some byte swapping here
   return result;
}

So, at this point, our goal is to come up with a single function that, from the caller’s perspective, looks like this:

int swapped = swapBytes(unswapped);

The caller shouldn’t need to do anything in the way of telling the function how big the data to be swapped is, or whether the data actually needs to be swapped or not. But to function, our swap function needs to know all of that stuff. So, we’ll shield the caller from all of these details by breaking things out into a public interface (the swapBytes function) and an implementation, which will go into a template struct called swapBytes_impl. Since you can’t specialize template functions, this will also allow us to use specialization, but still keep the main entry point a naked function, without the added scoping of a struct or class.

The base implementation looks like this:

template
struct swapBytes_impl
{
   template 
   static T swapBytes(T in) { return in; }
};

And the swapBytes function looks like this:

template
T swapBytes(T in)
{
   // make sure we can actually handle this sized data
   BOOST_STATIC_ASSERT(sizeof(T) == 2 || sizeof(T) == 4 || sizeof(T) == 8);
   // Don't try to swap anything except built-in arithmetic types (integers & floats)
   // If you, for some reason, you think your data should be swapped as-is, then you'll
   // need to cast it to the appropriately sized type yourself. You should also reconsider
   // your design, because it\'s very possibly wrong. Keep in mind, also, that swapping a
   // pointer makes very little sense.
   BOOST_STATIC_ASSERT(boost::is_arithmetic::value);

   return swapBytes_impl::swapBytes(in);
}

Sweet. So now we have a function that can handle not swapping bytes for integers, floats, etc etc etc. Now, we just create some specializations of the implementation that actually does swapping, one for each data size we can handle:

template<>
struct swapBytes_impl
{
   template 
   static T swapBytes(T in)
   {
      return swapBytes4(in);
   }
};

(the rest of these functions look exactly the same, except with the 4’s replaced by 2’s and 8’s)

And that’s it, we’re done! So, what happens when we make a call to this byte swapping function? Let’s start with the simple case:

int swapped = swapBytes

The C++ compiler automatically fills in the last template parameter, T, with the type of the data being passed in, in this case “int”. So, the generated function would look something like:

int swapBytes(int in)
{
   return swapBytes_impl::swapBytes(in);
}

Since we don’t specialize for cases where the bool template parameter is true, this will just expand to the default implementation:

int swapBytes_impl::swapBytes(int in)
{
   return in;
}

This is what happens with the case where we actually need to some swapping. Here’s the call:

int swapped = swapBytes

The template expansion:

int swapBytes(int in)
{
   return swapBytes_impl::swapBytes(in);
}

This time, the bool template parameter is false, and the second parameter is 4. Lo and behold, we have a template specialization for this case! Here’s the expansion:

int swapBytes_impl::swapBytes(int in)
{
   return swapBytes4(in);
}

Beautiful! So, with templates, we’ve managed to reduce this code from a thousand lines or so down to around 200. Would you rather maintain 1000 lines or 200 lines? I thought so. Not to mention, we’ve reduced the number of actual function bodies from some ungodly number to 8. Less code == less errors. You can take a look at the final code here.

Can this be improved further? Probably, but it’s good enough for now. Of course, if anyone has any improvements to suggest, I am open to hear ‘em!

Comments