Editing Operator Reference

The following are valid operators in the Papyrus language:

 () [] ,  =  +  -
 *  /  %  .  "" !
 == != >  <  >= <=
 || && += -= *= /=
 %= as is

== Parenthesis ==
 ()
Parenthesis, when surrounding an [[Expression Reference|expression]], will cause that expression to be evaluated before any operators outside of the parenthesis. When following a [[Function Reference|function]] name, they denote the parameter list for the function.

Examples:
<source lang="papyrus">
; i will get the value of 9
i = (1 + 2) * 3
</source>
<br>
<source lang="papyrus">
; call the function MyFunction with a parameter of 10
MyFunction(10)
</source>

== Square Brackets ==
 []
Square brackets are used for [[Array Reference|arrays]]. Either for accessing a specific array element, denoting the size of an array for a new one, or for denoting that a type is an array type.

Examples:
<source lang="papyrus">
; i whatever is in element 0 of the array
i = myArray[0]
</source>
<br>
<source lang="papyrus">
; define an array of size 10
int[] myArray = new int[10]
</source>

== Comma ==
 ,
The comma operator separates parameters in a [[Function Reference|function]] definition, or a function call.

Examples:
<source lang="papyrus">
; call the function MyFunction with a parameter of 10 and 20
MyFunction(10, 20)
</source>

== Math Operators ==
 + - * / %
Math operators perform some sort of operation on the two [[Expression Reference|expressions]] it sits between. Papyrus supports assignment, addition, subtraction, multiplication, division, and integer modulus. The minus sign is also used for negation (also known as unary minus). The addition operator can also be used to concatenate ('paste together') strings.

Examples:
<source lang="papyrus">
; i will get the value of 7
i = 1 + 2 * 3
</source>
<br>
<source lang="papyrus">
; i will get the value of 1
i = 9 % 4
</source>
<br>
<source lang="papyrus">
; i will get the string "Hello World"
i = "Hello " + "World"
</source>

Note:
* Modulous unreliable for values greater than 0x80000000
* Code that uses modulous to manually isolate the low-order 3 bytes (6 nibbles) of a form ID will fail if the user has more than 127 mods installed.

<source lang="papyrus">
int ex1 = (0x7fffffff % 0x01000000) ; =  0x00ffffff as expected
int ex2 = (0x80000000 % 0x01000000) ; =  0x00000000 as expected 
int ex3 = (0x80000001 % 0x01000000) ; = -0x00ffffff, not expected
int ex4 = (0x80000002 % 0x01000000) ; = -0x00fffffe, not expected
</source>

== Dot ==
 .
