Operators

C4Script nowadays supports most operators known from other programming languages (C/C++ style) or mathematics.
The usual operator priority applies (multiplication before addition and similar). For further information, see the table below.
Use brackets to force a specific operator priority.
The following operators are supported:
Priority Operator Description Location Type (resulting, expected)
15 ++ Increases the value of the following variable by 1. prefix reference, reference
15 -- Decreases the value of the following variable by 1. prefix reference, reference
15 ~ Bitwise negation of the following value. prefix int, int
15 ! Logical negation of the following value. prefix bool, bool
15 + no effect (compatibility for terms such as "+5") prefix int, int
15 - Yields the reciprocal of the following value. prefix int, int
15 ++ Increases the value of the preceding variable by 1. postfix (only one parameter) int, reference
15 -- Decreases the value of the preceding variable by 1. postfix (only one parameter) int, reference
14l ** Yields the power of a to b. postfix int, int/int
13l / Divides a by b. postfix int, int/int
13l * Multiplies a by b. postfix int, int/int
13l % Yields the remainder of the devision of a by b. postfix int, int/int
12l - Subtracts b from a. postfix int, int/int
12l + Adds a to b. postfix int, int/int
11l << Performs a bit shift operation to the left. postfix int, int/int
11l >> Performs a bit shift operation to the right. postfix int, int/int
10l < Returns whether a is less than b. postfix bool, int/int
10l <= Returns whether a is less than or equal to b. postfix bool, int/int
10l > Returns whether a is greater than b. postfix bool, int/int
10l >= Returns whether the first value is greater than or equal to the second. postfix bool, int/int
9l == Returns whether a equals b. For proplists and arrays, pointers are compared. Use DeepEqual to compare contents. postfix bool, any/any
9l != Returns whether a is unequal to b. For proplists and arrays, pointers are compared. Use !DeepEqual to compare contents. postfix bool, any/any
8l & Performs a bitwise AND operation. postfix int, int/int
6l ^ Performs a bitwise XOR operation. postfix int, int/int
6l | Performs a bitwise OR operation. postfix int, int/int
5l && Performs a logical AND operation. postfix any, any/any
4l || Performs a logical OR operation. postfix any, any/any
3l ?? Returns the left-hand operand if the operand is not nil, or the right-hand operand otherwise. postfix any, any/any
2r *= Multiplies the preceeding variables by the following value. postfix reference, reference/int
2r /= Divides the preceeding variable by the following value. postfix reference, reference/int
2r %= Sets the preceeding variable to the remainder of the devision of that variable by the following value. postfix reference, reference/int
2r += Increases the preceeding variable by the following value. postfix reference, reference/int
2r -= Decreases the preeceding variable by the following value. postfix reference, reference/int
2r = Assigns the following value to the preceeding variable. postfix reference, reference/any

Explanation and examples:

Postfix or prefix?

This property of an operator determines whether it is used before (pre) or after (post) its parameter.
Prefix operators only have one parameter while postfix operators usually have two parameters (one preceeding and one following). See also operators ++/--.

Example 1:

Log(" Result: %d", 5 + 5);
Log(" Result: %d", 12 - 5);
Log(" Result: %d", 5 * 5);

Output:

 Result: 10
 Result: 7
 Result: 25
Addition, subtraction, multiplication, division, and similar form the group of postfix operators. They combine the two values preceeding and following the operator.

Example 2:

Log(" Result: %d", -(5 + 5));
Log(" Result: %d", ~7);
Log(" Result: %d", !0);

Output:

 Result: -10
 Result: -8
 Result: 1
Prefix operators are located before the value to which they are applied.

Operators ++ and --

Operators ++ and -- exist as both postfix and prefix operators. The postfix version of these operators does not have a second parameter.

Example 1 (postfix):

somevar = 0;
while(somevar++ < 10)
  Log("%d", somevar )

Example 2 (prefix):

somevar = 0;
while(++somevar < 10)
  Log("%d", somevar )
These two examples are almost identical. In both cases the value of somevar is increased by one per loop repetition. The result is compared to 10 in each case.
Yet there is an important difference between the two versions: when using the postfix version, the previous value of the variable is returned. The first example will result in a count from 1 to 10, since at beginning of the last loop repetition is value of somevar is 9. It is then increased by one (somevar is now 10) but the previous value of 9 is returned and compared to 10. Thus the loop will be repeated one more time and then the value of 10 is printed.
In the second example, on the other hand, the loop runs from 1 to 9. When somevar is 9 and is increased, the new value of 10 is returned immediately. The result is not less than 10 and the loop ends.

The Short-Circuiting Operators &&, || and ??

These operators are special. If the result can be determined by the first parameter alone, the second parameter is not computed at all. For example, this script does not explode an object, because the overall result would be false, regardless of the result of Explode:
0 && Explode(20);
Further, the result is the value of the first or second parameter, depending on whether one or both were evaluated. For example, one can create a knight if possible or else a Clonk:
CreateObject(Knight,0,0,GetOwner()) || CreateObject(Clonk,0,0,GetOwner())

The operator ??

The ?? operator is called the nil-coalescing operator. It can be used to specify a default value for an expression or function call that may evaluate to nil.

The equality operators ==, !=, === and !==

The shorter operators basically consider more things equal. For example, two arrays with the same contents are equal, but === only returns true when both sides of the operator contain the same array. This matters mostly when arrays or proplists are modified. Modification can change the return value of the ==/!= operators, but not of the ===/!== operators.

Priority and Associating

This subject shows how operator priority is evaluated in detail.
To calculate the result of a complex term, first we have to decide in which order to evaluate the individual operations and to which other operator the result is to be passed.
Generally, operators with a higher priority are evaluate before operators with a lower priority. Notice: this does not apply to the evaluation of parameters - those are normally evaluated from left to right.

