Re: [boost] [boost::endian] Request for comments/interest

Subject: Re: [boost] [boost::endian] Request for comments/interest
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2010-05-27 09:10:14

Tomas Puverle wrote:
>
> > Granted, but why not overload versus introduce a
> > long name like "swap_in_place?"
>
> My reasoning:
>
> 1) You cannot overload based on const vs non-const ref, so
> these two functions wouldn't work:
>
> template<typename T>
> void swap(T & t);
>
> template<typename T>
> T swap(const T & t);
>
> 2) Even if you could, I think the name swap_in_place<>()
> better expresses the intent of the function.  However, I
> could rename it to "swap_loc" or something similar if
> that's preferable to users.

The name is ugly, but that's not quite the point I was making, mostly because I was blinded by my own interface when looking at yours.  Allow me to show again what I have and see how the ideas can be merged:

   template <class T, class U>
   void
   to_host(T &, U);

   template <class T, class U>
   T
   to_host(U);

I don't provide in-place byte swapping as you can see, and that's an interesting use case I hadn't considered.

That interface provides for the following use cases:

{
   int32_t wire(/* from wire */);
   int i;
   to_host(i, wire);
}
{
   int32_t wire(/* from wire */);
   int i(to_host<int>(wire));
}

In the latter case, the function looks like a new-style cast.  Arguably, that could be named with "_cast" to make that connotation clearer.

You and others have noted that wire format isn't always big endian; I raised that issue at BoostCon.  My current interface is modeled after ntohs() and similar functions, so it assumes big endian wire format.  Your inclusion of a tag to indicate the direction of the endianness change, if any, accounts for that, obviously, but looks ugly to me.

Here's another take on the interface:

   template <class T, class U>
   void
   from_big_endian(T &, U);

   template <class T>
   void
   from_big_endian(T &);

   template <class T, class U>
   void
   to_big_endian(T &, U);

   template <class T>
   void
   to_big_endian(T &);

   template <class T, class U>
   void
   from_little_endian(T &, U);

   template <class T>
   void
   from_little_endian(T &);

   template <class T, class U>
   void
   to_little_endian(T &, U);

   template <class T>
   void
   to_little_endian(T &);

   template <class T, class U>
   T
   big_endian_cast(U);

   template <class T, class U>
   T
   little_endian_cast(U);

Obviously, I've embedded the direction and ordering in the function template names rather than in a template argument, but that looks more readable to me.  Of course, the direction is relative to the host order.

The casts and the copy-swap functions swap U and return T so long as T is big enough.  That means static checks for relative sizes and signedness.  Obviously, the to_*_endian<>() functions correspond, in part, to your swap_in_place<>() and the casts to your swap<>().  Naming them *_cast is much nicer.

The two-argument overloads are safer than the casts because they eliminate the chance for truncation:

   int32_t wire(/* from wire */);
   short s(big_endian_cast<int32_t>(wire));

Compilers can be configured to warn about such things, of course, but programmers are lazy and can ignore warnings.  If that were written as follows, the compiler can verify the types:

   int32_t wire(/* from wire */);
   short s;
   to_big_endian(s, wire); // ERROR: destination too small

That API supports these use cases:

{
   int32_t wire(/* from wire */);
   long l;
   to_big_endian(l, wire);
   /// OK if sizeof(long) >= sizeof(int32_t)
}
{
   int32_t value(/* from wire */);
   to_big_endian(value);
}
{
   int32_t wire(/* from wire */);
   int i(little_endian_cast<int>(wire));
   /// OK if sizeof(int) >= sizeof(int32_t)
}

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.