Having fun with C++11 — how to pass flags to a function

I’ve never been very active posting here, and since I left academia it has been even slower. All of 2016 passed without a single post! Since I now work for a company, it’s become more difficult for me to post about the fun little things that I work with. Nevertheless, I wanted to share a C++ construct that I came up with to pass flags (a collection of yes/no options) to a function.

I’ve been having fun with C++11. I have used mostly C (besides scripting languages such MATLAB or Python) to write image analysis algorithms. Back in the early 1990’s I played around with C++, but hadn’t used it since. In my new job, all code is in C++, and so I’ve had the chance to learn about C++11 and its standard library. C++11 feels like a different language from the C++ of the early 1990’s. It is very expressive, and makes even complicated things easy to implement and maintain.

One of the issues I’ve run into is how to pass flags to a function. Image analysis algorithms often have different modes of operation, and the user of the function must be able to choose the mode. A very simple example could be a clipping function: for example, the clipping function can clip only the low grey-values, only the high grey-values, or both; it can use hard clipping or soft clipping; and it can use the given limits or compute them from the data. These options correspond to four independent boolean values: ClipLow, ClipHigh, ClipSoft, and ClipAuto. If the function has four boolean parameters, then the function call is quite unreadable:

Clip(image, true, true, false, true);

One does not know what each of the true and false values refer to.

The classical solution

In the old days, writing in C, we would use an enumerator for these four options, giving each one a different power of two as a value:

typedef enum {
   ClipLow = 1,
   ClipHigh = 2,
   ClipSoft = 4,
   ClipAuto = 8,
} ClipFlags;

Clip(image, ClipLow | ClipHigh | ClipAuto);

The values can be combined with the bit-wise OR operator, yielding a single value that encodes which of the options were chosen. This worked well, but (being C) there was no strong type checking. You could pass the value 5327 as the flag, and the compiler would be just as happy. Later versions of the C standard enforced stronger type checking, and the compiler would issue warnings if the value passed was not one of those in the enumerator. However, this meant that any combination of two values would yield an integer that is not one of the values in the enumerator, so warnings would be issued when passing more than one flag to the function. To suppress these warnings, function calls looked like this instead:

Clip(image, (ClipFlags)(ClipLow | ClipHigh | ClipAuto));

…hardly any better.

The function itself would test whether a flag is set or not by using the bit-wise AND operator:

if(flags & ClipAuto) { ... }

The C++ way

In C++ there is stronger type checking. Enumerators work more or less the same way, but C++11 introduces an enum class, which does strong type checking: it is impossible to cast a random integer to the enumerator type. The strongly typed enumerator is great, as it makes it unnecessary to test for illegal values. A variable of that type can only ever obtain values within the given collection. This does mean, however, that it is useless for flags.

Alternatives are the std::bitset type, which implements exactly what flags are supposed to do, but identify bits only by their position. One then would define a strong enumerator that gives a name to each bit in the set:

enum class ClipFlags {
   ClipLow,  // has a value of 0 by default
   ClipHigh, // has a value of 1
   ClipSoft, // has a value of 2
   ClipAuto, // has a value of 3
};
std::bitset<4> clipFlagsParam;
clipFlagsParam[int(ClipFlags::ClipLow)] = true;

This makes for even more awkward code… But because bit sets can be ANDed and ORed together, one can define constants that have only one bit set, and use these just as we used the enumerated constants in the old C code (but with strong type checking, meaning that one cannot assign just any integer value as the flag set):

using ClipFlags = std::bitset<4>;
constexpr ClipFlags ClipLow(1);
constexpr ClipFlags ClipHigh(2);
constexpr ClipFlags ClipSoft(4);
constexpr ClipFlags ClipAuto(8);

Clip(image, ClipLow | ClipHigh | ClipAuto);

There is, however, still one small issue here that we haven’t discussed yet: if another function, with a different set of flags, also happens to have four flags, its flag type (e.g. ConvolutionFlags) would be an alias, because it also maps to a std::bitset<4>. Good-bye strong type checking:

Clip(image, ConvolutionHack); // the compiler is OK with this,
                              // even if it makes no sense...

How do we really want to use flags?

Let’s take a moment here to reflect on the syntax of flags. We OR the flags together to set multiple flags. We are saying “I want ClipLow OR ClipHigh“, rather than “I want ClipLow AND ClipHigh“. Because we do want both flags set, not the one or the other. To test, we use the AND operator, which is equally awkward. We accept this syntax because we’ve always done it this way, and we know what it means, but the syntax really does not express what we mean at all!

Wouldn’t it be nicer if we could instead say

Clip(image, ClipLow + ClipHigh + ClipAuto);

What operator to use to test whether a flag is set is a little bit more involved. I have settled finally for the equality operator (==), even though it’s somewhat an abuse of its meaning. But we expect comparison operators to yield a true/false response, so it is a natural fit in some way. Another option could be the greater-or-equal operator (>=), which could be read as “the flag set is a superset of the flags on the right”. So flags >= ClipLow + ClipHigh says that flags has at least those two flags set. It also makes the asymmetry clear. However, !(flags >= ClipLow + ClipHigh) is not the same as flags < ClipLow + ClipHigh, and that can be confusing too. So instead I picked the equality operator here, with the inequality operator returning the opposite value.

My way

This is the class that I came up with:

