<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Operators</title>
  <h>Operators</h>
  <part>
    <text>C4Script nowadays supports most operators known from other programming languages (C/C++ style) or mathematics.</text>
    <text>The usual operator priority applies (multiplication before addition and similar). For further information, see the table below.</text>
    <text>Use brackets to force a specific operator priority.</text>
    <text>The following operators are supported:</text>
    <text>
      <table>
        <rowh>
          <col>Priority</col>
          <col>Operator</col>
          <col>Description</col>
          <col>Location</col>
          <col>Type (resulting, expected)</col>
        </rowh>
        <row>
          <col>15</col>
          <col id="++">++</col>
          <col>Increases the value of the <strong>following</strong> variable by 1.</col>
          <col>prefix</col>
          <col>reference, reference</col>
        </row>
        <row>
          <col>15</col>
          <col id="--">--</col>
          <col>Decreases the value of the <strong>following</strong> variable by 1.</col>
          <col>prefix</col>
          <col>reference, reference</col>
        </row>
        <row>
          <col>15</col>
          <col id="~">~</col>
          <col>Bitwise negation of the following value.</col>
          <col>prefix</col>
          <col>int, int</col>
        </row>
        <row>
          <col>15</col>
          <col id="!">!</col>
          <col>Logical negation of the following value.</col>
          <col>prefix</col>
          <col>bool, bool</col>
        </row>
        <row>
          <col>15</col>
          <col>+</col>
          <col>no effect (compatibility for terms such as "+5")</col>
          <col>prefix</col>
          <col>int, int</col>
        </row>
        <row>
          <col>15</col>
          <col>-</col>
          <col>Yields the reciprocal of the following value.</col>
          <col>prefix</col>
          <col>int, int</col>
        </row>
        <row>
          <col>15</col>
          <col>++</col>
          <col>Increases the value of the <strong>preceding</strong> variable by 1.</col>
          <col>postfix (only one parameter)</col>
          <col>int, reference</col>
        </row>
        <row>
          <col>15</col>
          <col>--</col>
          <col>Decreases the value of the <strong>preceding</strong> variable by 1.</col>
          <col>postfix (only one parameter)</col>
          <col>int, reference</col>
        </row>
        <row>
          <col>14l</col>
          <col id="**">**</col>
          <col>Yields the power of a to b.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>13l</col>
          <col id="/">/</col>
          <col>Divides a by b.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>13l</col>
          <col id="*">*</col>
          <col>Multiplies a by b.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>13l</col>
          <col id="%">%</col>
          <col>Yields the remainder of the devision of a by b.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>12l</col>
          <col id="-">-</col>
          <col>Subtracts b from a.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>12l</col>
          <col id="+">+</col>
          <col>Adds a to b.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>11l</col>
          <col id="&lt;&lt;">&lt;&lt;</col>
          <col>Performs a bit shift operation to the left.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>11l</col>
          <col id="&gt;&gt;">&gt;&gt;</col>
          <col>Performs a bit shift operation to the right.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>10l</col>
          <col id="&lt;">&lt;</col>
          <col>Returns whether a is less than b.</col>
          <col>postfix</col>
          <col>bool, int/int</col>
        </row>
        <row>
          <col>10l</col>
          <col id="&lt;=">&lt;=</col>
          <col>Returns whether a is less than or equal to b.</col>
          <col>postfix</col>
          <col>bool, int/int</col>
        </row>
        <row>
          <col>10l</col>
          <col id="&gt;">&gt;</col>
          <col>Returns whether a is greater than b.</col>
          <col>postfix</col>
          <col>bool, int/int</col>
        </row>
        <row>
          <col>10l</col>
          <col id="&gt;=">&gt;=</col>
          <col>Returns whether the first value is greater than or equal to the second.</col>
          <col>postfix</col>
          <col>bool, int/int</col>
        </row>
        <row>
          <col>9l</col>
          <col id="==">==</col>
          <col>Returns whether a equals b. For proplists and arrays, pointers are compared. Use <funclink>DeepEqual</funclink> to compare contents.</col>
          <col>postfix</col>
          <col>bool, any/any</col>
        </row>
        <row>
          <col>9l</col>
          <col id="!=">!=</col>
          <col>Returns whether a is unequal to b. For proplists and arrays, pointers are compared. Use !<funclink>DeepEqual</funclink> to compare contents.</col>
          <col>postfix</col>
          <col>bool, any/any</col>
        </row>
        <row>
          <col>8l</col>
          <col id="&amp;">&amp;</col>
          <col>Performs a bitwise AND operation.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>6l</col>
          <col id="^">^</col>
          <col>Performs a bitwise XOR operation.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>6l</col>
          <col id="|">|</col>
          <col>Performs a bitwise OR operation.</col>
          <col>postfix</col>
          <col>int, int/int</col>
        </row>
        <row>
          <col>5l</col>
          <col id="&amp;&amp;">&amp;&amp;</col>
          <col>Performs a logical AND operation.</col>
          <col>postfix</col>
          <col>any, any/any</col>
        </row>
        <row>
          <col>4l</col>
          <col id="||">||</col>
          <col>Performs a logical OR operation.</col>
          <col>postfix</col>
          <col>any, any/any</col>
        </row>
        <row>
          <col>3l</col>
          <col id="??">??</col>
          <col>Returns the left-hand operand if the operand is not <code>nil</code>, or the right-hand operand otherwise.</col>
          <col>postfix</col>
          <col>any, any/any</col>
        </row>
        <row>
          <col>2r</col>
          <col id="*=">*=</col>
          <col>Multiplies the preceeding variables by the following value.</col>
          <col>postfix</col>
          <col>reference, reference/int</col>
        </row>
        <row>
          <col>2r</col>
          <col id="/=">/=</col>
          <col>Divides the preceeding variable by the following value.</col>
          <col>postfix</col>
          <col>reference, reference/int</col>
        </row>
        <row>
          <col>2r</col>
          <col id="%=">%=</col>
          <col>Sets the preceeding variable to the remainder of the devision of that variable by the following value.</col>
          <col>postfix</col>
          <col>reference, reference/int</col>
        </row>
        <row>
          <col>2r</col>
          <col id="+=">+=</col>
          <col>Increases the preceeding variable by the following value.</col>
          <col>postfix</col>
          <col>reference, reference/int</col>
        </row>
        <row>
          <col>2r</col>
          <col id="-=">-=</col>
          <col>Decreases the preeceding variable by the following value.</col>
          <col>postfix</col>
          <col>reference, reference/int</col>
        </row>
        <row>
          <col>2r</col>
          <col id="=">=</col>
          <col>Assigns the following value to the preceeding variable.</col>
          <col>postfix</col>
          <col>reference, reference/any</col>
        </row>
      </table>
    </text>
    <h id="operk">Explanation and examples:</h>
    <part>
      <h>Postfix or prefix?</h>
      <part>
        <text>This property of an operator determines whether it is used <em>before</em> (pre) or <em>after</em> (post) its parameter.</text>
        <text>Prefix operators only have one parameter while postfix operators usually have two parameters (one preceeding and one following). See also <a href="#opppmm">operators ++/--</a>.</text>
        <h>Example 1:</h>
        <code>Log(&quot; Result: %d&quot;, 5 + 5);