Example:

Log("%d", 5 * 4 + 3 < 6);
evaluated as:
Log("%d", (((5 * 4) + 3) < 6));
Here we have another problem: what to do when 'neighbouring' operators have the same priority? Should we first process the left or the right term? This is decided by the so called associativity. If an operator is left-associative then the term on the left is evaluated first (this is the usual case). With right-associative operators the term on the right is evaluated first.

Example:

somevar = othervar = 1 + 2 + 3 + 4;
evaluated as:
somevar = (othervar = (((1 + 2) + 3) + 4) );
Here you can see that the operator "+" is left-associative, the term "1 + 2 + 3" is evaluated as "(1 + 2) + 3".
As opposed to this, the term "somevar = othervar = x" becomes "somevar = (othervar = x)", since the operator "=" is right-associative.
To find out about an operator's associativity, see the table above.

Bit Manipulation Operators

In the operator list you will have noticed some operators which perform bitwise operations or bit shift.
To start out, a short description of bits: any computer internally works with 'binary numbers'. In this system there are only two digits: 0 and 1. Humans, by the way, usually work with 10 digits: 0 to 9. With the binary system, number can be represented as follows:

The Binary System

(each number is presented in the decimal system first, then binary)
1 = 00000001
2 = 00000010
4 = 00000100
8 = 00001000
6 = 00000110
7 = 00000111
Each digit in the binary system is called a "bit". A sequence of 8 bits (see above) is called a "byte".
Bitwise operatiors perform actions on the bits of a number.

Example:

~00000000 = 11111111
~00000100 = 11111011
~01100000 = 10011111
This example shows a binary NOT. That means, each bit of the number is negated individually (0 becomes 1, 1 becomes 0).
Bitwise operators with two parameters combine the bits of two numbers.

Examples:

10010010
& 01110111
= 00010010
10010010
| 01110111
= 11110111
10010010
^ 01110111
= 11100101
These three operators are (in order) AND (&), OR (|) and EXCLUSIVE-OR (^).
With the AND operator, the resulting bit will only be 1 if both incoming bits are 1. AND gives the following result:
& 0 1
0 0 0
1 0 1
The OR operator results in 1 if one or both of the incoming bits are 1:
| 0 1
0 0 1
1 1 1
The XOR operator results in 1 if either (but not both) of the incoming bits are 1:
^ 0 1
0 0 1
1 1 0

Applications:

Clonk often uses bitwise operations when storing the characteristics of an object in a single value. The best known example is the category ("C4D" values) of an object. Here, each bit of the category value represents a certain class or characteristic.
To access or sort out the individual characteristics, you can easily access a C4D value with bitwise operators:

Example (wipf):

Category = 69640
This value in binary system:
10001000000001000
You can see that bit 3, 12, and 16 are set (counting from left to right, starting with 0).
This represents the C4D values C4D_Living (objects is a living being), C4D_SelectAnimal (living being can be selected in the menu system) and C4D_TradeLiving (living being can be bought or sold).
In script you can now easily check whether a given bit is set: simply use the AND operator (&) with a second parameter ("mask"). In this mask, only a single bit is set, representing the category value which we we like to test for. In the result of the AND operation all bits that do not interest us, will be 0. Only the one bit that does interest us, has the chance of being 1 - that is, if it is set in the original value. Since a single bit set in a number will already cause that number's value to be different from 0, all you have to do now is to compare the resulting number to 0: if it is different from 0, the characteristic we have been looking for is given; if the result is equal to 0, the characteristic is not given.

Example:

10001000000001000 (value)
& 00001000000000000 (mask)
= 00001000000000000
In this case, the result is unequal to 0, so we know the bit we have set in the mask is also set in the original value.
10001000000001000 (value)
& 00000000010000000 (mask)
= 00000000000000000
Here the result is equal to 0, meaning the bit we are looking for was not set in the original value.
The question remains where to get the proper mask from. In the case of the C4D categories, there are predefined values we can use. They are called C4D_xxx. So to find out whether an object is a living being we use the following code:
if (GetCategory() & C4D_Living)
  ;...;
Now we can test whether an individual bit is set. But how can we change bits, for example set them? For this, we can use the OR operator (|). Again, it is applied using a value and a mask as a second parameter:
10001000000001000 (value)
| 00000000010000000 (mask)
= 10001000010001000 (new value)
In this way it is only possible to set a certain bit to 1. If the bit was already set, the value will remain unchanged. To set a certain bit to 0 we have to use the AND operator and the inverse (logical NOT) mask, or [value] &~[mask].
10001000010001000 (value)
& 11111111101111111 (= ~00000000010000000)
= 10001000000001000 (new value)
It is also possibly to toggle a certain bit from 1 to 0 or 0 to 1, whichever way it is set. This is done with the XOR operator (^):
10001000000001000 (value)
^ 00000000010000000 (mask)
= 10001000010001000 (new value)
10001000010001000 (value)
^ 00000000010000000 (mask)
= 10001000000001000 (new value)

Bit Shifts

Besides operators for bitwise combination of values there are also the bit shift operators. All these operators do is move all the bits in a number from left to right (adding a new 0 on the left) or from right to left (adding a new 0 on the right).

Example:

  00001000000001000 << 2
= 00100000000100000

  00001000000001000 >> 2
= 00000010000000010
Mathematically, the operator << performs a multiplication by 2 (exactly in the same way that in the decimal system appending a 0 performs a multiplication by 10) and the operator >> is a division by 2 (including some rounding).
Using these operators you can put together masks (1 << bit-no.) and mix or take apart RGB color values.
PeterW,