The dot operator goes after a variable name to let you call [[Function Reference|functions]] on it, or to access [[Property Reference|properties]] or [[Struct Reference#Struct Members|struct members]].

Examples:
<source lang="papyrus">
; Call the function on the variable
myVariable.MyFunction()
</source>
<br>
<source lang="papyrus">
; Set the property to 10
myVariable.MyProperty = 10
</source>

== Double Quotes ==
 ""
Double quotes surround a [[Literals Reference#String Literals|string literal]].

Examples:
<source lang="papyrus">
; A basic hello world string
hello = "Hello World!"
</source>

== Logical Operators ==
 ! || &&
Logical operators evaluate to true or false values, based on their [[Expression Reference|expressions]].
*The NOT operator (!) will be true if its single expression (to the left of the operator) is false, and false if it is true.
*The OR operator (||) will be true if one of the expressions to its left and right are true, and will short-circuit if the left expression is true (it will not evaluate the right expression at all).
*The AND operator (&&) will be true if both of the expressions to its left and right are true, and will short-circuit if the left expression is false (it will not evaluate the right expression at all).

Examples:
<source lang="papyrus">
; i gets true if both a and b are true
i = a && b
</source>
<br>
<source lang="papyrus">
; i gets true if a is false
i = !a
</source>

== Comparison Operators ==
 == != < > <= >=
The comparison operators compare both [[Expression Reference|expressions]] to their left and right, and return a boolean value based on the operator used. If floating-point values are being compared, a tiny epsilon value is accounted for to conteract floating-point error. If string variables are being compared, the comparison is case-insensitive.
*Equality (==) returns true if both expressions have equal values.
*Inequality (!=) returns true if both expressions have inequal values.
*Less-than (<) returns true if the right expression's value is smaller then the left expression's value.
*Greater-than (>) returns true if the right expression's value is larger then the left expression's value.
*Less-than or equal to (<=) returns true if the right expression's value is smaller than or equal to the left expression's value.
*Greater-than or equal to (>=) returns true if the right expression's value is larger than or equal to the left expression's value.

Examples:
<source lang="papyrus">
; i will get true if a is greater then b
i = a > b
</source>
<br>
<source lang="papyrus">
; i will get true if a is equal to b
i = a == b
</source>

== Assignment Operators ==
 = += -= *= /= %=
Assignment operators assign the value from the right [[Expression Reference|expression]] to the [[Variable Reference|variable]] (or [[Property Reference|property]]) from the left expression. If the equal sign starts with one of the math operators, then the right expression's value will be added to the current value of the left expression, and then assigned to the left expression. Note that if the left expression is a property, then both the property's get and set functions will be called.

Examples:
<source lang="papyrus">
; assign 10 to i
i = 10
</source>
<br>
<source lang="papyrus">
; add 1 to the current value of i, and assign it to i
i += 1
</source>

== Cast ==
 as
The [[Cast Reference|cast]] operator attempts to cast the value from the left [[Expression Reference|expression]] to the type to the right of it, and returns the resulting value.

Examples:
<source lang="papyrus">
; cast a to a float and assign it to i
i = a as float
</source>

== Type Check ==
 is
The [[Cast Reference|type check]] operator checks to see if the value from the left [[Expression Reference|expression]] is the type specified to the right of it, and returns true or false. If the type is a base type, like int, bool, or float, the check is strict and will only return true if the type exactly matches (a float is not an int, for example). If the type is an object type, then the check is loose and will return true if the object would be successfully cast to the type (an ObjectReference is a Form).

Examples:
<source lang="papyrus">
; check to see if myObject is an ObjectReference
if myObject is ObjectReference
  Debug.Trace("I got an object reference!")
endIf
</source>

== Operator Precedence ==
Operator precedence is listed in the following table, from highest to lowest:
{| class="wikitable"
|-
| ()
| Mathematical parenthesis
|-
| .
| Dot operator (for accessing functions and properties)
|-
| as is
| Cast operators
|-
| - !
| Unary minus and logical NOT
|-
| * / %
| Multiplication, division, and modulus
|-
| + -
| Addition and subtraction
|-
| == != > < >= <=
| Comparison operators
|-
| &&
| Logical AND
|-
| &#124;&#124;
| Logical OR
|-
| = += -= *= /= %=
| Assignment
|}

[[Category:Scripting]]
[[Category:Papyrus]]
[[Category:Papyrus Language Reference]]
@@ Line 67: / Line 67: @@
 </source>
-=== Note ===
+Note:
+* Modulous unreliable for values greater than 0x80000000
-In the past, there was concern about the correctness of the [https://en.wikipedia.org/wiki/Modulo_operation modulo] (<code>%</code>) operator when applied to negative integers such as -2,147,483,647 (0x80000001). Those concerns were unfounded.
+* Code that uses modulous to manually isolate the low-order 3 bytes (6 nibbles) of a form ID will fail if the user has more than 127 mods installed.
-''The modulo operator produces correct results in all cases'', but it must be understood that the result will have the sign of the dividend in Papyrus (as in Java and many other languages), therefore <code>3 % 2 == 1</code> and <code>-3 % 2 == -1</code>.
-A specific case of concern was the calculation necessary to isolate the low-order 3 bytes (6 nibbles, or 24 bits) of an integer, which requires a modulo operation with a divisor of 2^24 (AKA 0x01000000 or 16,777,216). When that modulo operation is applied to dividends in the range -2,147,483,647 (0x80000001) to -1 (0xFFFFFFFF), inclusive, the results correctly range from -16,777,215 (0xFF000001) to -1 (0xFFFFFFFF). However, the goal of isolating the low-order 3 bytes of the integer (performing an operation equivalent to a bit-wise AND with 0x00FFFFFF) is ''not'' met in those cases. In order to meet that goal, negative values must be handled specially. For example:
-<source lang="papyrus">
-int Function getLow3Bytes(int i)
-{Set the high 8 bits of i to zero, and return the low 24 bits intact.
- Equivalent to "i & 0x00FFFFFF" in C, Java, etc.}
-    if i < 0
-        ; Force i to be a positive number, by changing its high bit (bit 32) from 1 to 0.
-        i += 0x80000000
-    endIf
-    return i % 0x01000000
-EndFunction
-</source>
-Such emulation of bit-wise operations using mathematical operations is a little more complicated when the high bit must be preserved:
 <source lang="papyrus">
-int Function getHighByteAsLowByte(int i)
+int ex1 = (0x7fffffff % 0x01000000) ; =  0x00ffffff as expected
-{Return the high byte of i as a value between 0 and 255 (0x00-0xFF), inclusive.
+int ex2 = (0x80000000 % 0x01000000) ; =  0x00000000 as expected
-  Equivalent to "i >> 24 & 0xFF" in C, Java, etc.}
+int ex3 = (0x80000001 % 0x01000000) ; = -0x00ffffff, not expected
-    if i < 0
+int ex4 = (0x80000002 % 0x01000000) ; = -0x00fffffe, not expected
-        ; Force i to be a positive number, by changing its high bit (bit 32) from 1 to 0.
-        ; Then divide by 0x01000000 (16,777,216), which is now equivalent to a right shift of 24 bits.
-        ; Finally, restore the value of the high bit we cleared, now that it is bit 8 and cannot affect the sign.
-        return (i + 0x80000000) / 0x01000000 + 0x80
-    endIf
-    return i / 0x01000000
-EndFunction
 </source>