[[painless-operators-general]] === Operators: General [[precedence-operator]] ==== Precedence Use the `precedence operator '()'` to guarantee the order of evaluation for an expression. An expression encapsulated by the precedence operator (enclosed in parentheses) overrides existing precedence relationships between operators and is evaluated prior to other expressions in inward-to-outward order. *Grammar* [source,ANTLR4] ---- precedence: '(' expression ')'; ---- *Examples* * Precedence with numeric operators. + [source,Painless] ---- int x = (5+4)*6; <1> int y = 12/(x-50); <2> ---- + <1> declare `int x`; add `int 5` and `int 4` -> `int 9`; multiply `int 9` and `int 6` -> `int 54`; store `int 54` to `x`; (note the add is evaluated before the multiply due to the precedence operator) <2> declare `int y`; load from `x` -> `int 54`; subtract `int 50` from `int 54` -> `int 4`; divide `int 12` by `int 4` -> `int 3`; store `int 3` to `y`; (note the subtract is evaluated before the divide due to the precedence operator) [[function-call-operator]] ==== Function Call Use the `function call operator ()` to call an existing function. A <> is defined within a script. *Grammar* [source,ANTLR4] ---- function_call: ID '(' ( expression (',' expression)* )? ')''; ---- *Examples* * A function call. + [source,Painless] ---- int add(int x, int y) { <1> return x + y; } int z = add(1, 2); <2> ---- + <1> define function `add` that returns `int` and has parameters (`int x`, `int y`) <2> declare `int z`; call `add` with arguments (`int 1`, `int 2`) -> `int 3`; store `int 3` to `z` [[cast-operator]] ==== Cast An explicit cast converts the value of an original type to the equivalent value of a target type forcefully as an operation. Use the `cast operator '()'` to specify an explicit cast. Refer to <> for more information. [[conditional-operator]] ==== Conditional A conditional consists of three expressions. The first expression is evaluated with an expected boolean result type. If the first expression evaluates to true then the second expression will be evaluated. If the first expression evaluates to false then the third expression will be evaluated. The second and third expressions will be <> if the evaluated values are not the same type. Use the `conditional operator '? :'` as a shortcut to avoid the need for a full if/else branch in certain expressions. *Errors* * If the first expression does not evaluate to a boolean type value. * If the values for the second and third expressions cannot be promoted. *Grammar* [source,ANTLR4] ---- conditional: expression '?' expression ':' expression; ---- *Promotion* [cols="<1,^1,^1,^1,^1,^1,^1,^1,^1,^1"] |==== | | byte | short | char | int | long | float | double | Reference | def | byte | int | int | int | int | long | float | double | - | def | short | int | int | int | int | long | float | double | - | def | char | int | int | int | int | long | float | double | - | def | int | int | int | int | int | long | float | double | - | def | long | long | long | long | long | long | float | double | - | def | float | float | float | float | float | float | float | double | - | def | double | double | double | double | double | double | double | double | - | def | Reference | - | - | - | - | - | - | - | Object @ | def | def | def | def | def | def | def | def | def | def | def |==== @ If the two reference type values are the same then this promotion will not occur. *Examples* * Evaluation of conditionals. + [source,Painless] ---- boolean b = true; <1> int x = b ? 1 : 2; <2> List y = x > 1 ? new ArrayList() : null; <3> def z = x < 2 ? x : 2.0; <4> ---- + <1> declare `boolean b`; store `boolean true` to `b` <2> declare `int x`; load from `b` -> `boolean true` evaluate 1st expression: `int 1` -> `int 1`; store `int 1` to `x` <3> declare `List y`; load from `x` -> `int 1`; `int 1` greater than `int 1` -> `boolean false`; evaluate 2nd expression: `null` -> `null`; store `null` to `y`; <4> declare `def z`; load from `x` -> `int 1`; `int 1` less than `int 2` -> `boolean true`; evaluate 1st expression: load from `x` -> `int 1`; promote `int 1` and `double 2.0`: result `double`; implicit cast `int 1` to `double 1.0` -> `double 1.0`; implicit cast `double 1.0` to `def` -> `def`; store `def` to `z`; [[assignment-operator]] ==== Assignment Use the `assignment operator '='` to store a value in a variable or reference type member field for use in subsequent operations. Any operation that produces a value can be assigned to any variable/field as long as the <> are the same or the resultant type can be <> to the variable/field type. See <> for examples using variables. *Errors* * If the type of value is unable to match the type of variable or field. *Grammar* [source,ANTLR4] ---- assignment: field '=' expression ---- *Examples* The examples use the following reference type definition: [source,Painless] ---- name: Example non-static member fields: * int x * def y * List z ---- * Field assignments of different type values. + [source,Painless] ---- Example example = new Example(); <1> example.x = 1; <2> example.y = 2.0; <3> example.z = new ArrayList(); <4> ---- + <1> declare `Example example`; allocate `Example` instance -> `Example reference`; store `Example reference` to `example` <2> load from `example` -> `Example reference`; store `int 1` to `x` of `Example reference` <3> load from `example` -> `Example reference`; implicit cast `double 2.0` to `def` -> `def`; store `def` to `y` of `Example reference` <4> load from `example` -> `Example reference`; allocate `ArrayList` instance -> `ArrayList reference`; implicit cast `ArrayList reference` to `List reference` -> `List reference`; store `List reference` to `z` of `Example reference` + * A field assignment from a field access. + [source,Painless] ---- Example example = new Example(); <1> example.x = 1; <2> example.y = example.x; <3> ---- + <1> declare `Example example`; allocate `Example` instance -> `Example reference`; store `Example reference` to `example` <2> load from `example` -> `Example reference`; store `int 1` to `x` of `Example reference` <3> load from `example` -> `Example reference @0`; load from `example` -> `Example reference @1`; load from `x` of `Example reference @1` -> `int 1`; implicit cast `int 1` to `def` -> `def`; store `def` to `y` of `Example reference @0`; (note `Example reference @0` and `Example reference @1` are the same) [[compound-assignment-operator]] ==== Compound Assignment Use the `compound assignment operator '$='` as a shortcut for an assignment where a binary operation would occur between the variable/field as the left-hand side expression and a separate right-hand side expression. A compound assignment is equivalent to the expression below where V is the variable/field and T is the type of variable/member. [source,Painless] ---- V = (T)(V op expression); ---- *Operators* The table below shows the available operators for use in a compound assignment. Each operator follows the casting/promotion rules according to their regular definition. For numeric operations there is an extra implicit cast when necessary to return the promoted numeric type value to the original numeric type value of the variable/field and can result in data loss. |==== |Operator|Compound Symbol |Multiplication|*= |Division|/= |Remainder|%= |Addition|+= |Subtraction|-= |Left Shift|+++<<=+++ |Right Shift|>>= |Unsigned Right Shift|>>>= |Bitwise And|&= |Boolean And|&= |Bitwise Xor|^= |Boolean Xor|^= |Bitwise Or|\|= |Boolean Or|\|= |String Concatenation|+= |==== *Errors* * If the type of value is unable to match the type of variable or field. *Grammar* [source,ANTLR4] ---- compound_assignment: ( ID | field ) '$=' expression; ---- Note the use of the `$=` represents the use of any of the possible binary operators. *Examples* * Compound assignment for each numeric operator. + [source,Painless] ---- int i = 10; <1> i *= 2; <2> i /= 5; <3> i %= 3; <4> i += 5; <5> i -= 5; <6> i <<= 2; <7> i >>= 1; <8> i >>>= 1; <9> i &= 15; <10> i ^= 12; <11> i |= 2; <12> ---- + <1> declare `int i`; store `int 10` to `i` <2> load from `i` -> `int 10`; multiply `int 10` and `int 2` -> `int 20`; store `int 20` to `i`; (note this is equivalent to `i = i*2`) <3> load from `i` -> `int 20`; divide `int 20` by `int 5` -> `int 4`; store `int 4` to `i`; (note this is equivalent to `i = i/5`) <4> load from `i` -> `int 4`; remainder `int 4` by `int 3` -> `int 1`; store `int 1` to `i`; (note this is equivalent to `i = i%3`) <5> load from `i` -> `int 1`; add `int 1` and `int 5` -> `int 6`; store `int 6` to `i`; (note this is equivalent to `i = i+5`) <6> load from `i` -> `int 6`; subtract `int 5` from `int 6` -> `int 1`; store `int 1` to `i`; (note this is equivalent to `i = i-5`) <7> load from `i` -> `int 1`; left shift `int 1` by `int 2` -> `int 4`; store `int 4` to `i`; (note this is equivalent to `i = i<<2`) <8> load from `i` -> `int 4`; right shift `int 4` by `int 1` -> `int 2`; store `int 2` to `i`; (note this is equivalent to `i = i>>1`) <9> load from `i` -> `int 2`; unsigned right shift `int 2` by `int 1` -> `int 1`; store `int 1` to `i`; (note this is equivalent to `i = i>>>1`) <10> load from `i` -> `int 1`; bitwise and `int 1` and `int 15` -> `int 1`; store `int 1` to `i`; (note this is equivalent to `i = i&2`) <11> load from `i` -> `int 1`; bitwise xor `int 1` and `int 12` -> `int 13`; store `int 13` to `i`; (note this is equivalent to `i = i^2`) <12> load from `i` -> `int 13`; bitwise or `int 13` and `int 2` -> `int 15`; store `int 15` to `i`; (note this is equivalent to `i = i|2`) + * Compound assignment for each boolean operator. + [source,Painless] ---- boolean b = true; <1> b &= false; <2> b ^= false; <3> b |= true; <4> ---- + <1> declare `boolean b`; store `boolean true` in `b`; <2> load from `b` -> `boolean true`; boolean and `boolean true` and `boolean false` -> `boolean false`; store `boolean false` to `b`; (note this is equivalent to `b = b && false`) <3> load from `b` -> `boolean false`; boolean xor `boolean false` and `boolean false` -> `boolean false`; store `boolean false` to `b`; (note this is equivalent to `b = b ^ false`) <4> load from `b` -> `boolean true`; boolean or `boolean false` and `boolean true` -> `boolean true`; store `boolean true` to `b`; (note this is equivalent to `b = b || true`) + * A compound assignment with the string concatenation operator. + [source,Painless] ---- String s = 'compound'; <1> s += ' assignment'; <2> ---- <1> declare `String s`; store `String 'compound'` to `s`; <2> load from `s` -> `String 'compound'`; string concat `String 'compound'` and `String ' assignment''` -> `String 'compound assignment'`; store `String 'compound assignment'` to `s`; (note this is equivalent to `s = s + ' assignment'`) + * A compound assignment with the `def` type. + [source,Painless] ---- def x = 1; <1> x += 2; <2> ---- <1> declare `def x`; implicit cast `int 1` to `def`; store `def` to `x`; <2> load from `x` -> `def`; implicit cast `def` to `int 1` -> `int 1`; add `int 1` and `int 2` -> `int 3`; implicit cast `int 3` to `def` -> `def`; store `def` to `x`; (note this is equivalent to `x = x+2`) + * A compound assignment with an extra implicit cast. + [source,Painless] ---- byte b = 1; <1> b += 2; <2> ---- <1> declare `byte b`; store `byte 1` to `x`; <2> load from `x` -> `byte 1`; implicit cast `byte 1 to `int 1` -> `int 1`; add `int 1` and `int 2` -> `int 3`; implicit cast `int 3` to `byte 3` -> `byte 3`; store `byte 3` to `b`; (note this is equivalent to `b = b+2`)