NVSE Expressions

From GECK
Jump to: navigation, search

NVSE allows for complex expressions in the context of NVSE aware functions, such as Let, Eval and TestExpr, and when using Inline Expressions and the now deprecated 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: 

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.

Has a special Let macro:

Original Syntax
 Macro Equivalent
let iCount := 10. iCount = 10

More on such macros: Let Macro.

|| 1 Logical Or 2 True if either expression is true.
  • In the context of assignment, if the left-hand value is non-zero, that numeric value is returned. Otherwise, the right-hand numeric value is returned. If either of the two operands aren't numbers (i.e form, array, string), then they are converted to boolean values (1/0) should they be returned.

Example: 

int res

res = 1 || 2
printvar res  ;prints "res: 1"
	
res = 0 || 2
printvar res  ;prints "res: 2"

res = 0 || 0
printvar res  ;prints "res: 0"
    • NOTE: this behavior is different from the vanilla || operator, which only returns a boolean (1 or 0).
&& 2 Logical And 2 True if both expressions are true.
  • Since xNVSE 6.2.5: in the context of assignment, if the left-hand value is false (0), returns 0. Otherwise, returns the right-hand value's numeric value (converted to bool for non-numeric types).
let iTest := -5 && -5
print $iTest        ;* -5

let iTest := 1 && -5
print $iTest        ;* -5

let iTest := 0 && -5
print $iTest      ;* 0
    • NOTE: this behavior is different from the vanilla && operator, which only returns a boolean (1 or 0).
+= 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.
|= 2 Bitwise Or and Assign 2 Performs a Bitwise Or, demoting the operands to integers, and assigns the result to the variable on the left.
&= 2 Bitwise And and Assign 2 Performs a Bitwise And, demoting the operands to integers, and assigns the result to the variable on the left.
%= 2 Modulo and Assign 2 Calculates the remainder of integer division between the two operands and assigns the result to variable on the left.
: 3 Slice/Range 2 Specifies a range of elements in a string or array. For strings, creates a substring (see Sv SubString). For arrays, 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.

If both operands are arrays:

  • Before xNVSE 6.2.1:
    • Arrays were compared by their internal numeric IDs, and not their contents.
  • After xNVSE 6.2.1:
    • Arrays are now compared by their surface contents. If both arrays have the same contents, then they are said to be equal. However, if there are any sub-arrays in the operand arrays, those are compared via their numeric IDs. Use Ar_DeepEquals for comparing nested/multidimensional arrays.
!= 4 Inequality 2 True if the operands are not equal. See the Equality operator for more details.
> 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 the value 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 string containing 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"]'
. 15 Quest Variable Access / Reference Call 0 If the lefthand element is a reference and the righthand element is a function, the function will be called with the reference being attributed as its caller.

If the lefthand element is a Quest and the righthand element is a variable from that quest's script, will access that variable.

Also supports Chained dot syntax.

{ } 16 Function Args 0 Specifies the argument variables that the UDF or Lambda accepts.

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
    ...
loop

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

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

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

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

See Also

External Links

Retrieved from "https://geckwiki.com/index.php?title=NVSE_Expressions&oldid=30943"