C++ class design with invariant

cclassinvariants

I've been pondering a really basic question about how far to take enforcing a class's invariant. Maybe that's worded badly, so as an example, let's say that I want to write a class which stores a limited palette of colours. The class's constructor should take the size of the palette – the idea being that you can add as many colours to the palette as you want, but it restricts the size on a FIFO policy. So we'll say that I want to arbitrarily restrict this size to the range 1 to 32 ("nobody will ever need more than 32 colours").

Let's get started…

class palette
{
public:
   palette(unsigned int max_size) : m_max_size{max_size} { }
private:
   unsigned int m_max_size;
};

So far, so good. Except I'm not doing anything to confirm that the max size is within my restricted range, i.e. the invariant can be broken right from construction.

(Just to clarify: this class isn't intended for use in some public library – it's simply an internal class to a single application)

Four options spring to mind beyond "do nothing":

Put a comment on the class to ask callers to use the class correctly.
```
// Please only call with 1 <= max_size <= 32
```

Assert that it's within range.

assert(max_size >= 1 && max_size <= 32);

Throw an exception if it's outside the range

if (max_size < 1 || max_size > 32)
    throw std::invalid_argument();

Get the compiler to check by converting to a template

template <unsigned int MAX>
class palette
{
public:
    palette() { // no need for the argument any more
        static_assert(MAX >= 1 && MAX <= 32, "oops");
    }
};

Options #1 seems a little bit like wishful thinking, but maybe it's good enough for 'just' an internal class? Options #2 to #4 are increasingly fussy about the size, to the point where #4 changes the syntax so that the compiler will report an error if the class isn't being used correctly.

I'd welcome any thoughts on this. I understand that the answer will probably begin with "Well it all depends…", but I'm just fishing for some general guidelines or some alternate suggestions.

Best Answer

I would go with an assertion. Without any further information, I'd probably default to the non-static assert().

A comment would indeed be wishful thinking. Not only can it be ignored, but it can very easily go out of date if (when?) you decide 32 should no longer be the limit.

If this was a public API with other programmers using it, the exception would be beneficial as it tends to provide more debugging information, especially if you included a meaningful error message such as "walderFrey::palette size must be between 1 and 32 inclusive". Otherwise, they might have to dig into your source code and learn how your library works just to figure out why that random assert failed. But since this is just for your own use, there's not as much benefit in that. And you might as well get the (admittedly small) performance benefit of having the assert() disappear in non-debug builds.

I've also heard it argued that exceptions should indicate unpredictable, exceptional conditions that may be unlikely to repeat or may not even be fixable, while assertions should indicate programmer errors that definitely can and should be fixed. I generally agree with this guideline when there is no public API to worry about.

The template solution is neat, but that raises a bigger question: should a size-1 palette and a size-32 palette be considered the same type? Does it make sense to assign one to the other? If it does not make sense, then that's an additional benefit of implementing this class as a template. But you should not decide whether to make this class a template solely because a static_assert() is slightly nicer than an assert(). A regular assert() is definitely "good enough". Normally, generic code involving templates is more complex, so I'd default to a "normal" class until I felt the complexity was justified, hence I'd recommend assert() unless you feel going with templates is justified for other reasons.

Related Solutions

Loop invariant vs Assertions

An invariant is a condition that can be relied upon to be true during execution of a program. For example, a loop invariant is a condition that is true at the beginning and end of every execution of a loop.

An assertion is a predicate (a true–false statement) placed in a program to indicate that the developer thinks that the predicate is always true at that place. Programmers often use assertions in their code to make invariants explicit.

While Loop Invariance Theorem
Assume that S is an invariant of the loop

While C do
 E

Assume also that S is true on the first entry to the loop. Then S stays true after every iteration of the loop. In particular,

If the loop terminates then S is true after the last iteration.
If the loop does not terminate then S always stays true.

C++ – How to store various sized values in a vector

Firstly, command classes are decoupled from the medium and protocol. That means you can design the command classes for your own programming convenience, rather than having to design it to match exactly to the specifics of each protocol (which would be impossible, since different protocols may have different bit widths for the same command and field).

When I mention convenience, what I mean is that you can use the maximum bit width you'll ever need for each command's fields.

However, you may still need to have device- or protocol-specific validation code, since each device or protocol imposes its own limits to what values can be in those fields. Unless you don't plan to implement any validation at all.

When it comes to validation, there are several choices:

Not doing it at all, if you will be doing all of the programming yourself, and if it is a hobby project such that mistakes do not result in damages.
Validating it eagerly, i.e. in the command class. This may be difficult, since a command class might not know which device or protocol it will be sent to.
Validating it late, i.e. in the protocol class where the command values are being converted into bytes.

For example, even if a validation rule says that a particular field can only have a value in the range 0 - 100, it doesn't stop you from using a uint32_t or int32_t for that field in the command class.

To the second question of having an overloaded method that takes in various built-in number types and append the bytes to an internal byte vector, do notice the caveats.

In my opinion, if you only needs to work with the fundamental integer types, you don't need templates. Instead, you simply provide function overloads for each of the types, and you call the functions with a value of the appropriate type.

void CPacket::addData(uint32_t data) { ... }
void CPacket::addData(int32_t data) { ... }
void CPacket::addData(uint16_t data) { ... }
void CPacket::addData(int16_t data) { ... }
...

Regarding the code inside, there are several choices:

Type punning with union. This assumes that your code will work exclusively with one byte-endianness, thus not needing to consider the possibility of porting to a different byte-endianness.

union
{
    uint32_t value;
    uint8_t bytes[4];
} pun = { data };
// after that, add the bytes to the vector one-by-one, according to the byte endianness of the communication.

Explicitly extracting the bytes with endian-agnostic bitwise arithmetic: (see note on casting)

// only if value is unsigned. For signed value, it must first be cast to unsigned
uint8_t byte0 = (uint8_t)value;
uint8_t byte1 = (uint8_t)(value >> 8ul);
uint8_t byte2 = (uint8_t)(value >> 16ul);
uint8_t byte3 = (uint8_t)(value >> 24ul);

Best Answer

Related Solutions

Loop invariant vs Assertions

C++ – How to store various sized values in a vector

Related Topic