More on Naked Primitives

The post Strong Typing or Naked Primitives showed an example of problems that can occur when using common variable types (or if you prefer, built-in data types) as argument types in methods and functions, and a potential solution. The post discussed a Size struct with the constructor:

struct Size {
    Size(const uint32_t width, const uint32_t height);
};

and the possible problems that can occur, such as placing the height argument before the width argument.

User Defined Literals continued the example by showing how to use and convert different unit types in the arguments. Specifically, the best way to supply the width and height arguments in units of pixels, inches, and centimetres.

This post will continue to investigate ways of specifying arguments to remove the confusion that can occur when using common variable types as arguments.

Character String to Enumeration

In this post, we will declare a class that partially encapsulates the functionality of C File I/O. A good introduction to C File I/O is provided by programiz.com.

Here is a simple first File class and how to use it. We are interested only in the arguments; the actual implementation is not included. That is up to you to provide.

class File
{
public:
    File(const char* fileName, const char* mode) 
        { /* create file if necessary, and open it */}
    ~File() { /* close file */}
    void print(const char* charString, bool appendReturn) 
        { /* print charsString */}
};

int main()
{
    File file1("file1", "a");
    file1.print("A line", true);
    File file2("file2", "w");
    file2.print("A line, no return", false);
    File file3("file3", "xmf_");
    return 0;
}

The constructor for file1 will create the file if it does not exist, then move the cursor for writing to the file to past the last character in the file. The constructor for file2 will create the file if it does not exist, or erase the contents of the file if it does exist, and place the write cursor at the beginning of the file. The constructor for file3 contains invalid characters in the mode field, so you would have to add code to the File constructor to handle this.

Another problem with the constructor as it is declared is that there are two arguments of type const char* so if you specify the arguments in the wrong order when calling the constructor, the compiler will not catch the error. We will not look at this further as this has already been discussed in Strong Typing or Naked Primitives.

So, our only concern here is the second argument, the mode. Since there are a limited number of values, this appears to be a good candidate for an enumeration instead of a string. Looking at the possible values for mode you will notice that it serves two different purposes:

  1. Indicates that the file should be opened for some combination of reading, writing, or appending.
  2. Indicates whether the file contents are text or binary.

To simplify the code in the constructor, let’s use two separate enumerations, one for the operation type, and one for the contents type. Here is the code resulting from these changes:

enum Mode {
    eRead = 1,
    eWrite = 2,
    eAppend = 4
};

enum Type {
    eText = 1,
    eBinary = 2
};

class File
{
public:
    File(const char* fileName, unsigned int mode, enum Type type) 
        { /* create file if necessary, and open it */}
    ~File() { /* close file */}
    void print(const char* charString, bool appendReturn) 
        { /* print charString */}
};

int main()
{
    File file1("file1", eAppend, eText);
    file1.print("A line", true);
    File file2("file2", eWrite, eText);
    file2.print("A line, no return", false);
    File file3("file3", eRead | eWrite, eText);
    File file4("file4", eBinary | 16, eText);
    return 0;
}

The Mode enumeration contains only three values: eRead, eWrite, and eAppend.  No attempt has been made to distinguish between the fopen modes of “w+” and “r+”. That is left as an exercise for the reader because it is not germane to the topic of this post.

Since a file can be opened for both reading and writing, or reading and appending, the second argument for the File constructor is specified as unsigned int. Multiple values of mode can therefore be OR’ed together. See, for example, the constructor call for file3. Everything looks good so far. Now look at the constructor call for file4. Here the Mode has been set to a combination of eBinary, which is a Type not a Mode, and 16 which has no numerical equivalent in Mode.

One potential solution to this problem is to add two enumeration values to the Mode enumeration: eReadAndWrite, and eReadAndAppend, and to change the second argument type in the File constructor to enum Mode. This works in this case, but what if Mode had a large number of individual values which could be combined in many different ways? Defining a value for every combination would not be a viable option.

The solution is to change the Mode and Type enumerations to both be enum class and to add a class that can OR together multiple Mode values:

enum class Mode : unsigned int {
    eRead = 1,
    eWrite = 2,
    eAppend = 4
};

enum class Type : unsigned int {
    eText = 1,
    eBinary = 2
};

template <typename BitType, typename MaskType = unsigned int>
class Flags
{
public:
 Flags()
 : m_mask(0) {}

 Flags(BitType bit)
 : m_mask(bit) {}

 Flags(Flags<BitType> const& rhs)
 : m_mask(rhs.m_mask) {}

 Flags<BitType> operator|(Flags<BitType> const& rhs) const
 {
 Flags<BitType, MaskType> result(*this);
 result |= rhs;
 return result;
 }

private:
 MaskType m_mask;
};

using ModeFlags = Flags<Mode>;
ModeFlags operator|(Mode bit0, Mode bit1)
{
 return ModeFlags(bit0) | bit1;
}


class File
{
public:
    File(const char* fileName, ModeFlags mode, Type type) 
    { /* create file if necessary, and open it */}
    ~File() { /* close file */}
    void print(const char* charString, bool appendReturn) 
    { /* print charString */}
};

int main()
{
    File file1("file1", Mode::eAppend, Type::eText);
    file1.print("A line", true);
    File file2("file2", Mode::eWrite, Type::eText);
    file2.print("A line, no return", false);
    File file3("file3", Mode::eRead | Mode::eWrite, Type::eText);
    File file4("file4", Type::eBinary | 16, Type::eText);
    return 0;
}

The Flags class has been borrowed from the Vulkan C++ bindings, vulkan.hpp, available as part of the Vulkan SDK, or separately from its GitHub repository. I have included only those parts of the class that are required for this example to compile or not where required. Things to note:

  1. The second argument in the File constructor has been changed to type ModeFlags, which is just an alias for Flags<Mode>.
  2. The line containing the constructor call for file3 now compiles.
  3. The line containing the constructor call for file4 does not compile because Type::eBinary and 16 are both not of type Mode. But, since this is a programming error, that is what we want to happen.

Update (February 17, 2017): A few days after publishing this post, I ran across Alternative to select-many bitmask that discusses a number of methods for combining bitmask bits.

Boolean to Enumeration

In the section above, we changed a character string that could contain a limited number of values to enumerations. By doing so, we ensured that invalid values could not be coded, and we ensured that 6 months from now when you or someone else looks at the code, they will not have to reference the documentation or the class’s declaration to determine the meaning of each argument.

Now we move on to boolean arguments. In the main function in the examples above, there are calls to File::print. The second argument in these calls contains either true or false. Can you tell what those argument values mean without looking at the class declaration? What happens if you change the value of this argument to 6? Hint: the program will still compile, but the compiler will generate a warning.

Let’s change this boolean to an enum class.

enum class LineEnd : bool {
    eNoReturn = false,
    eReturn = true
};
.
.
.
    void print(const char* charString, LineEnd appendReturn) 
    { /* print charString */}
.
.
.
    file1.print("A line", LineEnd::eReturn);
    file2.print("A line, no return", LineEnd::eNoReturn);

Now there is no confusion as to the meaning of the second argument to the File::print method. Also, trying to use values like true or 6 for this argument cause a compiler error.

Update (February 17, 2017): A few days after I published this post, Andrzej Krzemieński published a post with an alternative that uses a tagged_bool class.

Conclusions

The examples in this post are contrived to illustrate the points I am trying to make. I do not expect that anyone would actually try to write the File class I have started to declare because the functionality that would be provided in such a class is already available in classes in the standard C++ library. However, a number of conclusions can be drawn from using the techniques shown in these examples:

  1. By changing function and method arguments from common variable types to classes, including enum classes, a number of errors that formerly would only show up at program execution time can now be caught at compile time. This moves the burden of dealing with these errors from the user to the developer where they belong.
  2. Assuming that the classes and enumeration values are properly named, the meaning of the argument values specified  in the source code are much clearer, thereby making the work of the code maintainer much easier.