Operators

Operators 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: PriorityOperatorDescriptionLocationType (resulting, expected) 15++Increases the value of the following variable by 1.prefixreference, reference 15--Decreases the value of the following variable by 1.prefixreference, reference 15~Bitwise negation of the following value.prefixint, int 15!Logical negation of the following value.prefixbool, bool 15+no effect (compatibility for terms such as "+5")prefixint, int 15-Yields the reciprocal of the following value.prefixint, 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.postfixint, int/int 13l/Divides a by b.postfixint, int/int 13l*Multiplies a by b.postfixint, int/int 13l%Yields the remainder of the devision of a by b.postfixint, int/int 12l-Subtracts b from a.postfixint, int/int 12l+Adds a to b.postfixint, int/int 11l<<Performs a bit shift operation to the left.postfixint, int/int 11l>>Performs a bit shift operation to the right.postfixint, int/int 10l<Returns whether a is less than b.postfixbool, int/int 10l<=Returns whether a is less than or equal to b.postfixbool, int/int 10l>Returns whether a is greater than b.postfixbool, int/int 10l>=Returns whether the first value is greater than or equal to the second.postfixbool, int/int 9l==Returns whether a equals b. For proplists and arrays, pointers are compared. Use DeepEqual to compare contents.postfixbool, any/any 9l!=Returns whether a is unequal to b. For proplists and arrays, pointers are compared. Use !DeepEqual to compare contents.postfixbool, any/any 8l&Performs a bitwise AND operation.postfixint, int/int 6l^Performs a bitwise XOR operation.postfixint, int/int 6l|Performs a bitwise OR operation.postfixint, int/int 5l&&Performs a logical AND operation.postfixany, any/any 4l||Performs a logical OR operation.postfixany, any/any 3l??Returns the left-hand operand if the operand is not nil, or the right-hand operand otherwise.postfixany, any/any 2r*=Multiplies the preceeding variables by the following value.postfixreference, reference/int 2r/=Divides the preceeding variable by the following value.postfixreference, reference/int 2r%=Sets the preceeding variable to the remainder of the devision of that variable by the following value.postfixreference, reference/int 2r+=Increases the preceeding variable by the following value.postfixreference, reference/int 2r-=Decreases the preeceding variable by the following value.postfixreference, reference/int 2r=Assigns the following value to the preceeding variable.postfixreference, 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: &01 000 101

The OR operator results in 1 if one or both of the incoming bits are 1: |01 001 111

The XOR operator results in 1 if either (but not both) of the incoming bits are 1: ^01 001 110

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