OpenSearch/docs/painless/painless-operators-general.asciidoc

[[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
<<painless-functions, function call>> 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 <<painless-casting, casting>> 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 <<promotion, promoted>> 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
<<painless-types, types>> are the same or the resultant type can be
<<painless-casting, implicitly cast>> to the variable/field type.

See <<variable-assignment, variable assignment>> 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`)