template<typename E>
class Options {
      unsigned long values;
      constexpr Options(unsigned long v, int) : values{v} {}
   public:
      constexpr Options() : values(0) {}
      constexpr Options(unsigned n) : values{1UL << n} {}
      constexpr bool operator==(Options const& other) const {
         return (values & other.values) == other.values;
      }
      constexpr bool operator!=(Options const& other) const {
         return !operator==(other);
      }
      constexpr Options operator+(Options const& other) const {
         return {values | other.values, 0};
      }
      Options& operator+=(Options const& other) {
         values |= other.values;
         return *this;
      }
      Options& operator-=(Options const& other) {
         values &= ~other.values;
         return *this;
      }
};

It is pretty straight-forward. A single private member is an integer that holds the flag values. A constructor creates an object with the n’th value set. The operators discussed above are implemented, as well as the compound assignment operators += and -=, which add and remove a flag from a set. The private constructor is used by the plus operator. The class is defined as a class template, where the template argument exists solely to make a distinction between different sets. That is, the template argument makes it so that we can define two different flag sets (for the clip function and the convolution function) and keep those sets as strictly different types. This is how you would use it:

class ClipFlags__Tag; // never defined!
using ClipFlags = Options<ClipFlags__Tag>;
constexpr ClipFlags ClipLow(0);
constexpr ClipFlags ClipHigh(1);
constexpr ClipFlags ClipSoft(2);
constexpr ClipFlags ClipAuto(3);

Clip(image, ClipLow + ClipHigh + ClipAuto);
Clip(image, ConvolutionHack); // compiler error, ConvolutionHack is not of type ClipFlags.

if(flags == ClipAuto) { ... }

I have also defined the following two preprocessor macros, to make it even easier to use this class template:

#define DECLARE_OPTIONS(name) class name##__Tag; using name = Options<name##__Tag>
#define DEFINE_OPTION(name, option, index) constexpr name option(index)

To create the constants above we now do:

DECLARE_OPTIONS(ClipFlags);
DEFINE_OPTIONS(ClipFlags, ClipLow, 0);
DEFINE_OPTIONS(ClipFlags, ClipHigh, 1);
DEFINE_OPTIONS(ClipFlags, ClipSoft, 2);
DEFINE_OPTIONS(ClipFlags, ClipAuto, 3);

This is hardly more work than the original C code to define flags, yet it yields strong type checking (the user will never be able to pass illegal or unknown flags, confuse the flags from different algorithms, etc.), and a very pleasant syntax that makes sense for people that never had to deal with bit sets.

Do note also that

DEFINE_OPTIONS(ClipFlags, ClipBoth, ClipLow + ClipHigh);

invokes the copy constructor, so is perfectly fine.

In closing

C++11 really allows to create custom types that behave in any way one wants. And it doesn’t take a lot of effort to do so. I’m certainly enjoying its expressiveness, especially compared with plain old C.

Let me know what you think!

7 Responses to “Having fun with C++11 — how to pass flags to a function”

  1. On January 5th, 2017, at 8:37, Petter said:

    Seems way over-engineered. Just define a regular struct with public bool members.

    Also, macros are not very idiomatic C++.

  2. On January 5th, 2017, at 10:52, Cris said:

    Hej Petter,

    Macros are wonderful. There’s better constructs in C++ for many of the applications of macros in C, but that doesn’t mean they don’t have their unique uses in C++. I’m not ashamed to use them! ๐Ÿ™‚

    Your struct approach leads to code that is either not any better than simple parameters to the function:

    Clip(image, ClipOptions{true,true,false,true});
    

    or overly verbose:

    ClipOptions clipOptions;
    clipOptions.left = true;
    clipOptions.right = true;
    clipOptions.auto = true;
    Clip(image,clipOptions);
    

    Or am I missing something?

  3. On January 6th, 2017, at 15:20, Petter said:

    Thatโ€™s right. I had the second approach in mind. The first one is not readable. (Bitfields can obviously be used if space is important for some reason)

    Your code will be difficult to understand because + is using | internally which is surprising. It is clever where there is no need to be clever. The library will actually be harder to use.

    If you really want short calling code, here is how to do it:

    enum class ClipFlags { ... };
    void Clip(Image& image, std::set flags);
    

    The Clip function can then be called as

    Clip(image, {ClipLow, ClipHigh, ClipAuto});
    

    P.S. Your blog does not render the angle brackets in template code.

  4. On January 6th, 2017, at 17:13, Cris said:

    Using a set is a nice idea. It’s not the most efficient way of doing it, but I like it.

    I’ve fixed the angle brackets, thanks!

  5. On January 14th, 2017, at 14:35, Geert said:

    Hi Cris,

    Good to see you back on the blog? You live in the US now, I believe? I live in NJ at the moment. How is the commercial world treating you?

    Geert

  6. On January 14th, 2017, at 20:57, Cris said:

    Hi Geert,

    Thanks for stopping by! It’s always good to hear from you!

  7. On March 27th, 2017, at 5:11, Patrik said:

    Hi Cris,

    Nice to see a new blog post!

    Reading the comments I wanted to put my 0.2 cents … in Petters hat. While your approach is really well thought through, i would say that from a humble user’s standpoint it seems somewhat confusing. I prefer the overly verbose struct approach. Using that approach I can hand over my code to someone else for review or simply come back to the code 6 months later and it’s clear what is happening.

    Now, I should’ve prefaced this comment with the fact that I’m working in C# now (and loving it). The coding guidelines in C# fit better for writing novels rather than compact code ๐Ÿ™‚

Leave a Reply

You can use these HTML tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

Note: I moderate all comments. Comments without a clear relation to the text above will not be published.