Tagging

Tagging

Go back Home

Motivation

Assume you have the following class:

class LatLong
{
public:
	LatLong(double latitude, double longitude)
	: latitude{latitude}
	, longitude{longitude}
private:
	double latitude;
	double longitude;
}

Now, you want to use the units library in order to make sure that the given coordinates are of the right type. You remember that latitude and longitude are actually angle units measured in degrees, so you choose to implement the class like this:

class LatLong
{
public:
	LatLong(Degrees latitude, Degrees longitude)
	: latitude{latitude}
	, longitude{longitude}
private:
	Degrees latitude;
	Degrees longitude;
}

Now, you want to use this class, so you write the following code:

Degrees longitude{33};
Degrees latitude{32};
LatLong coordinate{longitude, latitude};

Did you notice the mistake? You accidentally switched between the latitude and the longitude.

With tags, you can prevent this mistake.

What are Tags?

Tagging is our way to give a certain unit a special meaning. In our case, the coordinates are not just arbitrary degrees, but they are latitude and longitude with a very distinctive meaning to each one of them.

With tags we can create new classes named Latitude and Longitude and use them in our code. We do that by creating a tag struct for each one of them and then create tagged unit classes:

struct latitude_tag{};
struct longitude_tag{};

using Latitude = Tag<Degrees, latitude_tag>
using Longitude = Tag<Degrees, longitude_tag>

class LatLong
{
public:
	LatLong(Latitude latitude, Longitude longitude)
	: latitude{latitude}
	, longitude{longitude}
private:
	Latitude latitude;
	Longitude longitude;
}

Now, we can use this class properly:

Latitude latitude{32};
Longitude longitude{33};
LatLong coordinate{latitude, longitude};

And the following code will not compile:

LatLong coordinate{latitude, Degrees{33}}; // This will not compile since you cannot use untagged units.
LatLong coordinate{longitude, latitude}; // This will not compile since the values are switched

Class Tagging

As in the example above, you can tag classes by using the Tag<> typedef. It takes a unit class and tag classes and creates a tagged unit with those tags. For example:

struct tag1{};
struct tag2{};
struct tag3{};

using TaggedMeters1 = Tag<Meters, tag1>; // This unit has the "tag1" tag.
using TaggedMeters2 = Tag<Meters, tag1, tag2, tag3>; // This unit has the "tag1", "tag2" and "tag3" tags.
using TaggedMeters3 = Tag<TaggedMeters1, tag2>; // This unit has both the "tag1" and "tag2" tags.

Tagging a unit twice with the same tag doesn't have any effect. Therefore, the following will compile:

using TaggedMeters4 = Tag<Meters, tag1, tag1>;
static_assert(std::is_same<TaggedMeters1, TaggedMeters4>::value, "Units are not the same!"); // This PASSES the static assert

Class Untagging

You can remove tags from a given unit class using the Untag<> typedef. For example:

using AllTaggedMeters = Tag<Meters, tag1, tag2, tag3>;
using UntaggedMeters1 = Untag<AllTaggedMeters, tag1>; // This unit has the "tag2" and "tag3" tags.
using UntaggedMeters2 = Untag<AllTaggedMeters, tag1, tag2>; // This unit has only the "tag3" tag.
using UntaggedMeters3 = Untag<UntaggedMeters1, tag2>; // This unit has only the "tag3" tag.

Untagging a unit with the same tag twice, or untagging a unit with a tag it does not contain, has no effect.

Object Tagging

You can tag a given object using the tag() function. It creates a new copied object with same value and unit, but with the given tag. Here is an example using the previously defined tags.

Meters m{3};
auto tm1 = tag<tag1>(m); // This object has the "tag1" tag.
auto tm2 = tag<tag1, tag2, tag3>(m); // This object has the "tag1", "tag2" and "tag3" tags.
auto tm3 = tag<tag2>(tm1); // This object has both the "tag1" and "tag2" tags.

Same as classes tagging, tagging twice with the same tag has no effect.

Object Untagging

Same as class untagging, you can untag unit object using the untag function. For example:

AllTaggedMeters am{3};
auto um1 = untag<tag1>(am); // This object has the "tag2" and "tag3" tags.
auto um2 = untag<tag1, tag2>(am); // This object has only the "tag3" tags.
auto um3 = untag<tag2>(um1); // This object has only the "tag3" tags.

Same as class untagging, untagging the same tag twice or untagging with a tag that the unit does not contain, has no effect.

Untag All

You can untag all tags from classes using the UntagAll<> typedef and from objects using the untagAll() function. For example:

using AllUntaggedMeters = UntagAll<AllTaggedMeters>;
bool isSameClass = std::is_same<AllUntaggedMeters, Meters>::value // This is true!
bool isSameObject = untagAll(am) == 3_meters; // This is true!

Tags Checking

You can use the hasTag() function to check if a unit has a certain tag. This function is static constexpr, which means:

• It is calculated in compile time and can be used in static_assert (for example).
• It is static, which means it can be run over the class or an instance of the class.

if (tm1.hasTag<tag1>()) cout << "object has tag!" << endl; // Printed!
if (TaggedMeters2::hasTag<tag2>()) cout << "class has tag!" << endl; // Printed!
static_assert(tm3.hasTag<tag3>(), "object doesn't have the required tag"); // This will not compile!