====== add ======

===== Description =====

Add two numbers.

===== Function prototype =====

<code>
variant add <variant:Var1> <variant:Var2>
</code>


===== Arguments =====

^  Name  ^  Type  ^ Comment ^
|  //arg1//  |  variant  | The first number to be added. |
|  //arg2//  |  variant  | The second number to be added. |

<note important>
If the type of //arg1// is not equal to that of //arg2//, the ordering of the arguments may change the result of calls to ''add''. See [[#Algebra of variables of dissimilar types]].
</note>

===== Return value =====

The sum of //arg1// and //arg2//, in the data type of //arg1//.

===== Example =====

<code>
float f
set f 50.1

echo <zs:add f 20>
</code>

... the output of which is written to the event log by [[plugins:general:zeoscript:reference:functions:echo]] as:

<file>
70.1
</file>

===== Comments =====


==== Algebra of variables of dissimilar types ====

If the type of //arg2// is different to that of //arg1//, //arg2// will be typecast to the type of //arg1//. Thus, in certain circumstances, the the result of ''add'' will be different if the argument order is swapped, even if the values are unchanged.

For example, consider the case of adding a float (//f// = 4.5) and an integer (//i// = 4):

<code>
float f
int i

set f 4.5
set i 4

echo <zs: add f i> // 'f' goes first, so comparing as floats
echo <zs: add i f> // 'i' goes first, so comparing as integers
</code>

The result of this code is:

<file>
8.5
8
</file>

In the first addition in the above script (''echo <add f i>''), the first argument is a float (//f// = 4.5) so the second argument (//i// = 4) will be typecast to a float with the value of 4.0. The sum of 4.5 and 4.0 is 8.5.

In the second addition in the above script (''echo <add i f>''), the first argument is a integer (//i// = 4) so the second argument (//f// = 4.5) will be typecast to an integer with the value of 4. The sum of 4 and 4 is 8.

The moral of the story is: when performing algebraic operations on variables, consider the type of the variables when deciding the argument order.

===== See also =====

  * [[plugins:general:zeoscript:reference:functions:sub]]
  * [[plugins:general:zeoscript:reference:functions:mul]]
  * [[plugins:general:zeoscript:reference:functions:div]]
  * [[plugins:general:zeoscript:reference:functions:mod]]
  * [[plugins:general:zeoscript:reference:functions:incr]]
  * [[plugins:general:zeoscript:reference:functions:decr]]