CrashCourse – 006 – Templates and relationals

Last time I introduced the Intrinsic class together with some handy relational operator related functionality. But since Intrinsic is now the home of operations like Clamp and Max and these operations are defined by templates, without filtering the template parameters they can receive, anything can be passed to these functions. Even things that are not comparable!

So let’s see what problems this can cause and how to solve them. Let us consider a simple Version class that holds the major, minor and revision number of some product. A very simple class, not meant to be functional, just a simple example:

class Version {
	val major = 0;
	val minor = 0;
	val revision = 0;
	
	this(maj: Int, min: Int, rev: Int) {
		major = maj;
		minor = min;
		revision = rev;
	}
}

To break up the monotony of large blocks of text on the blog, I shall show a screenshot of the typical ZIDE workflow that is used when developing the samples for this blog and anything else Z2 related:

006less01

A quick tour of the sample. On line 3 we define our simple Version class and on line 15 we define a class with a @main slot method to test the version class. On lines 17 and 18 we instantiate two version variables.

On line 20, we test the equality of these two variables. As described in CrashCourse – 003 – What you get for free, Z2 will figure out common task for you from a small pool of common tasks. Simple straightforward comparison of value types is one of these tasks. The compiler takes one look at the Version and has zero problems to test equality of two instances. You as a programmer you shouldn’t have to write such easy boring code that only compares 3 Ints. Same for line 21, where we test for inequality. These two lines work out of the box because aggregate value type equality if a well defined unambiguous operation. Such methods that are provided automatically by the compiler for you are called automatic methods. They are always provided, but you can suppress this for a class/method combination if not needed.

And this is the reason why line 22 fails to compile. On this line, we don’t use operators == or !=, but operator <. The “less” operator can’t be defined unambiguously for aggregate types and the compiler can’t resolve v1 < v2. This is what the error says. Maybe the error message could be improved though.

The solution for this compilation error is to provide a < since the compiler can’t provide one for us. In Z2, method names that start with @ are called slots and they are just regular methods, but in some context the compiler will call them implicitly. Like @main. The calling mechanisms of the slots makes them perfect candidates for defining operators in classes. This was deemed a better solution than using a keyword like in other programming languages and the literal operator. It is easier to read, type and manually call. And solves some additional problems, like with pre and post ++ operators.

The < can be defined using the @less method:

class Version {
	val major = 0;
	val minor = 0;
	val revision = 0;
	
	this(maj: Int, min: Int, rev: Int) {
		major = maj;
		minor = min;
		revision = rev;
	}
	
	def @less(const v: Version): Bool; const {
		System.Out << "call " << class << '.' << def.Name << " of class " << @neq.class << "\n";
		if (major < v.major)
			return true;
		else if (major > v.major)
			return false;
		else  {
			if (minor < v.minor)
				return true;
			else if (minor > v.minor)
				return false;
			else
				return revision < v.revision;
		}
	}
}

This updated Version class defines on line 12 the @less slot. Now, when we do v1 < v2, the @less method will be called on the v1 instance and v2 will be passed in as a parameter. This is of course just syntactic sugar since @less is just a normal method with a name that starts with @, so it can be called normally: v1 < v2 and v1.@less(v2) are equivalent and result in the same machine code. The actual implementation is not important. I used here a simple implementation of the top of my head for comparing versions and may not be the optimal way to compare versions in production code. It is just a sample. This method could be implemented to not work as a relational less operator, even though it represents that slot. It is a very good idea not to do this to avoid major confusion.

One strange thing about this method is line 13. This is just for this sample to test that this method is actually called. Normally, you wouldn’t add such tests in real code. It could have been a simple System.Out << "Hey, @less has been called"; but I opted for this more complicated statement to demonstrate some reflection. Z2 has both compile and run time reflection and these features combined with templates and can be quite powerful. But in this sample we only use reflection for basic debugging. First we print out class. This is equivalent with this.class and returns the compile time class information for this, a reference to the current instance. def is similar to this, but does not represent the current instance, but instead the current method. Like class.Name, def.Name will return the name of the current method. And similarly to this.class, def.class returns the class information for the current method. In Z2 everything is an instance of a class, even methods. The class of all methods is Def. But instead of printing out def.class, I printed out the class of another method: @neq.class. It is the same class and I used this in the sample both to demonstrate that the classes are the same and that automatic methods are there and present, even if it not obvious that they are: @eq is the == operator and @neq is the != operator. So the output of this program after the fix will be:

false
true
call Version.@less of class Def
true

With @less working, now we can try a much more complicated sample, where we use all relational operators, Min,Max, Clamp and so on:

class Test {
	def @main() {
		val v1 = Version{1, 2, 7000};
		val v2 = Version{2, 0, 1};
		
		System.Out << (v1 < v2) << "\n";
		System.Out << (v1 > v2) << "\n";
		System.Out << (v1 <= v2) << "\n";
		System.Out << (v1 >= v2) << "\n";
		
		System.Out << "Min: " << Intrinsic.Min(v1, v2) << "\n";
		System.Out << "Max: " << Intrinsic.Max(v1, v2) << "\n";
		
		val v3 = Version{1, 0, 0};
		Intrinsic.Clamp(v3, v1, v2);
		System.Out << "Clamp: " << v3 << "\n";
		
		val v4 = Intrinsic.Clamped(Version{7, 5, 6}, v1, v2);
		System.Out << "Clamped: " << v4 << "\n";
	}
}

call Version.@less of class Def
true
call Version.@less of class Def
false
call Version.@less of class Def
true
call Version.@less of class Def
false
call Version.@less of class Def
Min: 1 2 7000
call Version.@less of class Def
Max: 2 0 1
call Version.@less of class Def
Clamp: 1 2 7000
call Version.@less of class Def
call Version.@less of class Def
Clamped: 2 0 1

The interesting part of this sample starts on lines 6-9. We only defined operator <, but we can use >, <= and >=. Think of it as the compiler making up for the fact that it couldn’t provide you with a free < operator. If you have @less defined, but not @more(the > operator), the compiler can still handle > by swapping the two operands: v1 > v2 is compiled as v2 < v1. And since we provided less and @eq, the equality operator, is an automatic method, the compiler can use them both to provide operator , called @lesseq and @moreeq. And once all these operators are defined manually or automatically, you can now use all the stuff from Intrinsic. And the same applies for when you have @more defined but not @less.

This part of the language design may be a bit confusing at first, so let me reiterate the rules:

  • @eq (==) and @neq (!=) are automatic. You get them for free, but you can of course override them and do something different. For POD types you rarely need to, but or non POD types and types that embed pointers, you may need to provide a better implementation since the automatic one might not do what you need.
  • @less (<) and @more (>) are not automatic. You need to define at least one of them! If you define both, they are use appropriately. If you define only one, their opposite is resolved by swapping around the operands.
  • @lesseq (<=) and @moreeq (>=) are automatic only if you defined at least one of @less and @more. Once you define at least one of these two, you get all 4. You are free to override @lesseq and @moreeq as with the others, and sometimes it is worth it from a performance point of view. To do <=, the compiler may need to do both < and =. It is sometimes possible to implement <= in a more efficient way.

So to reiterate, in order to get full relational operator coverage, you need to define either @less, @more or both!

In the git repository you can find these samples and more, part of the daily unit-testing.

With this, the very basics of the core numerical types are covered. Next time I’ll extend upon this as a jumping off point to introducing vectors!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s