Enum std.typecons.Flag

Enum members

Example

Code calling getLine (usually far away from its definition) can't be understood without looking at the documentation, even by users familiar with the API:

string getLine(bool keepTerminator)
{
    ...
    if (keepTerminator) ...
    ...
}
...
auto line = getLine(false);

Assuming the reverse meaning (i.e. "ignoreTerminator") and inserting the wrong code compiles and runs with erroneous results.

After replacing the boolean parameter with an instantiation of Flag, code calling getLine can be easily read and understood even by people not fluent with the API:

string getLine(Flag!"keepTerminator" keepTerminator)
{
    ...
    if (keepTerminator) ...
    ...
}
...
auto line = getLine(Flag!"keepTerminator".yes);

Passing categorical data by means of unstructured bool parameters is classified under "simple-data coupling" by Steve McConnell in the Code Complete book, along with three other kinds of coupling. The author argues citing several studies that coupling has a negative effect on code quality. Flag offers a simple structuring method for passing yes/no flags to APIs.

An alias can be used to reduce the verbosity of the flag's type:

alias KeepTerminator = Flag!"keepTerminator";
string getline(KeepTerminator keepTerminator)
{
    ...
    if (keepTerminator) ...
    ...
}
...
// Code calling getLine can now refer to flag values using the shorter name:
auto line = getLine(KeepTerminator.yes);