Log(&quot; Result: %d&quot;, 12 - 5);
Log(&quot; Result: %d&quot;, 5 * 5);</code>
        <h>Output:</h>
        <code> Result: 10
 Result: 7
 Result: 25</code>
        <text>Addition, subtraction, multiplication, division, and similar form the group of postfix operators. They combine the two values preceeding and following the operator.</text>
        <h>Example 2:</h>
        <code>Log(&quot; Result: %d&quot;, -(5 + 5));
Log(&quot; Result: %d&quot;, ~7);
Log(&quot; Result: %d&quot;, !0);</code>
        <h>Output:</h>
        <code> Result: -10
 Result: -8
 Result: 1</code>
        <text>Prefix operators are located before the value to which they are applied.</text>
      </part>
      <h id="opppmm">Operators ++ and --</h>
      <part>
        <text>Operators ++ and -- exist as both postfix and prefix operators. The postfix version of these operators does not have a second parameter.</text>
        <h>Example 1 (postfix):</h>
        <code>somevar = 0;
while(<strong>somevar++</strong> &lt; 10)
  Log(&quot;%d&quot;, somevar )</code>
        <h>Example 2 (prefix):</h>
        <code>somevar = 0;
while(<strong>++somevar</strong> &lt; 10)
  Log(&quot;%d&quot;, somevar )</code>
        <text>These two examples are almost identical. In both cases the value of <code>somevar</code> is increased by one per loop repetition. The result is compared to 10 in each case.</text>
        <text>Yet there is an important difference between the two versions: when using the postfix version, the <strong>previous</strong> value of the variable is returned. The first example will result in a count from 1 to <strong>10</strong>, since at beginning of the last loop repetition is value of <code>somevar</code> is 9. It is then increased by one (<code>somevar</code> 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.</text>
        <text>In the second example, on the other hand, the loop runs from 1 to <strong>9</strong>. When <code>somevar</code> is 9 and is increased, the new value of 10 is returned immediately. The result is not less than 10 and the loop ends.</text>
      </part>
      <h id="shortcircuiting">The Short-Circuiting Operators &amp;&amp;, || and ??</h>
      <part>
        <text>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 <code>false</code>, regardless of the result of Explode:</text>
        <code>0 &amp;&amp; Explode(20);</code>
        <text>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:</text>
        <code>CreateObject(Knight,0,0,GetOwner()) || CreateObject(Clonk,0,0,GetOwner())</code>
      </part>
      <h id="nilcoalesce">The operator <code>??</code></h>
      <part>
        <text>The <code>??</code> 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 <code>nil</code>.</text>
      </part>
      <h id="equality">The equality operators <code>==</code>, <code>!=</code>, <code>===</code> and <code>!==</code></h>
      <part>
        <text>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 <code>==</code>/<code>!=</code> operators, but not of the <code>===</code>/<code>!==</code> operators.</text>
      </part>
      <h id="prio">Priority and Associating</h>
      <part>
        <text>This subject shows how operator priority is evaluated in detail.</text>
        <text>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.</text>
        <text>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.</text>
        <h>Example:</h>
        <code>Log(&quot;%d&quot;, 5 * 4 + 3 &lt; 6);</code>
        <text>evaluated as:</text>
        <code>Log(&quot;%d&quot;, (((5 * 4) + 3) &lt; 6));</code>
        <text>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.</text>
        <h>Example:</h>
        <code>somevar = othervar = 1 + 2 + 3 + 4;</code>
        <text>evaluated as:</text>
        <code>somevar = (othervar = (((1 + 2) + 3) + 4) );</code>
        <text>Here you can see that the operator "+" is left-associative, the term "<code>1 + 2 + 3</code>" is evaluated as "<code>(1 + 2) + 3</code>".</text>
        <text>As opposed to this, the term "<code>somevar = othervar = x</code>" becomes "<code>somevar = (othervar = x)</code>", since the operator "=" is right-associative.</text>
        <text>To find out about an operator's associativity, see the table above.</text>
      </part>
      <h id="Bitweise">Bit Manipulation Operators</h>
      <text>In the operator list you will have noticed some operators which perform bitwise operations or bit shift.</text>
      <text>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:</text>
      <h id="binary">The Binary System</h>
      <part>
        <text>(each number is presented in the decimal system first, then binary)</text>
        <code>1 = 00000001
2 = 00000010
4 = 00000100
8 = 00001000
6 = 00000110
7 = 00000111</code>
        <text>Each digit in the binary system is called a "bit". A sequence of 8 bits (see above) is called a "byte".</text>
        <text>Bitwise operatiors perform actions on the bits of a number.</text>
        <h>Example:</h>
        <code>~00000000 = 11111111
~00000100 = 11111011
~01100000 = 10011111</code>
        <text>This example shows a binary NOT. That means, each bit of the number is negated individually (0 becomes 1, 1 becomes 0).</text>
        <text>Bitwise operators with two parameters combine the bits of two numbers.</text>
        <h>Examples:</h>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10010010</code></col>
            </row>
            <row>
              <col><code>&amp;</code></col>
              <col><code>01110111</code></col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>00010010</code></col>
            </row>
          </table>
        </text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10010010</code></col>
            </row>
            <row>
              <col><code>|</code></col>
              <col><code>01110111</code></col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>11110111</code></col>
            </row>
          </table>
        </text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10010010</code></col>
            </row>
            <row>
              <col><code>^</code></col>
              <col><code>01110111</code></col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>11100101</code></col>
            </row>
          </table>
        </text>
        <text>These three operators are (in order) AND (&amp;), OR (|) and EXCLUSIVE-OR (^).</text>
        <text>With the AND operator, the resulting bit will only be 1 if both incoming bits are 1. AND gives the following result:</text>
        <text>
          <table>
            <row>
              <col><code>&amp;</code></col>
              <col>0</col>
              <col>1</col>
            </row>
            <row>
              <col>0</col>
              <col>0</col>
              <col>0</col>
            </row>
            <row>
              <col>1</col>
              <col>0</col>
              <col>1</col>
            </row>
          </table>
        </text>
        <text>The OR operator results in 1 if one or both of the incoming bits are 1:</text>
        <text>
          <table>
            <row>
              <col><code>|</code></col>
              <col>0</col>
              <col>1</col>
            </row>
            <row>
              <col>0</col>
              <col>0</col>
              <col>1</col>
            </row>
            <row>
              <col>1</col>
              <col>1</col>
              <col>1</col>
            </row>
          </table>
        </text>
        <text>The XOR operator results in 1 if either (but not both) of the incoming bits are 1:</text>
        <text>
          <table>
            <row>
              <col><code>^</code></col>
              <col>0</col>
              <col>1</col>
            </row>
            <row>
              <col>0</col>
              <col>0</col>
              <col>1</col>
            </row>
            <row>
              <col>1</col>
              <col>1</col>
              <col>0</col>
            </row>
          </table>
        </text>
        <h>Applications:</h>
        <text>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.</text>
        <text>To access or sort out the individual characteristics, you can easily access a C4D value with bitwise operators:</text>
        <h>Example (wipf):</h>
        <code>Category = 69640</code>
        <text>This value in binary system:</text>
        <code>10001000000001000</code>
        <text>You can see that bit 3, 12, and 16 are set (counting from left to right, starting with 0).</text>
        <text>This represents the C4D values <funclink>C4D_Living</funclink> (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).</text>
        <text>In script you can now easily check whether a given bit is set: simply use the AND operator (&amp;) 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.</text>
        <h>Example:</h>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000000001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>&amp;</code></col>
              <col><code>00001000000000000</code></col>
              <col>(mask)</col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>00001000000000000</code></col>
              <col></col>
            </row>
          </table>
        </text>
        <text>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.</text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000000001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>&amp;</code></col>
              <col><code>00000000010000000</code></col>
              <col>(mask)</col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>00000000000000000</code></col>
              <col></col>
            </row>
          </table>
        </text>
        <text>Here the result is equal to 0, meaning the bit we are looking for was not set in the original value.</text>
        <text>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 <code>C4D_xxx</code>. So to find out whether an object is a living being we use the following code:</text>
        <code>if (<funclink>GetCategory</funclink>() &amp; <funclink>C4D_Living</funclink>)
  ;...;</code>
        <text>Now we can test whether an individual bit is set. But how can we change bits, for example <strong>set</strong> them? For this, we can use the OR operator (|). Again, it is applied using a value and a mask as a second parameter:</text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000000001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>|</code></col>
              <col><code>00000000010000000</code></col>
              <col>(mask)</col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>10001000010001000</code></col>
              <col>(new value)</col>
            </row>
          </table>
        </text>
        <text>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 <strong>inverse</strong> (logical NOT) mask, or <code>[value] &amp;~[mask]</code>.</text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000010001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>&amp;</code></col>
              <col><code>11111111101111111</code></col>
              <col><code>(= ~00000000010000000)</code></col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>10001000000001000</code></col>
              <col>(new value)</col>
            </row>
          </table>
        </text>
        <text>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 (^):</text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000000001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>^</code></col>
              <col><code>00000000010000000</code></col>
              <col>(mask)</col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>10001000010001000</code></col>
              <col>(new value)</col>
            </row>
          </table>
        </text>
        <text>
          <table>
            <row>
              <col></col>
              <col><code>10001000010001000</code></col>
              <col>(value)</col>
            </row>
            <row>
              <col><code>^</code></col>
              <col><code>00000000010000000</code></col>
              <col>(mask)</col>
            </row>
            <row>
              <col><code>=</code></col>
              <col><code>10001000000001000</code></col>
              <col>(new value)</col>
            </row>
          </table>
        </text>
      </part>
      <h id="bitmove">Bit Shifts</h>
      <part>
        <text>Besides operators for bitwise combination of values there are also the <strong>bit shift</strong> 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).</text>
        <h>Example:</h>
        <code>  00001000000001000 &lt;&lt; 2
= 00100000000100000

  00001000000001000 &gt;&gt; 2
= 00000010000000010</code>
        <text>Mathematically, the operator &lt;&lt; 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 &gt;&gt; is a division by 2 (including some rounding).</text>
        <text>Using these operators you can put together masks (1 &lt;&lt; bit-no.) and mix or take apart <funclink>RGB</funclink> color values.</text>
      </part>
    </part>
  </part>
  <author>PeterW</author></doc>