NVSE Expressions

From GECK

NVSE allows for complex expressions in the context of NVSE aware functions, such as Let, Eval and TestExpr, and when using the Script Compiler Override. The following table details the permitted operators

Symbol Precedence Function Number of Operands Description
 := 0 Assignment 2 Assigns the value of an expression on the right to the variable or array element on the left. Right-associative. The value of the assignment is the right-most operand. Supports multiple assignment i.e. a := b := c := 0 sets all 3 variables to zero. Assignment of strings creates a copy of the string, whereas assignment of arrays creates a reference to the array.
| | 1 Logical Or 2 True if either expression is true.
&& 2 Logical And 2 True if both expressions are true.
+= 2 Add and Assign 2 Adds the expression on the right to the variable or array element on the left.
-= 2 Subtract and Assign 2 Subtracts the expression on the right from the variable or array element on the left.
*= 2 Multiply and Assign 2 Multiplies the variable or array element on the left by the expression on the right.
/= 2 Divide and Assign 2 Divides the variable or array element on the left by the expression on the right.
^= 2 Exponent and Assign 2 Raises the variable or array element on the left to the power of the expression on the right.
 : 3 Slice/Range 2 Specifies a range of elements in a string or array. For strings, creates a substring. Forarrays, creates a copy of the elements within the range. Range includes the upper element. For strings, negative indices start at the last element and count backwards.
 :: 3 Make Pair 2 Specifies a key-value pair. The lefthand operand defines the key as a numeric or string value, and the righthand operand defines the value (of any type).
== 4 Equality 2 True if the operands are equal. Operands must be comparable to each other.
 != 4 Inequality 2 True if the operands are not equal.
> 5 Greater Than 2 Operands must be comparable and ordered. For strings, comparison is case-insensitive.
< 5 Less Than 2 For strings, case-insensitive.
>= 5 Greater or Equal 2 For strings, case-insensitive.
<= 5 Less than or Equal 2 For strings, case-insensitive.
| 6 Bitwise Or 2 Performs a bitwise or, demoting the operands to integers.
& 7 Bitwise And 2 Performs a bitwise and, demoting the operands to integers.
<< 8 Binary Left Shift 2 Shifts left operand left by specified number of bits, demoting both operands to integers.
>> 8 Binary Right Shift 2 Shifts left operand right by specified number of bits, demoting both operands to integers.
+ 9 Addition/Concatentation 2 Adds two numbers or joins two strings.
- 9 Subtraction 2 Self-explanatory.
* 10 Multiplication 2 Self-explanatory.
/ 10 Division 2 Self-explanatory.
 % 10 Modulo 2 Returns the remainder of integer division.
^ 11 Exponentiation 2 Raises left operand to the power of the right operand.
- 12 Negation 1 Returns the opposite of an expression.
$ 12 Stringize 1 Returns a string representation of an expression. (Shorthand for ToString).
# 12 Numericize 1 Returns the numeric value of a string. (Shorthand for ToNumber).
* 12 Dereference/Unbox 1 Dereferences an array. If the array is a StringMap with a "value" key, returns thevalue associated with that key. Otherwise returns the value of the first element.
& 12 Box 1 "Boxes" a value of any type, returning an Array containing that value as its only element. The value can be retrieved with the unary * (unbox) operator.
 ! 13 Logical Not 1 Returns the opposite of a boolean expression. i.e. !(true) evaluates to false.
( ) 14 Parentheses 0 Enclose expressions within parentheses to override default precedence rules.
[ ] 15 Subscript 2 For arrays, accesses the element having the specified key. For strings, returns a stringcontaining the single character at the specified position. The expression within the brackets is treated as if it were parenthesized (overrides precedence rules).
-> 15 Member Access 2 The lefthand operand is a StringMap having a key specified by the righthand operand. Returns the value associated with that key. Example: 'dict->key' is equivalent to 'dict["key"]'

A Few Examples

; assign a variable
let MyInt := 5

; reference a single entry from an array, or character from a string
my_array[4] ; * element at index 4

; reference a substring of a string_var (or sub array)
let my_string := "this is my full string"
my_string[0:3] == "this"
my_string[-6:-1] == "string" ; * you can use negative indices to reference via the end

; * concatanate strings, use the stringize operator, and nested functions:
Print "this is sunny's name: " + $SunnyREF + " and a nested function too: " + $(GetNVSEVersion)

; 'this is sunny's name: Sunny Smiles and a nested function too: 4'

while (x += 1) < 5 ; increment x, then loop if less then 5
    ...

if TestExpr MyRef := MyArray[x] ; assign MyRef to array element x, if this index exists 
   ...

if eval !(SunnyREF.GetDead) ; if sunny is not dead
   ...

foreach entry <- SomeArray
   let MyRef := *entry     ; 'Unbox' is equivalent to using entry["value"]
   ...

; boxing a ref into a single entry array allows passage as an argument of this type:
call MyUDF &MyRef 

See Also

External Links

Personal tools