elasticsearch: .../painless-lang-spec.asciidoc

Painless Language Specification

Painless is a scripting language designed for security and performance. Painless syntax is similar to Java syntax along with some additional features such as dynamic typing, Map and List accessor shortcuts, and array initializers. As a direct comparison to Java, there are some important differences, especially related to the casting model. For more detailed conceptual information about the basic constructs that Painless and Java share, refer to the corresponding topics in the Java Language Specification.

Painless scripts are parsed and compiled using the ANTLR4 and ASM libraries. Scripts are compiled directly into Java Virtual Machine (JVM) byte code and executed against a standard JVM. This specification uses ANTLR4 grammar notation to describe the allowed syntax. However, the actual Painless grammar is more compact than what is shown here.

Comments

Use a comment to annotate or explain code within a script. Use the // token anywhere on a line to specify a single-line comment. All characters from the // token to the end of the line are ignored. Use an opening / token and a closing / token to specify a multi-line comment. Multi-line comments can start anywhere on a line, and all characters in between the / token and / token are ignored. A comment is included anywhere within a script.

Grammar

SINGLE_LINE_COMMENT: '//' .*? [\n\r];
MULTI_LINE_COMMENT: '/*' .*? '*/';

Examples

Single-line comments.

// single-line comment

int value; // single-line comment

Multi-line comments.

/* multi-
   line
   comment */

int value; /* multi-
              line
              comment */ value = 0;

int value; /* multi-line
              comment */

/* multi-line
   comment */ int value;

int value; /* multi-line
              comment */ value = 0;

int value; /* multi-line comment */ value = 0;

Keywords

Keywords are reserved tokens for built-in language features.

Errors

If a keyword is used as an identifier.

Keywords

else

while

for

continue

break

return

new

try

catch

throw

this

instanceof

Literals

Use a literal to specify a value directly in an operation.

Integers

Use an integer literal to specify an integer type value in decimal, octal, or hex notation of a primitive type int, long, float, or double. Use the following single letter designations to specify the primitive type: l or L for long, f or F for float, and d or D for double. If not specified, the type defaults to int. Use 0 as a prefix to specify an integer literal as octal, and use 0x or 0X as a prefix to specify an integer literal as hex.

Grammar

INTEGER: '-'? ( '0' | [1-9] [0-9]* ) [lLfFdD]?;
OCTAL:   '-'? '0' [0-7]+ [lL]?;
HEX:     '-'? '0' [xX] [0-9a-fA-F]+ [lL]?;

Examples

Integer literals.
```
0     (1)
0D    (2)
1234L (3)
-90f  (4)
-022  (5)
0xF2A (6)
```
1. int 0
2. double 0.0
3. long 1234
4. float -90.0
5. int -18 in octal
6. int 3882 in hex

Floats

Use a floating point literal to specify a floating point type value of a primitive type float or double. Use the following single letter designations to specify the primitive type: f or F for float and d or D for double. If not specified, the type defaults to double.

Grammar

DECIMAL: '-'? ( '0' | [1-9] [0-9]* ) (DOT [0-9]+)? EXPONENT? [fFdD]?;
EXPONENT: ( [eE] [+\-]? [0-9]+ );

Examples

Floating point literals.
```
0.0      (1)
1E6      (2)
0.977777 (3)
-126.34  (4)
89.9F    (5)
```
1. double 0.0
2. double 1000000.0 in exponent notation
3. double 0.977777
4. double -126.34
5. float 89.9

Strings

Use a string literal to specify a String type value with either single-quotes or double-quotes. Use a \" token to include a double-quote as part of a double-quoted string literal. Use a \' token to include a single-quote as part of a single-quoted string literal. Use a \\ token to include a backslash as part of any string literal.

Grammar

STRING: ( '"'  ( '\\"'  | '\\\\' | ~[\\"] )*? '"'  )
      | ( '\'' ( '\\\'' | '\\\\' | ~[\\'] )*? '\'' );

Examples

String literals using single-quotes.

'single-quoted string literal'
'\'single-quoted with escaped single-quotes\' and backslash \\'
'single-quoted with non-escaped "double-quotes"'

String literals using double-quotes.

"double-quoted string literal"
"\"double-quoted with escaped double-quotes\" and backslash: \\"
"double-quoted with non-escaped 'single-quotes'"

Characters

Character literals are not specified directly. Instead, use the cast operator to convert a String type value into a char type value.

Identifiers

Use an identifier as a named token to specify a variable, type, field, method, or function.

Errors

If a keyword is used as an identifier.

Grammar

ID: [_a-zA-Z] [_a-zA-Z-0-9]*;

Examples

Variations of identifiers.
```
a
Z
id
list
list0
MAP25
_map25
Map_25
```

Variables

A variable loads and stores a value for evaluation during operations.

Declaration

Declare a variable before use with the format of type followed by identifier. Declare an array type variable using an opening [ token and a closing ] token for each dimension directly after the identifier. Specify a comma-separated list of identifiers following the type to declare multiple variables in a single statement. Use an assignment operator combined with a declaration to immediately assign a value to a variable. A variable not immediately assigned a value will have a default value assigned implicitly based on the type.

Errors

If a variable is used prior to or without declaration.

Grammar

declaration : type ID assignment? (',' ID assignment?)*;
type: ID ('.' ID)* ('[' ']')*;
assignment: '=' expression;

Examples

Different variations of variable declaration.
```
int x;           (1)
List y;          (2)
int x, y = 5, z; (3)
def d;           (4)
int i = 10;      (5)
float[] f;       (6)
Map[][] m;       (7)
```
1. declare int x; store default null to x
2. declare List y; store default null to y
3. declare int x; store default int 0 to x; declare int y; store int 5 to y; declare int z; store default int 0 to z;
4. declare def d; store default null to d
5. declare int i; store int 10 to i
6. declare float[] f; store default null to f
7. declare Map[][] m; store default null to m

Assignment

Use the assignment operator '=' to store a value in a variable for use in subsequent operations. Any operation that produces a value can be assigned to any variable as long as the types are the same or the resultant type can be implicitly cast to the variable type.

Errors

If the type of value is unable to match the type of variable.

Grammar

assignment: ID '=' expression

Examples

Variable assignment with an integer literal.
```
int i;  (1)
i = 10; (2)
```
1. declare int i; store default int 0 to i
2. store int 10 to i
Declaration combined with immediate assignment.
```
int i = 10;     (1)
double j = 2.0; (2)
```
1. declare int i; store int 10 to i
2. declare double j; store double 2.0 to j
Assignment of one variable to another using primitive type values.
```
int i = 10; (1)
int j = i;  (2)
```
1. declare int i; store int 10 to i
2. declare int j; load from i → int 10; store int 10 to j
Assignment with reference types using the new instance operator.
```
ArrayList l = new ArrayList(); (1)
Map m = new HashMap();         (2)
```
1. declare ArrayList l; allocate ArrayList instance → ArrayList reference; store ArrayList reference to l
2. declare Map m; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference → Map reference; store Map reference to m
Assignment of one variable to another using reference type values.
```
List l = new ArrayList(); (1)
List k = l;               (2)
List m;                   (3)
m = k;                    (4)
```
1. declare List l; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to l
2. declare List k; load from l → List reference; store List reference to k; (note l and k refer to the same instance known as a shallow-copy)
3. declare List m; store default null to m
4. load from k → List reference; store List reference to m; (note l, k, and m refer to the same instance)
Assignment with array type variables using the new array operator.
```
int[] ia1;                   (1)
ia1 = new int[2];            (2)
ia1[0] = 1;                  (3)
int[] ib1 = ia1;             (4)
int[][] ic2 = new int[2][5]; (5)
ic2[1][3] = 2;               (6)
ic2[0] = ia1;                (7)
```
1. declare int[] ia1; store default null to ia1
2. allocate 1-d int array instance with length [2] → 1-d int array reference; store 1-d int array reference to ia1
3. load from ia1 → 1-d int array reference; store int 1 to index [0] of 1-d int array reference
4. declare int[] ib1; load from ia1 → 1-d int array reference; store 1-d int array reference to ib1; (note ia1 and ib1 refer to the same instance known as a shallow copy)
5. declare int[][] ic2; allocate 2-d int array instance with length [2, 5] → 2-d int array reference; store 2-d int array reference to ic2
6. load from ic2 → 2-d int array reference; store int 2 to index [1, 3] of 2-d int array reference
7. load from ia1 → 1-d int array reference; load from ic2 → 2-d int array reference; store 1-d int array reference to index [0] of 2-d int array reference; (note ia1, ib1, and index [0] of ia2 refer to the same instance)

Types

A type is a classification of data used to define the properties of a value. These properties specify what data a value represents and the rules for how a value is evaluated during an operation. Each type belongs to one of the following categories: primitive, reference, or dynamic.

Primitive Types

A primitive type represents basic data built natively into the JVM and is allocated to non-heap memory. Declare a primitive type variable or access a primitive type member field (from a reference type instance), and assign it a primitive type value for evaluation during later operations. The default value for a newly-declared primitive type variable is listed as part of the definitions below. A primitive type value is copied during an assignment or as an argument for a method/function call.

A primitive type has a corresponding reference type (also known as a boxed type). Use the field access operator or method call operator on a primitive type value to force evaluation as its corresponding reference type value.

The following primitive types are available:

`byte`	8-bit, signed, two’s complement integer range: [`-128`, `127`] default value: `0` reference type: `Byte`
`short`	16-bit, signed, two’s complement integer range: [`-32768`, `32767`] default value: `0` reference type: `Short`
`char`	16-bit, unsigned, Unicode character range: [`0`, `65535`] default value: `0` or `\u0000` reference type: `Character`
`int`	32-bit, signed, two’s complement integer range: [`-2^32`, `2^32-1`] default value: `0` reference type: `Integer`
`long`	64-bit, signed, two’s complement integer range: [`-2^64`, `2^64-1`] default value: `0` reference type: `Long`
`float`	32-bit, signed, single-precision, IEEE 754 floating point number default value: `0.0` reference type: `Float`
`double`	64-bit, signed, double-precision, IEEE 754 floating point number default value: `0.0` reference type: `Double`
`boolean`	logical quantity with two possible values of `true` and `false` default value: `false` reference type: `Boolean`

Examples

Primitive types used in declaration, declaration and assignment.
```
int i = 1;        (1)
double d;         (2)
boolean b = true; (3)
```
1. declare int i; store int 1 to i
2. declare double d; store default double 0.0 to d
3. declare boolean b; store boolean true to b
Method call on a primitive type using the corresponding reference type.
```
int i = 1;    (1)
i.toString(); (2)
```
1. declare int i; store int 1 to i
2. load from i → int 1; box int 1 → Integer 1 reference; call toString on Integer 1 reference → String '1'

Reference Types

A reference type is a named construct (object), potentially representing multiple pieces of data (member fields) and logic to manipulate that data (member methods), defined as part of the application programming interface (API) for scripts.

A reference type instance is a single set of data for one reference type object allocated to the heap. Use the new instance operator to allocate a reference type instance. Use a reference type instance to load from, store to, and manipulate complex data.

A reference type value refers to a reference type instance, and multiple reference type values may refer to the same reference type instance. A change to a reference type instance will affect all reference type values referring to that specific instance.

Declare a reference type variable or access a reference type member field (from a reference type instance), and assign it a reference type value for evaluation during later operations. The default value for a newly-declared reference type variable is null. A reference type value is shallow-copied during an assignment or as an argument for a method/function call. Assign null to a reference type variable to indicate the reference type value refers to no reference type instance. The JVM will garbage collect a reference type instance when it is no longer referred to by any reference type values. Pass null as an argument to a method/function call to indicate the argument refers to no reference type instance.

A reference type object defines zero-to-many of each of the following:

static member field: A static member field is a named and typed piece of data. Each reference type object contains one set of data representative of its static member fields. Use the field access operator in correspondence with the reference type object name to access a static member field for loading and storing to a specific reference type object. No reference type instance allocation is necessary to use a static member field.
non-static member field: A non-static member field is a named and typed piece of data. Each reference type instance contains one set of data representative of its reference type object’s non-static member fields. Use the field access operator for loading and storing to a non-static member field of a specific reference type instance. An allocated reference type instance is required to use a non-static member field.
static member method: A static member method is a function called on a reference type object. Use the method call operator in correspondence with the reference type object name to call a static member method. No reference type instance allocation is necessary to use a static member method.
non-static member method: A non-static member method is a function called on a reference type instance. A non-static member method called on a reference type instance can load from and store to non-static member fields of that specific reference type instance. Use the method call operator in correspondence with a specific reference type instance to call a non-static member method. An allocated reference type instance is required to use a non-static member method.
constructor: A constructor is a special type of function used to allocate a reference type instance defined by a specific reference type object. Use the new instance operator to allocate a reference type instance.

A reference type object follows a basic inheritance model. Consider types A and B. Type A is considered to be a parent of B, and B a child of A, if B inherits (is able to access as its own) all of A’s non-static members. Type B is considered a descendant of A if there exists a recursive parent-child relationship from B to A with none to many types in between. In this case, B inherits all of A’s non-static members along with all of the non-static members of the types in between. Type B is also considered to be a type A in both relationships.

Examples

Reference types evaluated in several different operations.
```
List l = new ArrayList(); (1)
l.add(1);                 (2)
int i = l.get(0) + 2;     (3)
```
1. declare List l; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to l
2. load from l → List reference; implicit cast int 1 to def → def call add on List reference with arguments (def)
3. declare int i; load from l → List reference; call get on List reference with arguments (int 0) → def; implicit cast def to int 1 → int 1; add int 1 and int 2 → int 3; store int 3 to i
Sharing a reference type instance.
```
List l0 = new ArrayList();     (1)
List l1 = l0;                  (2)
l0.add(1);                     (3)
l1.add(2);                     (4)
int i = l1.get(0) + l0.get(1); (5)
```
1. declare List l0; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to l0
2. declare List l1; load from l0 → List reference; store List reference to l1 (note l0 and l1 refer to the same instance known as a shallow-copy)
3. load from l0 → List reference; implicit cast int 1 to def → def call add on List reference with arguments (def)
4. load from l1 → List reference; implicit cast int 2 to def → def call add on List reference with arguments (def)
5. declare int i; load from l0 → List reference; call get on List reference with arguments (int 0) → def @0; implicit cast def @0 to int 1 → int 1; load from l1 → List reference; call get on List reference with arguments (int 1) → def @1; implicit cast def @1 to int 2 → int 2; add int 1 and int 2 → int 3; store int 3 to i;
Using the static members of a reference type.
```
int i = Integer.MAX_VALUE;       (1)
long l = Long.parseLong("123L"); (2)
```
1. declare int i; load from MAX_VALUE on Integer → int 2147483647; store int 2147483647 to i
2. declare long l; call parseLong on Long with arguments (long 123) → long 123; store long 123 to l

Dynamic Types

A dynamic type value can represent the value of any primitive type or reference type using a single type name def. A def type value mimics the behavior of whatever value it represents at run-time and will always represent the child-most descendant type value of any type value when evaluated during operations.

Declare a def type variable or access a def type member field (from a reference type instance), and assign it any type of value for evaluation during later operations. The default value for a newly-declared def type variable is null. A def type variable or method/function parameter can change the type it represents during the compilation and evaluation of a script.

Using the def type can have a slight impact on performance. Use only primitive types and reference types directly when performance is critical.

Errors

If a def type value represents an inappropriate type for evaluation of an operation at run-time.

Examples

General uses of the def type.
```
def dp = 1;               (1)
def dr = new ArrayList(); (2)
dr = dp;                  (3)
```
1. declare def dp; implicit cast int 1 to def → def; store def to dp
2. declare def dr; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def; store def to dr
3. load from dp → def; store def to dr; (note the switch in the type dr represents from ArrayList to int)
A def type value representing the child-most descendant of a value.
```
Object l = new ArrayList(); (1)
def d = l;                  (2)
d.ensureCapacity(10);       (3)
```
1. declare Object l; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to Object reference → Object reference; store Object reference to l
2. declare def d; load from l → Object reference; implicit cast Object reference to def → def; store def to d;
3. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call ensureCapacity on ArrayList reference with arguments (int 10); (note def was implicit cast to ArrayList reference since ArrayList` is the child-most descendant type value that the def type value represents)

String Type

The String type is a specialized reference type that does not require explicit allocation. Use a string literal to directly evaluate a String type value. While not required, the new instance operator can allocate String type instances.

Examples

General use of the String type.
```
String r = "some text";             (1)
String s = 'some text';             (2)
String t = new String("some text"); (3)
String u;                           (4)
```
1. declare String r; store String "some text" to r
2. declare String s; store String 'some text' to s
3. declare String t; allocate String instance with arguments (String "some text") → String "some text"; store String "some text" to t
4. declare String u; store default null to u

void Type

The void type represents the concept of a lack of type. Use the void type to indicate a function returns no value.

Examples

Use of the void type in a function.

void addToList(List l, def d) {
    l.add(d);
}

Array Type

An array type is a specialized reference type where an array type instance contains a series of values allocated to the heap. Each value in an array type instance is defined as an element. All elements in an array type instance are of the same type (element type) specified as part of declaration. Each element is assigned an index within the range [0, length) where length is the total number of elements allocated for an array type instance.

Use the new array operator or the array initialization operator to allocate an array type instance. Declare an array type variable or access an array type member field (from a reference type instance), and assign it an array type value for evaluation during later operations. The default value for a newly-declared array type variable is null. An array type value is shallow-copied during an assignment or as an argument for a method/function call. Assign null to an array type variable to indicate the array type value refers to no array type instance. The JVM will garbage collect an array type instance when it is no longer referred to by any array type values. Pass null as an argument to a method/function call to indicate the argument refers to no array type instance.

Use the array length operator to retrieve the length of an array type value as an int type value. Use the array access operator to load from and store to an individual element within an array type instance.

When an array type instance is allocated with multiple dimensions using the range [2, d] where d >= 2, each element within each dimension in the range [1, d-1] is also an array type. The element type of each dimension, n, is an array type with the number of dimensions equal to d-n. For example, consider int[][][] with 3 dimensions. Each element in the 3rd dimension, d-3, is the primitive type int. Each element in the 2nd dimension, d-2, is the array type int[]. And each element in the 1st dimension, d-1 is the array type int[][].

Examples

General use of single-dimensional arrays.
```
int[] x;                   (1)
float[] y = new float[10]; (2)
def z = new float[5];      (3)
y[9] = 1.0F;               (4)
z[0] = y[9];               (5)
```
1. declare int[] x; store default null to x
2. declare float[] y; allocate 1-d float array instance with length [10] → 1-d float array reference; store 1-d float array reference to y
3. declare def z; allocate 1-d float array instance with length [5] → 1-d float array reference; implicit cast 1-d float array reference to def → def; store def to z
4. load from y → 1-d float array reference; store float 1.0 to index [9] of 1-d float array reference
5. load from y → 1-d float array reference @0; load from index [9] of 1-d float array reference @0 → float 1.0; load from z → def; implicit cast def to 1-d float array reference @1 → 1-d float array reference @1; store float 1.0 to index [0] of 1-d float array reference @1
General use of a multi-dimensional array.
```
int[][][] ia3 = new int[2][3][4]; (1)
ia3[1][2][3] = 99;                (2)
int i = ia3[1][2][3];             (3)
```
1. declare int[][][] ia; allocate 3-d int array instance with length [2, 3, 4] → 3-d int array reference; store 3-d int array reference to ia3
2. load from ia3 → 3-d int array reference; store int 99 to index [1, 2, 3] of 3-d int array reference
3. declare int i; load from ia3 → 3-d int array reference; load from index [1, 2, 3] of 3-d int array reference → int 99; store int 99 to i

Casting

A cast converts the value of an original type to the equivalent value of a target type. An implicit cast infers the target type and automatically occurs during certain operations. An explicit cast specifies the target type and forcefully occurs as its own operation. Use the cast operator '()' to specify an explicit cast.

Refer to the cast table for a quick reference on all allowed casts.

Errors

If during a cast there exists no equivalent value for the target type.
If an implicit cast is given, but an explicit cast is required.

Grammar

cast: '(' TYPE ')' expression

Examples

Valid casts.
```
int i = (int)5L;         (1)
Map m = new HashMap();   (2)
HashMap hm = (HashMap)m; (3)
```
1. declare int i; explicit cast long 5 to int 5 → int 5; store int 5 to i
2. declare Map m; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference → Map reference; store Map reference to m
3. declare HashMap hm; load from m → Map reference; explicit cast Map reference to HashMap reference → HashMap reference; store HashMap reference to hm

Numeric Type Casting

A numeric type cast converts the value of an original numeric type to the equivalent value of a target numeric type. A cast between two numeric type values results in data loss when the value of the original numeric type is larger than the target numeric type can accommodate. A cast between an integer type value and a floating point type value can result in precision loss.

The allowed casts for values of each numeric type are shown as a row in the following table:

byte

short

char

int

long

float

double

byte

implicit

short

explicit

implicit

char

explicit

implicit

int

explicit

implicit

long

explicit

implicit

float

explicit

implicit

double

explicit

Examples

Valid numeric type casts.
```
int a = 1;            (1)
long b = a;           (2)
short c = (short)b;   (3)
double e = (double)a; (4)
```
1. declare int a; store int 1 to a
2. declare long b; load from a → int 1; implicit cast int 1 to long 1 → long 1; store long 1 to b
3. declare short c; load from b → long 1; explicit cast long 1 to short 1 → short 1; store short 1 value to c
4. declare double e; load from a → int 1; explicit cast int 1 to double 1.0; store double 1.0 to e; (note the explicit cast is extraneous since an implicit cast is valid)
Invalid numeric type casts resulting in errors.
```
int a = 1.0; // error (1)
int b = 2;            (2)
byte c = b;  // error (3)
```
1. declare int i; error → cannot implicit cast double 1.0 to int 1; (note an explicit cast is valid)
2. declare int b; store int 2 to b
3. declare byte c; load from b → int 2; error → cannot implicit cast int 2 to byte 2; (note an explicit cast is valid)

Reference Type Casting

A reference type cast converts the value of an original reference type to the equivalent value of a target reference type. An implicit cast between two reference type values is allowed when the original reference type is a descendant of the target type. An explicit cast between two reference type values is allowed when the original type is a descendant of the target type or the target type is a descendant of the original type.

Examples

Valid reference type casts.
```
List x;                        (1)
ArrayList y = new ArrayList(); (2)
x = y;                         (3)
y = (ArrayList)x;              (4)
x = (List)y;                   (5)
```
1. declare List x; store default value null to x
2. declare ArrayList y; allocate ArrayList instance → ArrayList reference; store ArrayList reference to y;
3. load from y → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to x; (note ArrayList is a descendant of List)
4. load from x → List reference; explicit cast List reference to ArrayList reference → ArrayList reference; store ArrayList reference to y;
5. load from y → ArrayList reference; explicit cast ArrayList reference to List reference → List reference; store List reference to x; (note the explicit cast is extraneous, and an implicit cast is valid)
Invalid reference type casts resulting in errors.
```
List x = new ArrayList();          (1)
ArrayList y = x;          // error (2)
Map m = (Map)x;           // error (3)
```
1. declare List x; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to x
2. declare ArrayList y; load from x → List reference; error → cannot implicit cast List reference to ArrayList reference; (note an explicit cast is valid since ArrayList is a descendant of List)
3. declare ArrayList y; load from x → List reference; error → cannot explicit cast List reference to Map reference; (note no cast is valid since neither List nor Map is a descendant of the other)

Dynamic Type Casting

A dynamic (def) type cast converts the value of an original def type to the equivalent value of any target type or converts the value of any original type to the equivalent value of a target def type.

An implicit cast from any original type value to a def type value is always allowed. An explicit cast from any original type value to a def type value is always allowed but never necessary.

An implicit or explicit cast from an original def type value to any target type value is allowed if and only if the cast is normally allowed based on the current type value the def type value represents.

Examples

Valid dynamic type casts with any original type to a target def type.
```
def d0 = 3;               (1)
d0 = new ArrayList();     (2)
Object o = new HashMap(); (3)
def d1 = o;               (4)
int i = d1.size();        (5)
```
1. declare def d0; implicit cast int 3 to def; store int 3 to d0
2. allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def; store def to d0
3. declare Object o; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Object reference → Object reference; store Object reference to o
4. declare def d1; load from o → Object reference; implicit cast Object reference to def → def; store def to d1
5. declare int i; load from d1 → def; implicit cast def to HashMap reference → HashMap reference`; call size on HashMap reference → int 0; store int 0 to i; (note def was implicit cast to HashMap reference since HashMap is the child-most descendant type value that the def type value represents)
Valid dynamic type casts with an original def type to any target type.
```
def d = 1.0;         (1)
int i = (int)d;      (2)
d = 1;               (3)
float f = d;         (4)
d = new ArrayList(); (5)
List l = d;          (6)
```
1. declare def d; implicit cast double 1.0 to def → def; store def to d
2. declare int i; load from d → def; implicit cast def to double 1.0 → double 1.0; explicit cast double 1.0 to int 1 → int 1; store int 1 to i; (note the explicit cast is necessary since a double type value is not converted to an int type value implicitly)
3. store int 1 to d; (note the switch in the type d represents from double to int)
4. declare float i; load from d → def; implicit cast def to int 1 → int 1; implicit cast int 1 to float 1.0 → float 1.0; store float 1.0 to f
5. allocate ArrayList instance → ArrayList reference; store ArrayList reference to d; (note the switch in the type d represents from int to ArrayList)
6. declare List l; load from d → def; implicit cast def to ArrayList reference → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to l
Invalid dynamic type casts resulting in errors.
```
def d = 1;                  (1)
short s = d;       // error (2)
d = new HashMap();          (3)
List l = d;        // error (4)
```
1. declare def d; implicit cast int 1 to def → def; store def to d
2. declare short s; load from d → def; implicit cast def to int 1 → int 1; error → cannot implicit cast int 1 to short 1; (note an explicit cast is valid)
3. allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def; store def to d
4. declare List l; load from d → def; implicit cast def to HashMap reference; error → cannot implicit cast HashMap reference to List reference; (note no cast is valid since neither HashMap nor List is a descendant of the other)

String to Character Casting

Use the cast operator to convert a String type value into a char type value.

Errors

If the String type value isn’t one character in length.
If the String type value is null.

Examples

Casting string literals into char type values.
```
char c = (char)"C"; (1)
c = (char)'c';      (2)
```
1. declare char c; explicit cast String "C" to char C → char C; store char C to c
2. explicit cast String 'c' to char c → char c; store char c to c
Casting a String reference into a char type value.
```
String s = "s";   (1)
char c = (char)s; (2)
```
1. declare String s; store String "s" to s;
2. declare char c load from s → String "s"; explicit cast String "s" to char s → char s; store char s to c

Boxing and Unboxing

Boxing is a special type of cast used to convert a primitive type to its corresponding reference type. Unboxing is the reverse used to convert a reference type to its corresponding primitive type.

Implicit boxing/unboxing occurs during the following operations:

Conversions between a def type and a primitive type are implicitly boxed/unboxed as necessary, though this is referred to as an implicit cast throughout the documentation.
Method/function call arguments are implicitly boxed/unboxed as necessary.
A primitive type value is implicitly boxed when a reference type method is called on it.

Explicit boxing/unboxing is not allowed. Use the reference type API to explicitly convert a primitive type value to its respective reference type value and vice versa.

Errors

If an explicit cast is made to box/unbox a primitive type.

Examples

Uses of implicit boxing/unboxing.
```
List l = new ArrayList();       (1)
l.add(1);                       (2)
Integer I = Integer.valueOf(0); (3)
int i = l.get(i);               (4)
```
1. declare List l; allocate ArrayList instance → ArrayList reference; store ArrayList reference to l;
2. load from l → List reference; implicit cast int 1 to def → def; call add on List reference with arguments (def); (note internally int 1 is boxed to Integer 1 to store as a def type value)
3. declare Integer I; call valueOf on Integer with arguments of (int 0) → Integer 0; store Integer 0 to I;
4. declare int i; load from I → Integer 0; unbox Integer 0 → int 0; load from l → List reference; call get on List reference with arguments (int 0) → def; implicit cast def to int 1 → int 1; store int 1 to i; (note internally int 1 is unboxed from Integer 1 when loaded from a def type value)
Uses of invalid boxing/unboxing resulting in errors.
```
Integer x = 1;                   // error (1)
Integer y = (Integer)1;          // error (2)
int a = Integer.valueOf(1);      // error (3)
int b = (int)Integer.valueOf(1); // error (4)
```
1. declare Integer x; error → cannot implicit box int 1 to Integer 1 during assignment
2. declare Integer y; error → cannot explicit box int 1 to Integer 1 during assignment
3. declare int a; call valueOf on Integer with arguments of (int 1) → Integer 1; error → cannot implicit unbox Integer 1 to int 1 during assignment
4. declare int a; call valueOf on Integer with arguments of (int 1) → Integer 1; error → cannot explicit unbox Integer 1 to int 1 during assignment

Promotion

Promotion is when a single value is implicitly cast to a certain type or multiple values are implicitly cast to the same type as required for evaluation by certain operations. Each operation that requires promotion has a promotion table that shows all required implicit casts based on the type(s) of value(s). A value promoted to a def type at compile-time is promoted again at run-time based on the type the def value represents.

Errors

If a specific operation cannot find an allowed promotion type for the type(s) of value(s) given.

Examples

Uses of promotion.
```
double d = 2 + 2.0; (1)
def x = 1;          (2)
float f = x + 2.0F; (3)
```
1. declare double d; promote int 2 and double 2.0 @0: result double; implicit cast int 2 to double 2.0 @1 → double 2.0 @1; add double 2.0 @1 and double 2.0 @0 → double 4.0; store double 4.0 to d
2. declare def x; implicit cast int 1 to def → def; store def to x;
3. declare float f; load from x → def; implicit cast def to int 1 → int 1; promote int 1 and float 2.0: result float; implicit cast int 1 to float 1.0 → float `1.0; add float 1.0 and float 2.0 → float 3.0; store float 3.0 to f; (note this example illustrates promotion done at run-time as promotion done at compile-time would have resolved to a def type value)

Allowed Casts

The following tables show all allowed casts. Read the tables row by row, where the original type is shown in the first column, and each subsequent column indicates whether a cast to the specified target type is implicit (I), explicit (E), or is not allowed (-).

Primitive/Reference Types

def

boolean ( o )

byte ( b )

short ( s )

char ( c )

int ( i )

long ( j )

float ( f )

double ( d )

Boolean ( O )

Byte ( B )

Short ( S )

Character ( C )

Integer ( I )

Long ( L )

Float ( F )

Double ( D )

String ( T )

Reference ( R )

@ See reference type casting for allowed reference type casts.

def Type

def

def as boolean

def as byte

def as short

def as char

def as int

def as long

def as float

def as double

def as Boolean

def as Byte

def as Short

def as Character

def as Integer

def as Long

def as Float

def as Double

def as String

def as Reference

@ See reference type casting for allowed reference type casts.

Operators

An operator is the most basic action that can be taken to evaluate values in a script. An expression is one-to-many consecutive operations. Precedence is the order in which an operator will be evaluated relative to another operator. Associativity is the direction within an expression in which a specific operator is evaluated. The following table lists all available operators:

Operator

Category

Symbol(s)

Precedence

Associativity

Precedence

General

()

left → right

Method Call

Reference

. ()

left → right

left → right

left → right

()

left → right

Array Initialization

Array

[] {}

left → right

Array Access

Array

[]

left → right

left → right

[]

left → right

List Access

Reference

[]

left → right

Map Initialization

Reference

[:]

left → right

Map Access

Reference

[]

left → right

left → right

—

left → right

right → left

—

right → left

right → left

right → left

right → left

right → left

()

right → left

New Instance

Reference

new ()

right → left

New Array

Array

new []

right → left

left → right

left → right

left → right

left → right

left → right

left → right

left → right

left → right

>>>

left → right

Greater Than

Boolean

left → right

Greater Than Or Equal

left → right

left → right

⇐

left → right

Instanceof

Boolean

instanceof

left → right

left → right

left → right

===

left → right

Identity Not Equals

Boolean

!==

left → right

left → right

left → right

left → right

left → right

left → right

left → right

? :

right → left

right → left

right → left

right → left

Operators: General

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

precedence: '(' expression ')';

Examples

Precedence with numeric operators.
```
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

Use the function call operator () to call an existing function. A function call is defined within a script.

Grammar

function_call: ID '(' ( expression (',' expression)* )? ')'';

Examples

A function call.
```
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

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 casting for more information.

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

conditional: expression '?' expression ':' expression;

Promotion

byte

short

char

int

long

float

double

Reference

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Reference

Object @

def

@ If the two reference type values are the same then this promotion will not occur.

Examples

Evaluation of conditionals.
```
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

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 types are the same or the resultant type can be implicitly cast to the variable/field type.

See variable assignment for examples using variables.

Errors

If the type of value is unable to match the type of variable or field.

Grammar

assignment: field '=' expression

Examples

The examples use the following reference type definition:

name:
  Example

non-static member fields:
  * int x
  * def y
  * List z

Field assignments of different type values.
```
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.
```
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

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.

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

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.
```
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.
```
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.
```
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.
```
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.
```
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)

Operators: Numeric

Post Increment

Use the post increment operator '++' to INCREASE the value of a numeric type variable/field by 1. An extra implicit cast is necessary to return the promoted numeric type value to the original numeric type value of the variable/field for the following types: byte, short, and char. If a variable/field is read as part of an expression the value is loaded prior to the increment.

Errors

If the variable/field is a non-numeric type.

Grammar

post_increment: ( variable | field ) '++';

Promotion

original	promoted	implicit
byte	int	byte
short	int	short
char	int	char
int	int
long	long
float	float
double	double
def	def

original

promoted

implicit

byte

int

byte

short

int

short

char

int

char

int

long

float

double

def

Examples

Post increment with different numeric types.
```
short i = 0; (1)
i++;         (2)
long j = 1;  (3)
long k;      (4)
k = j++;     (5)
```
1. declare short i; store short 0 to i
2. load from i → short 0; promote short 0: result int; add int 0 and int 1 → int 1; implicit cast int 1 to short 1; store short 1 to i
3. declare long j; implicit cast int 1 to long 1 → long 1; store long 1 to j
4. declare long k; store default long 0 to k
5. load from j → long 1; store long 1 to k; add long 1 and long 1 → long 2; store long 2 to j
Post increment with the def type.
```
def x = 1; (1)
x++;       (2)
```
1. declare def x; implicit cast int 1 to def → def; store def to x
2. load from x → def; implicit cast def to int 1; add int 1 and int 1 → int 2; implicit cast int 2 to def; store def to x

Post Decrement

Use the post decrement operator '--' to DECREASE the value of a numeric type variable/field by 1. An extra implicit cast is necessary to return the promoted numeric type value to the original numeric type value of the variable/field for the following types: byte, short, and char. If a variable/field is read as part of an expression the value is loaded prior to the decrement.

Errors

If the variable/field is a non-numeric type.

Grammar

post_decrement: ( variable | field ) '--';

Promotion

original	promoted	implicit
byte	int	byte
short	int	short
char	int	char
int	int
long	long
float	float
double	double
def	def

original

promoted

implicit

byte

int

byte

short

int

short

char

int

char

int

long

float

double

def

Examples

Post decrement with different numeric types.
```
short i = 0; (1)
i--;         (2)
long j = 1;  (3)
long k;      (4)
k = j--;     (5)
```
1. declare short i; store short 0 to i
2. load from i → short 0; promote short 0: result int; subtract int 1 from int 0 → int -1; implicit cast int -1 to short -1; store short -1 to i
3. declare long j; implicit cast int 1 to long 1 → long 1; store long 1 to j
4. declare long k; store default long 0 to k
5. load from j → long 1; store long 1 to k; subtract long 1 from long 1 → long 0; store long 0 to j
Post decrement with the def type.
```
def x = 1; (1)
x--;       (2)
```
1. declare def x; implicit cast int 1 to def → def; store def to x
2. load from x → def; implicit cast def to int 1; subtract int 1 from int 1 → int 0; implicit cast int 0 to def; store def to x

Pre Increment

Use the pre increment operator '++' to INCREASE the value of a numeric type variable/field by 1. An extra implicit cast is necessary to return the promoted numeric type value to the original numeric type value of the variable/field for the following types: byte, short, and char. If a variable/field is read as part of an expression the value is loaded after the increment.

Errors

If the variable/field is a non-numeric type.

Grammar

pre_increment: '++' ( variable | field );

Promotion

original	promoted	implicit
byte	int	byte
short	int	short
char	int	char
int	int
long	long
float	float
double	double
def	def

original

promoted

implicit

byte

int

byte

short

int

short

char

int

char

int

long

float

double

def

Examples

Pre increment with different numeric types.
```
short i = 0; (1)
++i;         (2)
long j = 1;  (3)
long k;      (4)
k = ++j;     (5)
```
1. declare short i; store short 0 to i
2. load from i → short 0; promote short 0: result int; add int 0 and int 1 → int 1; implicit cast int 1 to short 1; store short 1 to i
3. declare long j; implicit cast int 1 to long 1 → long 1; store long 1 to j
4. declare long k; store default long 0 to k
5. load from j → long 1; add long 1 and long 1 → long 2; store long 2 to j; store long 2 to k
Pre increment with the def type.
```
def x = 1; (1)
++x;       (2)
```
1. declare def x; implicit cast int 1 to def → def; store def to x
2. load from x → def; implicit cast def to int 1; add int 1 and int 1 → int 2; implicit cast int 2 to def; store def to x

Pre Decrement

Use the pre decrement operator '--' to DECREASE the value of a numeric type variable/field by 1. An extra implicit cast is necessary to return the promoted numeric type value to the original numeric type value of the variable/field for the following types: byte, short, and char. If a variable/field is read as part of an expression the value is loaded after the decrement.

Errors

If the variable/field is a non-numeric type.

Grammar

pre_increment: '--' ( variable | field );

Promotion

original	promoted	implicit
byte	int	byte
short	int	short
char	int	char
int	int
long	long
float	float
double	double
def	def

original

promoted

implicit

byte

int

byte

short

int

short

char

int

char

int

long

float

double

def

Examples

Pre decrement with different numeric types.
```
short i = 0; (1)
--i;         (2)
long j = 1;  (3)
long k;      (4)
k = --j;     (5)
```
1. declare short i; store short 0 to i
2. load from i → short 0; promote short 0: result int; subtract int 1 from int 0 → int -1; implicit cast int -1 to short -1; store short -1 to i
3. declare long j; implicit cast int 1 to long 1 → long 1; store long 1 to j
4. declare long k; store default long 0 to k
5. load from j → long 1; subtract long 1 from long 1 → long 0; store long 0 to j store long 0 to k;
Pre decrement operator with the def type.
```
def x = 1; (1)
--x;       (2)
```
1. declare def x; implicit cast int 1 to def → def; store def to x
2. load from x → def; implicit cast def to int 1; subtract int 1 from int 1 → int 0; implicit cast int 0 to def; store def to x

Unary Positive

Use the unary positive operator '+' to the preserve the IDENTITY of a numeric type value.

Errors

If the value is a non-numeric type.

Grammar

unary_positive: '+' expression;

Examples

Unary positive with different numeric types.
```
int x = +1;  (1)
long y = +x; (2)
```
1. declare int x; identity int 1 → int 1; store int 1 to x
2. declare long y; load from x → int 1; identity int 1 → int 1; implicit cast int 1 to long 1 → long 1; store long 1 to y
Unary positive with the def type.
```
def z = +1; (1)
int i = +z; (2)
```
1. declare def z; identity int 1 → int 1; implicit cast int 1 to def; store def to z
2. declare int i; load from z → def; implicit cast def to int 1; identity int 1 → int 1; store int 1 to i;

Unary Negative

Use the unary negative operator '-' to NEGATE a numeric type value.

Errors

If the value is a non-numeric type.

Grammar

unary_negative: '-' expression;

Examples

Unary negative with different numeric types.
```
int x = -1;  (1)
long y = -x; (2)
```
1. declare int x; negate int 1 → int -1; store int -1 to x
2. declare long y; load from x → int 1; negate int -1 → int 1; implicit cast int 1 to long 1 → long 1; store long 1 to y
Unary negative with the def type.
```
def z = -1; (1)
int i = -z; (2)
```
1. declare def z; negate int 1 → int -1; implicit cast int -1 to def; store def to z
2. declare int i; load from z → def; implicit cast def to int -1; negate int -1 → int 1; store int 1 to i;

Bitwise Not

Use the bitwise not operator '~' to NOT each bit in an integer type value where a 1-bit is flipped to a resultant 0-bit and a 0-bit is flipped to a resultant 1-bit.

Errors

If the value is a non-integer type.

Bits

original	result
1	0
0	1

original

result

Grammar

bitwise_not: '~' expression;

Promotion

original	promoted
byte	int
short	int
char	int
int	int
long	long
def	def

original

promoted

byte

int

short

int

char

int

long

def

Examples

Bitwise not with different numeric types.
```
byte b = 1;  (1)
int i = ~b;  (2)
long l = ~i; (3)
```
1. declare byte x; store byte 1 to b
2. declare int i; load from b → byte 1; implicit cast byte 1 to int 1 → int 1; bitwise not int 1 → int -2; store int -2 to i
3. declare long l; load from i → int -2; implicit cast int -2 to long -2 → long -2; bitwise not long -2 → long 1; store long 1 to l
Bitwise not with the def type.
```
def d = 1;  (1)
def e = ~d; (2)
```
1. declare def d; implicit cast int 1 to def → def; store def to d;
2. declare def e; load from d → def; implicit cast def to int 1 → int 1; bitwise not int 1 → int -2; implicit cast int 1 to def → def; store def to e

Multiplication

Use the multiplication operator '*' to MULTIPLY together two numeric type values. Rules for resultant overflow and NaN values follow the JVM specification.

Errors

If either of the values is a non-numeric type.

Grammar

multiplication: expression '*' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Multiplication with different numeric types.
```
int i = 5*4;      (1)
double d = i*7.0; (2)
```
1. declare int i; multiply int 4 by int 5 → int 20; store int 20 in i
2. declare double d; load from int i → int 20; promote int 20 and double 7.0: result double; implicit cast int 20 to double 20.0 → double 20.0; multiply double 20.0 by double 7.0 → double 140.0; store double 140.0 to d
Multiplication with the def type.
```
def x = 5*4; (1)
def y = x*2; (2)
```
1. declare def x; multiply int 5 by int 4 → int 20; implicit cast int 20 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 20; multiply int 20 by int 2 → int 40; implicit cast int 40 to def → def; store def to y

Division

Use the division operator '/' to DIVIDE one numeric type value by another. Rules for NaN values and division by zero follow the JVM specification. Division with integer values drops the remainder of the resultant value.

Errors

If either of the values is a non-numeric type.
If a left-hand side integer type value is divided by a right-hand side integer type value of 0.

Grammar

division: expression '/' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Division with different numeric types.
```
int i = 29/4;     (1)
double d = i/7.0; (2)
```
1. declare int i; divide int 29 by int 4 → int 7; store int 7 in i
2. declare double d; load from int i → int 7; promote int 7 and double 7.0: result double; implicit cast int 7 to double 7.0 → double 7.0; divide double 7.0 by double 7.0 → double 1.0; store double 1.0 to d
Division with the def type.
```
def x = 5/4; (1)
def y = x/2; (2)
```
1. declare def x; divide int 5 by int 4 → int 1; implicit cast int 1 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 1; divide int 1 by int 2 → int 0; implicit cast int 0 to def → def; store def to y

Remainder

Use the remainder operator '%' to calculate the REMAINDER for division between two numeric type values. Rules for NaN values and division by zero follow the JVM specification.

Errors

If either of the values is a non-numeric type.

Grammar

remainder: expression '%' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Remainder with different numeric types.
```
int i = 29%4;     (1)
double d = i%7.0; (2)
```
1. declare int i; remainder int 29 by int 4 → int 1; store int 7 in i
2. declare double d; load from int i → int 1; promote int 1 and double 7.0: result double; implicit cast int 1 to double 1.0 → double 1.0; remainder double 1.0 by double 7.0 → double 1.0; store double 1.0 to d
Remainder with the def type.
```
def x = 5%4; (1)
def y = x%2; (2)
```
1. declare def x; remainder int 5 by int 4 → int 1; implicit cast int 1 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 1; remainder int 1 by int 2 → int 1; implicit cast int 1 to def → def; store def to y

Addition

Use the addition operator '+' to ADD together two numeric type values. Rules for resultant overflow and NaN values follow the JVM specification.

Errors

If either of the values is a non-numeric type.

Grammar

addition: expression '+' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Addition operator with different numeric types.
```
int i = 29+4;     (1)
double d = i+7.0; (2)
```
1. declare int i; add int 29 and int 4 → int 33; store int 33 in i
2. declare double d; load from int i → int 33; promote int 33 and double 7.0: result double; implicit cast int 33 to double 33.0 → double 33.0; add double 33.0 and double 7.0 → double 40.0; store double 40.0 to d
Addition with the def type.
```
def x = 5+4; (1)
def y = x+2; (2)
```
1. declare def x; add int 5 and int 4 → int 9; implicit cast int 9 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 9; add int 9 and int 2 → int 11; implicit cast int 11 to def → def; store def to y

Subtraction

Use the subtraction operator '-' to SUBTRACT a right-hand side numeric type value from a left-hand side numeric type value. Rules for resultant overflow and NaN values follow the JVM specification.

Errors

If either of the values is a non-numeric type.

Grammar

subtraction: expression '-' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Subtraction with different numeric types.
```
int i = 29-4;     (1)
double d = i-7.5; (2)
```
1. declare int i; subtract int 4 from int 29 → int 25; store int 25 in i
2. declare double d load from int i → int 25; promote int 25 and double 7.5: result double; implicit cast int 25 to double 25.0 → double 25.0; subtract double 33.0 by double 7.5 → double 25.5; store double 25.5 to d
Subtraction with the def type.
```
def x = 5-4; (1)
def y = x-2; (2)
```
1. declare def x; subtract int 4 and int 5 → int 1; implicit cast int 1 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 1; subtract int 2 from int 1 → int -1; implicit cast int -1 to def → def; store def to y

Left Shift

Use the left shift operator '<<' to SHIFT lower order bits to higher order bits in a left-hand side integer type value by the distance specified in a right-hand side integer type value.

Errors

If either of the values is a non-integer type.
If the right-hand side value cannot be cast to an int type.

Grammar

left_shift: expression '<<' expression;

Promotion

The left-hand side integer type value is promoted as specified in the table below. The right-hand side integer type value is always implicitly cast to an int type value and truncated to the number of bits of the promoted type value.

original	promoted
byte	int
short	int
char	int
int	int
long	long
def	def

original

promoted

byte

int

short

int

char

int

long

def

Examples

Left shift with different integer types.
```
int i = 4 << 1;   (1)
long l = i << 2L; (2)
```
1. declare int i; left shift int 4 by int 1 → int 8; store int 8 in i
2. declare long l load from int i → int 8; implicit cast long 2 to int 2 → int 2; left shift int 8 by int 2 → int 32; implicit cast int 32 to long 32 → long 32; store long 32 to l
Left shift with the def type.
```
def x = 4 << 2; (1)
def y = x << 1; (2)
```
1. declare def x; left shift int 4 by int 2 → int 16; implicit cast int 16 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 16; left shift int 16 by int 1 → int 32; implicit cast int 32 to def → def; store def to y

Right Shift

Use the right shift operator '>>' to SHIFT higher order bits to lower order bits in a left-hand side integer type value by the distance specified in a right-hand side integer type value. The highest order bit of the left-hand side integer type value is preserved.

Errors

If either of the values is a non-integer type.
If the right-hand side value cannot be cast to an int type.

Grammar

right_shift: expression '>>' expression;

Promotion

original	promoted
byte	int
short	int
char	int
int	int
long	long
def	def

original

promoted

byte

int

short

int

char

int

long

def

Examples

Right shift with different integer types.
```
int i = 32 >> 1;  (1)
long l = i >> 2L; (2)
```
1. declare int i; right shift int 32 by int 1 → int 16; store int 16 in i
2. declare long l load from int i → int 16; implicit cast long 2 to int 2 → int 2; right shift int 16 by int 2 → int 4; implicit cast int 4 to long 4 → long 4; store long 4 to l
Right shift with the def type.
```
def x = 16 >> 2; (1)
def y = x >> 1;  (2)
```
1. declare def x; right shift int 16 by int 2 → int 4; implicit cast int 4 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 4; right shift int 4 by int 1 → int 2; implicit cast int 2 to def → def; store def to y

Unsigned Right Shift

Use the unsigned right shift operator '>>>' to SHIFT higher order bits to lower order bits in a left-hand side integer type value by the distance specified in a right-hand side type integer value. The highest order bit of the left-hand side integer type value is not preserved.

Errors

If either of the values is a non-integer type.
If the right-hand side value cannot be cast to an int type.

Grammar

unsigned_right_shift: expression '>>>' expression;

Promotion

original	promoted
byte	int
short	int
char	int
int	int
long	long
def	def

original

promoted

byte

int

short

int

char

int

long

def

Examples

Unsigned right shift with different integer types.
```
int i = -1 >>> 29; (1)
long l = i >>> 2L; (2)
```
1. declare int i; unsigned right shift int -1 by int 29 → int 7; store int 7 in i
2. declare long l load from int i → int 7; implicit cast long 2 to int 2 → int 2; unsigned right shift int 7 by int 2 → int 3; implicit cast int 3 to long 3 → long 3; store long 3 to l
Unsigned right shift with the def type.
```
def x = 16 >>> 2; (1)
def y = x >>> 1;  (2)
```
1. declare def x; unsigned right shift int 16 by int 2 → int 4; implicit cast int 4 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 4; unsigned right shift int 4 by int 1 → int 2; implicit cast int 2 to def → def; store def to y

Bitwise And

Use the bitwise and operator '&' to AND together each bit within two integer type values where if both bits at the same index are 1 the resultant bit is 1 and 0 otherwise.

Errors

If either of the values is a non-integer type.

Bits

	1	0
1	1	0
0	0	0

Grammar

bitwise_and: expression '&' expression;

Promotion

byte

short

char

int

long

def

byte

int

long

def

short

int

long

def

char

int

long

def

int

long

def

long

def

Examples

Bitwise and with different integer types.
```
int i = 5 & 6;   (1)
long l = i & 5L; (2)
```
1. declare int i; bitwise and int 5 and int 6 → int 4; store int 4 in i
2. declare long l load from int i → int 4; promote int 4 and long 5: result long; implicit cast int 4 to long 4 → long 4; bitwise and long 4 and long 5 → long 4; store long 4 to l
Bitwise and with the def type.
```
def x = 15 & 6; (1)
def y = x & 5;  (2)
```
1. declare def x; bitwise and int 15 and int 6 → int 6; implicit cast int 6 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 6; bitwise and int 6 and int 5 → int 4; implicit cast int 4 to def → def; store def to y

Bitwise Xor

Use the bitwise xor operator '^' to XOR together each bit within two integer type values where if one bit is a 1 and the other bit is a 0 at the same index the resultant bit is 1 otherwise the resultant bit is 0.

Errors

If either of the values is a non-integer type.

Bits

The following table illustrates the resultant bit from the xoring of two bits.

	1	0
1	0	1
0	1	0

Grammar

bitwise_xor: expression '^' expression;

Promotion

byte

short

char

int

long

def

byte

int

long

def

short

int

long

def

char

int

long

def

int

long

def

long

def

Examples

Bitwise xor with different integer types.
```
int i = 5 ^ 6;   (1)
long l = i ^ 5L; (2)
```
1. declare int i; bitwise xor int 5 and int 6 → int 3; store int 3 in i
2. declare long l load from int i → int 4; promote int 3 and long 5: result long; implicit cast int 3 to long 3 → long 3; bitwise xor long 3 and long 5 → long 6; store long 6 to l
Bitwise xor with the def type.
```
def x = 15 ^ 6; (1)
def y = x ^ 5;  (2)
```
1. declare def x; bitwise xor int 15 and int 6 → int 9; implicit cast int 9 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 9; bitwise xor int 9 and int 5 → int 12; implicit cast int 12 to def → def; store def to y

Bitwise Or

Use the bitwise or operator '|' to OR together each bit within two integer type values where if at least one bit is a 1 at the same index the resultant bit is 1 otherwise the resultant bit is 0.

Errors

If either of the values is a non-integer type.

Bits

The following table illustrates the resultant bit from the oring of two bits.

	1	0
1	1	1
0	1	0

Grammar

bitwise_or: expression '|' expression;

Promotion

byte

short

char

int

long

def

byte

int

long

def

short

int

long

def

char

int

long

def

int

long

def

long

def

Examples

Bitwise or with different integer types.
```
int i = 5 | 6;   (1)
long l = i | 8L; (2)
```
1. declare int i; bitwise or int 5 and int 6 → int 7; store int 7 in i
2. declare long l load from int i → int 7; promote int 7 and long 8: result long; implicit cast int 7 to long 7 → long 7; bitwise or long 7 and long 8 → long 15; store long 15 to l
Bitwise or with the def type.
```
def x = 5 ^ 6; (1)
def y = x ^ 8; (2)
```
1. declare def x; bitwise or int 5 and int 6 → int 7; implicit cast int 7 to def → def; store def in x
2. declare def y; load from x → def; implicit cast def to int 7; bitwise or int 7 and int 8 → int 15; implicit cast int 15 to def → def; store def to y

Operators: Boolean

Boolean Not

Use the boolean not operator '!' to NOT a boolean type value where true is flipped to false and false is flipped to true.

Errors

If a value other than a boolean type value or a value that is castable to a boolean type value is given.

Truth

original	result
true	false
false	true

original

result

true

false

true

Grammar

boolean_not: '!' expression;

Examples

Boolean not with the boolean type.
```
boolean x = !false; (1)
boolean y = !x;     (2)
```
1. declare boolean x; boolean not boolean false → boolean true; store boolean true to x
2. declare boolean y; load from x → boolean true; boolean not boolean true → boolean false; store boolean false to y
Boolean not with the def type.
```
def y = true; (1)
def z = !y;   (2)
```
1. declare def y; implicit cast boolean true to def → def; store true to y
2. declare def z; load from y → def; implicit cast def to boolean true → boolean true; boolean not boolean true → boolean false; implicit cast boolean false to def → def; store def to z

Greater Than

Use the greater than operator '>' to COMPARE two numeric type values where a resultant boolean type value is true if the left-hand side value is greater than to the right-hand side value and false otherwise.

Errors

If either the evaluated left-hand side or the evaluated right-hand side is a non-numeric value.

Grammar

greater_than: expression '>' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Greater than with different numeric types.
```
boolean x = 5 > 4; (1)
double y = 6.0;    (2)
x = 6 > y;         (3)
```
1. declare boolean x; greater than int 5 and int 4 → boolean true; store boolean true to x;
2. declare double y; store double 6.0 to y;
3. load from y → double 6.0 @0; promote int 6 and double 6.0: result double; implicit cast int 6 to double 6.0 @1 → double 6.0 @1; greater than double 6.0 @1 and double 6.0 @0 → boolean false; store boolean false to x
Greater than with def type.
```
int x = 5;       (1)
def y = 7.0;     (2)
def z = y > 6.5; (3)
def a = x > y;   (4)
```
1. declare int x; store int 5 to x
2. declare def y; implicit cast double 7.0 to def → def; store def to y
3. declare def z; load from y → def; implicit cast def to double 7.0 → double 7.0; greater than double 7.0 and double 6.5 → boolean true; implicit cast boolean true to def → def; store def to z
4. declare def a; load from y → def; implicit cast def to double 7.0 → double 7.0; load from x → int 5; promote int 5 and double 7.0: result double; implicit cast int 5 to double 5.0 → double 5.0; greater than double 5.0 and double 7.0 → boolean false; implicit cast boolean false to def → def; store def to z

Greater Than Or Equal

Use the greater than or equal operator '>=' to COMPARE two numeric type values where a resultant boolean type value is true if the left-hand side value is greater than or equal to the right-hand side value and false otherwise.

Errors

If either the evaluated left-hand side or the evaluated right-hand side is a non-numeric value.

Grammar

greater_than_or_equal: expression '>=' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Greater than or equal with different numeric types.
```
boolean x = 5 >= 4; (1)
double y = 6.0;     (2)
x = 6 >= y;         (3)
```
1. declare boolean x; greater than or equal int 5 and int 4 → boolean true; store boolean true to x
2. declare double y; store double 6.0 to y
3. load from y → double 6.0 @0; promote int 6 and double 6.0: result double; implicit cast int 6 to double 6.0 @1 → double 6.0 @1; greater than or equal double 6.0 @1 and double 6.0 @0 → boolean true; store boolean true to x
Greater than or equal with the def type.
```
int x = 5;        (1)
def y = 7.0;      (2)
def z = y >= 7.0; (3)
def a = x >= y;   (4)
```
1. declare int x; store int 5 to x;
2. declare def y implicit cast double 7.0 to def → def; store def to y
3. declare def z; load from y → def; implicit cast def to double 7.0 @0 → double 7.0 @0; greater than or equal double 7.0 @0 and double 7.0 @1 → boolean true; implicit cast boolean true to def → def; store def to z
4. declare def a; load from y → def; implicit cast def to double 7.0 → double 7.0; load from x → int 5; promote int 5 and double 7.0: result double; implicit cast int 5 to double 5.0 → double 5.0; greater than or equal double 5.0 and double 7.0 → boolean false; implicit cast boolean false to def → def; store def to z

Less Than

Use the less than operator '<' to COMPARE two numeric type values where a resultant boolean type value is true if the left-hand side value is less than to the right-hand side value and false otherwise.

Errors

If either the evaluated left-hand side or the evaluated right-hand side is a non-numeric value.

Grammar

less_than: expression '<' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Less than with different numeric types.
```
boolean x = 5 < 4; (1)
double y = 6.0;    (2)
x = 6 < y;         (3)
```
1. declare boolean x; less than int 5 and int 4 → boolean false; store boolean false to x
2. declare double y; store double 6.0 to y
3. load from y → double 6.0 @0; promote int 6 and double 6.0: result double; implicit cast int 6 to double 6.0 @1 → double 6.0 @1; less than double 6.0 @1 and double 6.0 @0 → boolean false; store boolean false to x
Less than with the def type.
```
int x = 5;       (1)
def y = 7.0;     (2)
def z = y < 6.5; (3)
def a = x < y;   (4)
```
1. declare int x; store int 5 to x
2. declare def y; implicit cast double 7.0 to def → def; store def to y
3. declare def z; load from y → def; implicit cast def to double 7.0 → double 7.0; less than double 7.0 and double 6.5 → boolean false; implicit cast boolean false to def → def; store def to z
4. declare def a; load from y → def; implicit cast def to double 7.0 → double 7.0; load from x → int 5; promote int 5 and double 7.0: result double; implicit cast int 5 to double 5.0 → double 5.0; less than double 5.0 and double 7.0 → boolean true; implicit cast boolean true to def → def; store def to z

Less Than Or Equal

Use the less than or equal operator '⇐' to COMPARE two numeric type values where a resultant boolean type value is true if the left-hand side value is less than or equal to the right-hand side value and false otherwise.

Errors

If either the evaluated left-hand side or the evaluated right-hand side is a non-numeric value.

Grammar

greater_than_or_equal: expression '<=' expression;

Promotion

byte

short

char

int

long

float

double

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Examples

Less than or equal with different numeric types.
```
boolean x = 5 <= 4; (1)
double y = 6.0;     (2)
x = 6 <= y;         (3)
```
1. declare boolean x; less than or equal int 5 and int 4 → boolean false; store boolean true to x
2. declare double y; store double 6.0 to y
3. load from y → double 6.0 @0; promote int 6 and double 6.0: result double; implicit cast int 6 to double 6.0 @1 → double 6.0 @1; less than or equal double 6.0 @1 and double 6.0 @0 → boolean true; store boolean true to x
Less than or equal with the def type.
```
int x = 5;        (1)
def y = 7.0;      (2)
def z = y <= 7.0; (3)
def a = x <= y;   (4)
```
1. declare int x; store int 5 to x;
2. declare def y; implicit cast double 7.0 to def → def; store def to y;
3. declare def z; load from y → def; implicit cast def to double 7.0 @0 → double 7.0 @0; less than or equal double 7.0 @0 and double 7.0 @1 → boolean true; implicit cast boolean true to def → def; store def to z
4. declare def a; load from y → def; implicit cast def to double 7.0 → double 7.0; load from x → int 5; promote int 5 and double 7.0: result double; implicit cast int 5 to double 5.0 → double 5.0; less than or equal double 5.0 and double 7.0 → boolean true; implicit cast boolean true to def → def; store def to z

Instanceof

Use the instanceof operator to COMPARE the variable/field type to a specified reference type using the reference type name where a resultant boolean type value is true if the variable/field type is the same as or a descendant of the specified reference type and false otherwise.

Errors

If the reference type name doesn’t exist as specified by the right-hand side.

Grammar

instance_of: ID 'instanceof' TYPE;

Examples

Instance of with different reference types.
```
Map m = new HashMap();            (1)
boolean a = m instanceof HashMap; (2)
boolean b = m instanceof Map;     (3)
```
1. declare Map m; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference; store Map reference to m
2. declare boolean a; load from m → Map reference; implicit cast Map reference to HashMap reference → HashMap reference; instanceof HashMap reference and HashMap → boolean true; store boolean true to a
3. declare boolean b; load from m → Map reference; implicit cast Map reference to HashMap reference → HashMap reference; instanceof HashMap reference and Map → boolean true; store true to b; (note HashMap is a descendant of Map)
Instance of with the def type.
```
def d = new ArrayList();       (1)
boolean a = d instanceof List; (2)
boolean b = d instanceof Map;  (3)
```
1. declare def d; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def; store def to d
2. declare boolean a; load from d → def; implicit cast def to ArrayList reference → ArrayList reference; instanceof ArrayList reference and List → boolean true; store boolean true to a; (note ArrayList is a descendant of List)
3. declare boolean b; load from d → def; implicit cast def to ArrayList reference → ArrayList reference; instanceof ArrayList reference and Map → boolean false; store boolean false to a; (note ArrayList is not a descendant of Map)

Equality Equals

Use the equality equals operator '==' to COMPARE two values where a resultant boolean type value is true if the two values are equal and false otherwise. The member method, equals, is implicitly called when the values are reference type values where the first value is the target of the call and the second value is the argument. This operation is null-safe where if both values are null the resultant boolean type value is true, and if only one value is null the resultant boolean type value is false. A valid comparison is between boolean type values, numeric type values, or reference type values.

Errors

If a comparison is made between a boolean type value and numeric type value.
If a comparison is made between a primitive type value and a reference type value.

Grammar

equality_equals: expression '==' expression;

Promotion

boolean

byte

short

char

int

long

float

double

Reference

def

boolean

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Reference

Object

def

Examples

Equality equals with the boolean type.
```
boolean a = true;  (1)
boolean b = false; (2)
a = a == false;    (3)
b = a == b;        (4)
```
1. declare boolean a; store boolean true to a
2. declare boolean b; store boolean false to b
3. load from a → boolean true; equality equals boolean true and boolean false → boolean false; store boolean false to a
4. load from a → boolean false @0; load from b → boolean false @1; equality equals boolean false @0 and boolean false @1 → boolean false; store boolean false to b
Equality equals with primitive types.
```
int a = 1;          (1)
double b = 2.0;     (2)
boolean c = a == b; (3)
c = 1 == a;         (4)
```
1. declare int a; store int 1 to a
2. declare double b; store double 1.0 to b
3. declare boolean c; load from a → int 1; load from b → double 2.0; promote int 1 and double 2.0: result double; implicit cast int 1 to double 1.0 → double `1.0; equality equals double 1.0 and double 2.0 → boolean false; store boolean false to c
4. load from a → int 1 @1; equality equals int 1 @0 and int 1 @1 → boolean true; store boolean true to c
Equal equals with reference types.
```
List a = new ArrayList(); (1)
List b = new ArrayList(); (2)
a.add(1);                 (3)
boolean c = a == b;       (4)
b.add(1);                 (5)
c = a == b;               (6)
```
1. declare List a; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to a
2. declare List b; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to b
3. load from a → List reference; call add on List reference with arguments (int 1)
4. declare boolean c; load from a → List reference @0; load from b → List reference @1; call equals on List reference @0 with arguments (List reference @1) → boolean false; store boolean false to c
5. load from b → List reference; call add on List reference with arguments (int 1)
6. load from a → List reference @0; load from b → List reference @1; call equals on List reference @0 with arguments (List reference @1) → boolean true; store boolean true to c
Equality equals with null.
```
Object a = null;       (1)
Object b = null;       (2)
boolean c = a == null; (3)
c = a == b;            (4)
b = new Object();      (5)
c = a == b;            (6)
```
1. declare Object a; store null to a
2. declare Object b; store null to b
3. declare boolean c; load from a → null @0; equality equals null @0 and null @1 → boolean true; store boolean true to c
4. load from a → null @0; load from b → null @1; equality equals null @0 and null @1 → boolean true; store boolean true to c
5. allocate Object instance → Object reference; store Object reference to b
6. load from a → Object reference; load from b → null; call equals on Object reference with arguments (null) → boolean false; store boolean false to c
Equality equals with the def type.
```
def a = 0;               (1)
def b = 1;               (2)
boolean c = a == b;      (3)
def d = new HashMap();   (4)
def e = new ArrayList(); (5)
c = d == e;              (6)
```
1. declare def a; implicit cast int 0 to def → def; store def to a;
2. declare def b; implicit cast int 1 to def → def; store def to b;
3. declare boolean c; load from a → def; implicit cast a to int 0 → int 0; load from b → def; implicit cast b to int 1 → int 1; equality equals int 0 and int 1 → boolean false; store boolean false to c
4. declare def d; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def store def to d;
5. declare def e; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def store def to d;
6. load from d → def; implicit cast def to HashMap reference → HashMap reference; load from e → def; implicit cast def to ArrayList reference → ArrayList reference; call equals on HashMap reference with arguments (ArrayList reference) → boolean false; store boolean false to c

Equality Not Equals

Use the equality not equals operator '!=' to COMPARE two values where a resultant boolean type value is true if the two values are NOT equal and false otherwise. The member method, equals, is implicitly called when the values are reference type values where the first value is the target of the call and the second value is the argument with the resultant boolean type value flipped. This operation is null-safe where if both values are null the resultant boolean type value is false, and if only one value is null the resultant boolean type value is true. A valid comparison is between boolean type values, numeric type values, or reference type values.

Errors

If a comparison is made between a boolean type value and numeric type value.
If a comparison is made between a primitive type value and a reference type value.

Grammar

equality_not_equals: expression '!=' expression;

Promotion

boolean

byte

short

char

int

long

float

double

Reference

def

boolean

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Reference

Object

def

Examples

Equality not equals with the boolean type.
```
boolean a = true;  (1)
boolean b = false; (2)
a = a != false;    (3)
b = a != b;        (4)
```
1. declare boolean a; store boolean true to a
2. declare boolean b; store boolean false to b
3. load from a → boolean true; equality not equals boolean true and boolean false → boolean true; store boolean true to a
4. load from a → boolean true; load from b → boolean false; equality not equals boolean true and boolean false → boolean true; store boolean true to b
Equality not equals with primitive types.
```
int a = 1;          (1)
double b = 2.0;     (2)
boolean c = a != b; (3)
c = 1 != a;         (4)
```
1. declare int a; store int 1 to a
2. declare double b; store double 1.0 to b
3. declare boolean c; load from a → int 1; load from b → double 2.0; promote int 1 and double 2.0: result double; implicit cast int 1 to double 1.0 → double `1.0; equality not equals double 1.0 and double 2.0 → boolean true; store boolean true to c
4. load from a → int 1 @1; equality not equals int 1 @0 and int 1 @1 → boolean false; store boolean false to c
Equality not equals with reference types.
```
List a = new ArrayList(); (1)
List b = new ArrayList(); (2)
a.add(1);                 (3)
boolean c = a == b;       (4)
b.add(1);                 (5)
c = a == b;               (6)
```
1. declare List a; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to a
2. declare List b; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to b
3. load from a → List reference; call add on List reference with arguments (int 1)
4. declare boolean c; load from a → List reference @0; load from b → List reference @1; call equals on List reference @0 with arguments (List reference @1) → boolean false; boolean not boolean false → boolean true store boolean true to c
5. load from b → List reference; call add on List reference with arguments (int 1)
6. load from a → List reference @0; load from b → List reference @1; call equals on List reference @0 with arguments (List reference @1) → boolean true; boolean not boolean true → boolean false; store boolean false to c
Equality not equals with null.
```
Object a = null;       (1)
Object b = null;       (2)
boolean c = a == null; (3)
c = a == b;            (4)
b = new Object();      (5)
c = a == b;            (6)
```
1. declare Object a; store null to a
2. declare Object b; store null to b
3. declare boolean c; load from a → null @0; equality not equals null @0 and null @1 → boolean false; store boolean false to c
4. load from a → null @0; load from b → null @1; equality not equals null @0 and null @1 → boolean false; store boolean false to c
5. allocate Object instance → Object reference; store Object reference to b
6. load from a → Object reference; load from b → null; call equals on Object reference with arguments (null) → boolean false; boolean not boolean false → boolean true; store boolean true to c
Equality not equals with the def type.
```
def a = 0;               (1)
def b = 1;               (2)
boolean c = a == b;      (3)
def d = new HashMap();   (4)
def e = new ArrayList(); (5)
c = d == e;              (6)
```
1. declare def a; implicit cast int 0 to def → def; store def to a;
2. declare def b; implicit cast int 1 to def → def; store def to b;
3. declare boolean c; load from a → def; implicit cast a to int 0 → int 0; load from b → def; implicit cast b to int 1 → int 1; equality equals int 0 and int 1 → boolean false; store boolean false to c
4. declare def d; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def store def to d;
5. declare def e; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def store def to d;
6. load from d → def; implicit cast def to HashMap reference → HashMap reference; load from e → def; implicit cast def to ArrayList reference → ArrayList reference; call equals on HashMap reference with arguments (ArrayList reference) → boolean false; store boolean false to c

Identity Equals

Use the identity equals operator '===' to COMPARE two values where a resultant boolean type value is true if the two values are equal and false otherwise. A reference type value is equal to another reference type value if both values refer to same instance on the heap or if both values are null. A valid comparison is between boolean type values, numeric type values, or reference type values.

Errors

If a comparison is made between a boolean type value and numeric type value.
If a comparison is made between a primitive type value and a reference type value.

Grammar

identity_equals: expression '===' expression;

Promotion

boolean

byte

short

char

int

long

float

double

Reference

def

boolean

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Reference

Object

def

Examples

Identity equals with reference types.
```
List a = new ArrayList(); (1)
List b = new ArrayList(); (2)
List c = a;               (3)
boolean c = a === b;      (4)
c = a === c;              (5)
```
1. declare List a; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to a
2. declare List b; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to b
3. load from a → List reference; store List reference to c
4. declare boolean c; load from a → List reference @0; load from b → List reference @1; identity equals List reference @0 and List reference @1 → boolean false store boolean false to c
5. load from a → List reference @0; load from c → List reference @1; identity equals List reference @0 and List reference @1 → boolean true store boolean true to c (note List reference @0 and List reference @1 refer to the same instance)
Identity equals with null.
```
Object a = null;        (1)
Object b = null;        (2)
boolean c = a === null; (3)
c = a === b;            (4)
b = new Object();       (5)
c = a === b;            (6)
```
1. declare Object a; store null to a
2. declare Object b; store null to b
3. declare boolean c; load from a → null @0; identity equals null @0 and null @1 → boolean true; store boolean true to c
4. load from a → null @0; load from b → null @1; identity equals null @0 and null @1 → boolean true; store boolean true to c
5. allocate Object instance → Object reference; store Object reference to b
6. load from a → Object reference; load from b → null; identity equals Object reference and null → boolean false; store boolean false to c
Identity equals with the def type.
```
def a = new HashMap();   (1)
def b = new ArrayList(); (2)
boolean c = a === b;     (3)
b = a;                   (4)
c = a === b;             (5)
```
1. declare def d; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def store def to d
2. declare def e; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def store def to d
3. declare boolean c; load from a → def; implicit cast def to HashMap reference → HashMap reference; load from b → def; implicit cast def to ArrayList reference → ArrayList reference; identity equals HashMap reference and ArrayList reference → boolean false; store boolean false to c
4. load from a → def; store def to b
5. load from a → def; implicit cast def to HashMap reference @0 → HashMap reference @0; load from b → def; implicit cast def to HashMap reference @1 → HashMap reference @1; identity equals HashMap reference @0 and HashMap reference @1 → boolean true; store boolean true to b; (note HashMap reference @0 and HashMap reference @1 refer to the same instance)

Identity Not Equals

Use the identity not equals operator '!==' to COMPARE two values where a resultant boolean type value is true if the two values are NOT equal and false otherwise. A reference type value is not equal to another reference type value if both values refer to different instances on the heap or if one value is null and the other is not. A valid comparison is between boolean type values, numeric type values, or reference type values.

Errors

If a comparison is made between a boolean type value and numeric type value.
If a comparison is made between a primitive type value and a reference type value.

Grammar

identity_not_equals: expression '!==' expression;

Promotion

boolean

byte

short

char

int

long

float

double

Reference

def

boolean

def

byte

int

long

float

double

def

short

int

long

float

double

def

char

int

long

float

double

def

int

long

float

double

def

long

float

double

def

float

double

def

double

def

Reference

Object

def

Examples

Identity not equals with reference type values.
```
List a = new ArrayList(); (1)
List b = new ArrayList(); (2)
List c = a;               (3)
boolean c = a !== b;      (4)
c = a !== c;              (5)
```
1. declare List a; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to a
2. declare List b; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to b
3. load from a → List reference; store List reference to c
4. declare boolean c; load from a → List reference @0; load from b → List reference @1; identity not equals List reference @0 and List reference @1 → boolean true store boolean true to c
5. load from a → List reference @0; load from c → List reference @1; identity not equals List reference @0 and List reference @1 → boolean false store boolean false to c (note List reference @0 and List reference @1 refer to the same instance)
Identity not equals with null.
```
Object a = null;        (1)
Object b = null;        (2)
boolean c = a !== null; (3)
c = a !== b;            (4)
b = new Object();       (5)
c = a !== b;            (6)
```
1. declare Object a; store null to a
2. declare Object b; store null to b
3. declare boolean c; load from a → null @0; identity not equals null @0 and null @1 → boolean false; store boolean false to c
4. load from a → null @0; load from b → null @1; identity not equals null @0 and null @1 → boolean false; store boolean false to c
5. allocate Object instance → Object reference; store Object reference to b
6. load from a → Object reference; load from b → null; identity not equals Object reference and null → boolean true; store boolean true to c
Identity not equals with the def type.
```
def a = new HashMap();   (1)
def b = new ArrayList(); (2)
boolean c = a !== b;     (3)
b = a;                   (4)
c = a !== b;             (5)
```
1. declare def d; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def store def to d
2. declare def e; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def store def to d
3. declare boolean c; load from a → def; implicit cast def to HashMap reference → HashMap reference; load from b → def; implicit cast def to ArrayList reference → ArrayList reference; identity not equals HashMap reference and ArrayList reference → boolean true; store boolean true to c
4. load from a → def; store def to b
5. load from a → def; implicit cast def to HashMap reference @0 → HashMap reference @0; load from b → def; implicit cast def to HashMap reference @1 → HashMap reference @1; identity not equals HashMap reference @0 and HashMap reference @1 → boolean false; store boolean false to b; (note HashMap reference @0 and HashMap reference @1 refer to the same instance)

Boolean Xor

Use the boolean xor operator '^' to XOR together two boolean type values where if one boolean type value is true and the other is false the resultant boolean type value is true and false otherwise.

Errors

If either evaluated value is a value other than a boolean type value or a value that is castable to a boolean type value.

Truth

true

false

true

false

true

false

true

false

Grammar

boolean_xor: expression '^' expression;

Examples

Boolean xor with the boolean type.
```
boolean x = false;    (1)
boolean y = x ^ true; (2)
y = y ^ x;            (3)
```
1. declare boolean x; store boolean false to x
2. declare boolean y; load from x → boolean false boolean xor boolean false and boolean true → boolean true; store boolean true to y
3. load from y → boolean true @0; load from x → boolean true @1; boolean xor boolean true @0 and boolean true @1 → boolean false; store boolean false to y
Boolean xor with the def type.
```
def x = false;    (1)
def y = x ^ true; (2)
y = y ^ x;        (3)
```
1. declare def x; implicit cast boolean false to def → def; store def to x
2. declare def y; load from x → def; implicit cast def to boolean false → boolean false; boolean xor boolean false and boolean true → boolean true; implicit cast boolean true to def → def; store def to y
3. load from y → def; implicit cast def to boolean true @0 → boolean true @0; load from x → def; implicit cast def to boolean true @1 → boolean true @1; boolean xor boolean true @0 and boolean true @1 → boolean false; implicit cast boolean false → def; store def to y

Boolean And

Use the boolean and operator '&&' to AND together two boolean type values where if both boolean type values are true the resultant boolean type value is true and false otherwise.

Errors

If either evaluated value is a value other than a boolean type value or a value that is castable to a boolean type value.

Truth

true

false

true

false

Grammar

boolean_and: expression '&&' expression;

Examples

Boolean and with the boolean type.
```
boolean x = true;      (1)
boolean y = x && true; (2)
x = false;             (3)
y = y && x;            (4)
```
1. declare boolean x; store boolean true to x
2. declare boolean y; load from x → boolean true @0; boolean and boolean true @0 and boolean true @1 → boolean true; store boolean true to y
3. store boolean false to x
4. load from y → boolean true; load from x → boolean false; boolean and boolean true and boolean false → boolean false; store boolean false to y
Boolean and with the def type.
```
def x = true;      (1)
def y = x && true; (2)
x = false;         (3)
y = y && x;        (4)
```
1. declare def x; implicit cast boolean true to def → def; store def to x
2. declare def y; load from x → def; implicit cast def to boolean true @0 → boolean true @0; boolean and boolean true @0 and boolean true @1 → boolean true; implicit cast boolean true to def → def; store def to y
3. implicit cast boolean false to def → def; store def to x;
4. load from y → def; implicit cast def to boolean true → boolean true; load from x → def; implicit cast def to boolean false → boolean false; boolean and boolean true and boolean false → boolean false; implicit cast boolean false → def; store def to y

Boolean Or

Use the boolean or operator '||' to OR together two boolean type values where if either one of the boolean type values is true the resultant boolean type value is true and false otherwise.

Errors

If either evaluated value is a value other than a boolean type value or a value that is castable to a boolean type value.

Truth

true

false

true

false

true

false

Grammar:

boolean_and: expression '||' expression;

Examples

Boolean or with the boolean type.
```
boolean x = false;     (1)
boolean y = x || true; (2)
y = false;             (3)
y = y || x;            (4)
```
1. declare boolean x; store boolean false to x
2. declare boolean y; load from x → boolean false; boolean or boolean false and boolean true → boolean true; store boolean true to y
3. store boolean false to y
4. load from y → boolean false @0; load from x → boolean false @1; boolean or boolean false @0 and boolean false @1 → boolean false; store boolean false to y
Boolean or with the def type.
```
def x = false;     (1)
def y = x || true; (2)
y = false;         (3)
y = y || x;        (4)
```
1. declare def x; implicit cast boolean false to def → def; store def to x
2. declare def y; load from x → def; implicit cast def to boolean false → boolean true; boolean or boolean false and boolean true → boolean true; implicit cast boolean true to def → def; store def to y
3. implicit cast boolean false to def → def; store def to y;
4. load from y → def; implicit cast def to boolean false @0 → boolean false @0; load from x → def; implicit cast def to boolean false @1 → boolean false @1; boolean or boolean false @0 and boolean false @1 → boolean false; implicit cast boolean false → def; store def to y

Operators: Reference

Method Call

Use the method call operator '()' to call a member method on a reference type value. Implicit boxing/unboxing is evaluated as necessary per argument during the method call. When a method call is made on a target def type value, the parameters and return type value are considered to also be of the def type and are evaluated at run-time.

An overloaded method is one that shares the same name with two or more methods. A method is overloaded based on arity where the same name is re-used for multiple methods as long as the number of parameters differs.

Errors

If the reference type value is null.
If the member method name doesn’t exist for a given reference type value.
If the number of arguments passed in is different from the number of specified parameters.
If the arguments cannot be implicitly cast or implicitly boxed/unboxed to the correct type values for the parameters.

Grammar

method_call: '.' ID arguments;
arguments: '(' (expression (',' expression)*)? ')';

Examples

Method calls on different reference types.
```
Map m = new HashMap();                         (1)
m.put(1, 2);                                   (2)
int z = m.get(1);                              (3)
def d = new ArrayList();                       (4)
d.add(1);                                      (5)
int i = Integer.parseInt(d.get(0).toString()); (6)
```
1. declare Map m; allocate HashMap instance → HashMap reference; store HashMap reference to m
2. load from m → Map reference; implicit cast int 1 to def → def; implicit cast int 2 to def → def; call put on Map reference with arguments (int 1, int 2)
3. declare int z; load from m → Map reference; call get on Map reference with arguments (int 1) → def; implicit cast def to int 2 → int 2; store int 2 to z
4. declare def d; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList to def → def; store def to d
5. load from d → def; implicit cast def to ArrayList reference → ArrayList reference call add on ArrayList reference with arguments (int 1);
6. declare int i; load from d → def; implicit cast def to ArrayList reference → ArrayList reference call get on ArrayList reference with arguments (int 1) → def; implicit cast def to Integer 1 reference → Integer 1 reference; call toString on Integer 1 reference → String '1'; call parseInt on Integer with arguments (String '1') → int 1; store int 1 in i;

Field Access

Use the field access operator '.' to store a value to or load a value from a reference type member field.

Errors

If the reference type value is null.
If the member field name doesn’t exist for a given reference type value.

Grammar

field_access: '.' ID;

Examples

The examples use the following reference type definition:

name:
  Example

non-static member fields:
  * int x
  * def y
  * List z

Field access with the Example type.
```
Example example = new Example(); (1)
example.x = 1;                   (2)
example.y = example.x;           (3)
example.z = new ArrayList();     (4)
example.z.add(1);                (5)
example.x = example.z.get(0);    (6)
```
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)
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
5. load from example → Example reference; load from z of Example reference → List reference; call add on List reference with arguments (int 1)
6. load from example → Example reference @0; load from example → Example reference @1; load from z of Example reference @1 → List reference; call get on List reference with arguments (int 0) → int 1; store int 1 in x of List reference @0; (note Example reference @0 and Example reference @1 are the same)

Null Safe

Use the null safe operator '?.' instead of the method call operator or field access operator to ensure a reference type value is non-null before a method call or field access. A null value will be returned if the reference type value is null, otherwise the method call or field access is evaluated.

Errors

If the method call return type value or the field access type value is not a reference type value and is not implicitly castable to a reference type value.

Grammar

null_safe: null_safe_method_call
         | null_safe_field_access
         ;

null_safe_method_call: '?.' ID arguments;
arguments: '(' (expression (',' expression)*)? ')';

null_safe_field_access: '?.' ID;

Examples

The examples use the following reference type definition:

name:
  Example

non-static member methods:
  * List factory()

non-static member fields:
  * List x

Null safe without a null value.
```
Example example = new Example(); (1)
List x = example?.factory();     (2)
```
1. declare Example example; allocate Example instance → Example reference; store Example reference to example
2. declare List x; load from example → Example reference; null safe call factory on Example reference → List reference; store List reference to x;
Null safe with a null value;
```
Example example = null; (1)
List x = example?.x;    (2)
```
1. declare Example example; store null to example
2. declare List x; load from example → Example reference; null safe access x on Example reference → null; store null to x; (note the null safe operator returned null because example is null)

List Initialization

Use the list initialization operator '[]' to allocate an List type instance to the heap with a set of pre-defined values. Each value used to initialize the List type instance is cast to a def type value upon insertion into the List type instance using the add method. The order of the specified values is maintained.

Grammar

list_initialization: '[' expression (',' expression)* ']'
                   | '[' ']';

Examples

List initialization of an empty List type value.
```
List empty = []; (1)
```
1. declare List empty; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to empty
List initialization with static values.
```
List list = [1, 2, 3]; (1)
```
1. declare List list; allocate ArrayList instance → ArrayList reference; call add on ArrayList reference with arguments(int 1); call add on ArrayList reference with arguments(int 2); call add on ArrayList reference with arguments(int 3); implicit cast ArrayList reference to List reference → List reference; store List reference to list
List initialization with non-static values.
```
int i = 1;                  (1)
long l = 2L;                (2)
float f = 3.0F;             (3)
double d = 4.0;             (4)
String s = "5";             (5)
List list = [i, l, f*d, s]; (6)
```
1. declare int i; store int 1 to i
2. declare long l; store long 2 to l
3. declare float f; store float 3.0 to f
4. declare double d; store double 4.0 to d
5. declare String s; store String "5" to s
6. declare List list; allocate ArrayList instance → ArrayList reference; load from i → int 1; call add on ArrayList reference with arguments(int 1); load from l → long 2; call add on ArrayList reference with arguments(long 2); load from f → float 3.0; load from d → double 4.0; promote float 3.0 and double 4.0: result double; implicit cast float 3.0 to double 3.0 → double 3.0; multiply double 3.0 and double 4.0 → double 12.0; call add on ArrayList reference with arguments(double 12.0); load from s → String "5"; call add on ArrayList reference with arguments(String "5"); implicit cast ArrayList reference to List reference → List reference; store List reference to list

List Access

Use the list access operator '[]' as a shortcut for a set method call or get method call made on a List type value.

Errors

If a value other than a List type value is accessed.
If a non-integer type value is used as an index for a set method call or get method call.

Grammar

list_access: '[' expression ']'

Examples

List access with the List type.
```
List list = new ArrayList(); (1)
list.add(1);                 (2)
list.add(2);                 (3)
list.add(3);                 (4)
list[0] = 2;                 (5)
list[1] = 5;                 (6)
int x = list[0] + list[1];   (7)
int y = 1;                   (8)
int z = list[y];             (9)
```
1. declare List list; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to list
2. load from list → List reference; call add on List reference with arguments(int 1)
3. load from list → List reference; call add on List reference with arguments(int 2)
4. load from list → List reference; call add on List reference with arguments(int 3)
5. load from list → List reference; call set on List reference with arguments(int 0, int 2)
6. load from list → List reference; call set on List reference with arguments(int 1, int 5)
7. declare int x; load from list → List reference; call get on List reference with arguments(int 0) → def; implicit cast def to int 2 → int 2; load from list → List reference; call get on List reference with arguments(int 1) → def; implicit cast def to int 5 → int 5; add int 2 and int 5 → int 7; store int 7 to x
8. declare int y; store int 1 int y
9. declare int z; load from list → List reference; load from y → int 1; call get on List reference with arguments(int 1) → def; implicit cast def to int 5 → int 5; store int 5 to z
List access with the def type.
```
def d = new ArrayList(); (1)
d.add(1);                (2)
d.add(2);                (3)
d.add(3);                (4)
d[0] = 2;                (5)
d[1] = 5;                (6)
def x = d[0] + d[1];     (7)
def y = 1;               (8)
def z = d[y];            (9)
```
1. declare List d; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def; store def to d
2. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call add on ArrayList reference with arguments(int 1)
3. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call add on ArrayList reference with arguments(int 2)
4. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call add on ArrayList reference with arguments(int 3)
5. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call set on ArrayList reference with arguments(int 0, int 2)
6. load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call set on ArrayList reference with arguments(int 1, int 5)
7. declare def x; load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call get on ArrayList reference with arguments(int 0) → def; implicit cast def to int 2 → int 2; load from d → def; implicit cast def to ArrayList reference → ArrayList reference; call get on ArrayList reference with arguments(int 1) → def; implicit cast def to int 2 → int 2; add int 2 and int 5 → int 7; store int 7 to x
8. declare int y; store int 1 int y
9. declare int z; load from d → ArrayList reference; load from y → def; implicit cast def to int 1 → int 1; call get on ArrayList reference with arguments(int 1) → def; store def to z

Map Initialization

Use the map initialization operator '[:]' to allocate a Map type instance to the heap with a set of pre-defined values. Each pair of values used to initialize the Map type instance are cast to def type values upon insertion into the Map type instance using the put method.

Grammar

map_initialization: '[' key_pair (',' key_pair)* ']'
                  | '[' ':' ']';
key_pair: expression ':' expression

Examples

Map initialization of an empty Map type value.
```
Map empty = [:]; (1)
```
1. declare Map empty; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference → Map reference; store Map reference to empty
Map initialization with static values.
```
Map map = [1:2, 3:4, 5:6]; (1)
```
1. declare Map map; allocate HashMap instance → HashMap reference; call put on HashMap reference with arguments(int 1, int 2); call put on HashMap reference with arguments(int 3, int 4); call put on HashMap reference with arguments(int 5, int 6); implicit cast HashMap reference to Map reference → Map reference; store Map reference to map
Map initialization with non-static values.
```
byte b = 0;                  (1)
int i = 1;                   (2)
long l = 2L;                 (3)
float f = 3.0F;              (4)
double d = 4.0;              (5)
String s = "5";              (6)
Map map = [b:i, l:f*d, d:s]; (7)
```
1. declare byte b; store byte 0 to b
2. declare int i; store int 1 to i
3. declare long l; store long 2 to l
4. declare float f; store float 3.0 to f
5. declare double d; store double 4.0 to d
6. declare String s; store String "5" to s
7. declare Map map; allocate HashMap instance → HashMap reference; load from b → byte 0; load from i → int 1; call put on HashMap reference with arguments(byte 0, int 1); load from l → long 2; load from f → float 3.0; load from d → double 4.0; promote float 3.0 and double 4.0: result double; implicit cast float 3.0 to double 3.0 → double 3.0; multiply double 3.0 and double 4.0 → double 12.0; call put on HashMap reference with arguments(long 2, double 12.0); load from d → double 4.0; load from s → String "5"; call put on HashMap reference with arguments(double 4.0, String "5"); implicit cast HashMap reference to Map reference → Map reference; store Map reference to map

Map Access

Use the map access operator '[]' as a shortcut for a put method call or get method call made on a Map type value.

Errors

If a value other than a Map type value is accessed.

Grammar

map_access: '[' expression ']'

Examples

Map access with the Map type.
```
Map map = new HashMap();               (1)
map['value2'] = 2;                     (2)
map['value5'] = 5;                     (3)
int x = map['value2'] + map['value5']; (4)
String y = 'value5';                   (5)
int z = x[z];                          (6)
```
1. declare Map map; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference → Map reference; store Map reference to map
2. load from map → Map reference; call put on Map reference with arguments(String 'value2', int 2)
3. load from map → Map reference; call put on Map reference with arguments(String 'value5', int 5)
4. declare int x; load from map → Map reference; call get on Map reference with arguments(String 'value2') → def; implicit cast def to int 2 → int 2; load from map → Map reference; call get on Map reference with arguments(String 'value5') → def; implicit cast def to int 5 → int 5; add int 2 and int 5 → int 7; store int 7 to x
5. declare String y; store String 'value5' to y
6. declare int z; load from map → Map reference; load from y → String 'value5'; call get on Map reference with arguments(String 'value5') → def; implicit cast def to int 5 → int 5; store int 5 to z
Map access with the def type.
```
def d = new HashMap();             (1)
d['value2'] = 2;                   (2)
d['value5'] = 5;                   (3)
int x = d['value2'] + d['value5']; (4)
String y = 'value5';               (5)
def z = d[y];                      (6)
```
1. declare def d; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to def → def; store def to d
2. load from d → def; implicit cast def to HashMap reference → HashMap reference; call put on HashMap reference with arguments(String 'value2', int 2)
3. load from d → def; implicit cast def to HashMap reference → HashMap reference; call put on HashMap reference with arguments(String 'value5', int 5)
4. declare int x; load from d → def; implicit cast def to HashMap reference → HashMap reference; call get on HashMap reference with arguments(String 'value2') → def; implicit cast def to int 2 → int 2; load from d → def; call get on HashMap reference with arguments(String 'value5') → def; implicit cast def to int 5 → int 5; add int 2 and int 5 → int 7; store int 7 to x
5. declare String y; store String 'value5' to y
6. declare def z; load from d → def; load from y → String 'value5'; call get on HashMap reference with arguments(String 'value5') → def; store def to z

New Instance

Use the new instance operator 'new ()' to allocate a reference type instance to the heap and call a specified constructor. Implicit boxing/unboxing is evaluated as necessary per argument during the constructor call.

An overloaded constructor is one that shares the same name with two or more constructors. A constructor is overloaded based on arity where the same reference type name is re-used for multiple constructors as long as the number of parameters differs.

Errors

If the reference type name doesn’t exist for instance allocation.
If the number of arguments passed in is different from the number of specified parameters.
If the arguments cannot be implicitly cast or implicitly boxed/unboxed to the correct type values for the parameters.

Grammar

new_instance: 'new' TYPE '(' (expression (',' expression)*)? ')';

Examples

Allocation of new instances with different types.

Map m = new HashMap();   (1)
def d = new ArrayList(); (2)
def e = new HashMap(m);  (3)

declare Map m; allocate HashMap instance → HashMap reference; implicit cast HashMap reference to Map reference → Map reference; store Map reference to m;
declare def d; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to def → def; store def to d;
declare def e; load from m → Map reference; allocate HashMap instance with arguments (Map reference) → HashMap reference; implicit cast HashMap reference to def → def; store def to e;

String Concatenation

Use the string concatenation operator '+' to concatenate two values together where at least one of the values is a String type.

Grammar

concatenate: expression '+' expression;

Examples

String concatenation with different primitive types.
```
String x = "con";     (1)
String y = x + "cat"; (2)
String z = 4 + 5 + x; (3)
```
1. declare String x; store String "con" to x;
2. declare String y; load from x → String "con"; concat String "con" and String "cat" → String "concat"; store String "concat" to y
3. declare String z; add int 4 and int 5 → int 9; concat int 9 and String "9concat"; store String "9concat" to z; (note the addition is done prior to the concatenation due to precedence and associativity of the specific operations)
String concatenation with the def type.
```
def d = 2;             (1)
d = "con" + d + "cat"; (2)
```
1. declare def; implicit cast int 2 to def → def; store def in d;
2. concat String "con" and int 9 → String "con9"; concat String "con9" and String "con" → String "con9cat" implicit cast String "con9cat" to def → def; store def to d; (note the switch in type of d from int to String)

Elvis

An elvis consists of two expressions. The first expression is evaluated with to check for a null value. If the first expression evaluates to null then the second expression is evaluated and its value used. If the first expression evaluates to non-null then the resultant value of the first expression is used. Use the elvis operator '?:' as a shortcut for the conditional operator.

Errors

If the first expression or second expression cannot produce a null value.

Grammar

elvis: expression '?:' expression;

Examples

Elvis with different reference types.
```
List x = new ArrayList();      (1)
List y = x ?: new ArrayList(); (2)
y = null;                      (3)
List z = y ?: new ArrayList(); (4)
```
1. declare List x; allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to x;
2. declare List y; load x → List reference; List reference equals null → false; evaluate 1st expression: List reference → List reference; store List reference to y
3. store null to y;
4. declare List z; load y → List reference; List reference equals null → true; evaluate 2nd expression: allocate ArrayList instance → ArrayList reference; implicit cast ArrayList reference to List reference → List reference; store List reference to z;

Operators: Array

Array Initialization

Use the array initialization operator '[] {}' to allocate a single-dimensional array type instance to the heap with a set of pre-defined elements. Each value used to initialize an element in the array type instance is cast to the specified element type value upon insertion. The order of specified values is maintained.

Errors

If a value is not castable to the specified type value.

Grammar

array_initialization: 'new' TYPE '[' ']' '{' expression_list '}'
                    | 'new' TYPE '[' ']' '{' '}';
expression_list: expression (',' expression);

Example:

Array initialization with static values.
```
int[] x = new int[] {1, 2, 3}; (1)
```
1. declare int[] x; allocate 1-d int array instance with length [3] → 1-d int array reference; store int 1 to index [0] of 1-d int array reference; store int 2 to index [1] of 1-d int array reference; store int 3 to index [2] of 1-d int array reference; store 1-d int array reference to x;
Array initialization with non-static values.
```
int i = 1;      (1)
long l = 2L;    (2)
float f = 3.0F; (3)
double d = 4.0; (4)
String s = "5"; (5)
def array = new def[] {i, l, f*d, s}; (6)
```
1. declare int i; store int 1 to i
2. declare long l; store long 2 to l
3. declare float f; store float 3.0 to f
4. declare double d; store double 4.0 to d
5. declare String s; store String "5" to s
6. declare def array; allocate 1-d def array instance with length [4] → 1-d def array reference; load from i → int 1; implicit cast int 1 to def → def; store def to index [0] of 1-d def array reference; load from l → long 2; implicit cast long 2 to def → def; store def to index [1] of 1-d def array reference; load from f → float 3.0; load from d → double 4.0; promote float 3.0 and double 4.0: result double; implicit cast float 3.0 to double 3.0 → double 3.0; multiply double 3.0 and double 4.0 → double 12.0; implicit cast double 12.0 to def → def; store def to index [2] of 1-d def array reference; load from s → String "5"; implicit cast String "5" to def → def; store def to index [3] of 1-d def array reference; implicit cast 1-d int array reference to def → def; store def to array

Array Access

Use the array access operator '[]' to store a value to or load a value from an array type value. Each element of an array type value is accessed with an int type value to specify the index to store/load. The range of elements within an array that are accessible is [0, size) where size is the number of elements specified at the time of allocation. Use a negative int type value as an index to access an element in reverse from the end of an array type value within a range of [-size, -1].

Errors

If a value other than an int type value or a value that is castable to an int type value is provided as an index.
If an element is accessed outside of the valid ranges.

Grammar

brace_access: '[' expression ']'

Examples

Array access with a single-dimensional array.
```
int[] x = new int[2]; (1)
x[0] = 2;             (2)
x[1] = 5;             (3)
int y = x[0] + x[1];  (4)
int z = 1;            (5)
int i = x[z];         (6)
```
1. declare int[] x; allocate 1-d int array instance with length [2] → 1-d int array reference; store 1-d int array reference to x
2. load from x → 1-d int array reference; store int 2 to index [0] of 1-d int array reference;
3. load from x → 1-d int array reference; store int 5 to index [1] of 1-d int array reference;
4. declare int y; load from x → 1-d int array reference; load from index [0] of 1-d int array reference → int 2; load from x → 1-d int array reference; load from index [1] of 1-d int array reference → int 5; add int 2 and int 5 → int 7; store int 7 to y
5. declare int z; store int 1 to z;
6. declare int i; load from x → 1-d int array reference; load from z → int 1; load from index [1] of 1-d int array reference → int 5; store int 5 to i;
Array access with the def type.
```
def d = new int[2];  (1)
d[0] = 2;            (2)
d[1] = 5;            (3)
def x = d[0] + d[1]; (4)
def y = 1;           (5)
def z = d[y];        (6)
```
1. declare def d; allocate 1-d int array instance with length [2] → 1-d int array reference; implicit cast 1-d int array reference to def → def; store def to d
2. load from d → def implicit cast def to 1-d int array reference → 1-d int array reference; store int 2 to index [0] of 1-d int array reference;
3. load from d → def implicit cast def to 1-d int array reference → 1-d int array reference; store int 5 to index [1] of 1-d int array reference;
4. declare int x; load from d → def implicit cast def to 1-d int array reference → 1-d int array reference; load from index [0] of 1-d int array reference → int 2; load from d → def implicit cast def to 1-d int array reference → 1-d int array reference; load from index [1] of 1-d int array reference → int 5; add int 2 and int 5 → int 7; implicit cast int 7 to def → def; store def to x
5. declare def y; implicit cast int 1 to def → def; store def to y;
6. declare int i; load from d → def implicit cast def to 1-d int array reference → 1-d int array reference; load from y → def; implicit cast def to int 1 → int 1; load from index [1] of 1-d int array reference → int 5; implicit cast int 5 to def; store def to z;
Array access with a multi-dimensional array.
```
int[][][] ia3 = new int[2][3][4]; (1)
ia3[1][2][3] = 99;                (2)
int i = ia3[1][2][3];             (3)
```
1. declare int[][][] ia; allocate 3-d int array instance with length [2, 3, 4] → 3-d int array reference; store 3-d int array reference to ia3
2. load from ia3 → 3-d int array reference; store int 99 to index [1, 2, 3] of 3-d int array reference
3. declare int i; load from ia3 → 3-d int array reference; load from index [1, 2, 3] of 3-d int array reference → int 99; store int 99 to i

Array Length

An array type value contains a read-only member field named length. The length field stores the size of the array as an int type value where size is the number of elements specified at the time of allocation. Use the field access operator to load the field length from an array type value.

Examples

Access the length field.
```
int[] x = new int[10]; (1)
int l = x.length;      (2)
```
1. declare int[] x; allocate 1-d int array instance with length [2] → 1-d int array reference; store 1-d int array reference to x
2. declare int l; load x → 1-d int array reference; load length from 1-d int array reference → int 10; store int 10 to l;

New Array

Use the new array operator 'new []' to allocate an array type instance to the heap. Specify the element type following the new token. Specify each dimension with the [ and ] tokens following the element type name. The size of each dimension is specified by an int type value in between each set of [ and ] tokens.

Errors

If a value other than an int type value or a value that is castable to an int type value is specified for a dimension’s size.

Grammar

new_array: 'new' TYPE ('[' expression ']')+;

Examples

Allocation of different array types.
```
int[] x = new int[5];    (1)
x = new int[10];         (2)
int y = 2;               (3)
def z = new def[y][y*2]; (4)
```
1. declare int[] x; allocate 1-d int array instance with length [5] → 1-d int array reference; store 1-d int array reference to x
2. allocate 1-d int array instance with length [10] → 1-d int array reference; store 1-d int array reference to x
3. declare int y; store int 2 to y;
4. declare def z; load from y → int 2 @0; load from y → int 2 @1; multiply int 2 @1 by int 2 @2 → int 4; allocate 2-d int array instance with length [2, 4] → 2-d int array reference; implicit cast 2-d int array reference to def → def; store def to z;

Statements

Painless supports all of Java’s control flow statements except the switch statement.

Conditional statements

If / Else

if (doc[item].size() == 0) {
  // do something if "item" is missing
} else {
  // do something else
}

Loop statements

For

Painless also supports the for in syntax from Groovy:

for (def item : list) {
  ...
}

Scripts

Scripts are composed of one-to-many statements and are run in a sandbox that determines what local variables are immediately available along with what APIs are whitelisted for use.

Functions

A function is a named piece of code comprised of one-to-many statements to perform a specific task. A function is called multiple times in a single script to repeat its specific task. A parameter is a named type value available as a variable within the statement(s) of a function. A function specifies zero-to-many parameters, and when a function is called a value is specified per parameter. An argument is a value passed into a function at the point of call. A function specifies a return type value, though if the type is void then no value is returned. Any non-void type return value is available for use within an operation or is discarded otherwise.

You can declare functions at the beginning of a Painless script, for example:

boolean isNegative(def x) { x < 0 }
...
if (isNegative(someVar)) {
  ...
}

Lambdas

Lambda expressions and method references work the same as in Java.

list.removeIf(item -> item == 2);
list.removeIf((int item) -> item == 2);
list.removeIf((int item) -> { item == 2 });
list.sort((x, y) -> x - y);
list.sort(Integer::compare);

You can make method references to functions within the script with this, for example list.sort(this::mycompare).

Regexes

Regular expression constants are directly supported. To ensure fast performance, this is the only mechanism for creating patterns. Regular expressions are always constants and compiled efficiently a single time.

Pattern p = /[aeiou]/

Pattern flags

You can define flags on patterns in Painless by adding characters after the trailing / like /foo/i or /foo \w #comment/iUx. Painless exposes all of the flags from Java’s Pattern class using these characters:

Character Java Constant Example

Character	Java Constant	Example
`c`	CANON_EQ	`'å' ==~ /å/c` (open in hex editor to see)
`i`	CASE_INSENSITIVE	`'A' ==~ /a/i`
`l`	LITERAL	`'[a]' ==~ /[a]/l`
`m`	MULTILINE	`'a\nb\nc' =~ /^b$/m`
`s`	DOTALL (aka single line)	`'a\nb\nc' =~ /.b./s`
`U`	UNICODE_CHARACTER_CLASS	`'Ɛ' ==~ /\\w/U`
`u`	UNICODE_CASE	`'Ɛ' ==~ /ɛ/iu`
`x`	COMMENTS (aka extended)	`'a' ==~ /a #comment/x`

c

CANON_EQ

'å' ==~ /å/c (open in hex editor to see)

i

CASE_INSENSITIVE

'A' ==~ /a/i

l

LITERAL

'[a]' ==~ /[a]/l

m

MULTILINE

'a\nb\nc' =~ /^b$/m

s

DOTALL (aka single line)

'a\nb\nc' =~ /.b./s

U

UNICODE_CHARACTER_CLASS

'Ɛ' ==~ /\\w/U

u

UNICODE_CASE

'Ɛ' ==~ /ɛ/iu

x

COMMENTS (aka extended)

'a' ==~ /a #comment/x

"Fossies" - the Fresh Open Source Software Archive

Member "elasticsearch-6.8.23/docs/painless/painless-lang-spec.asciidoc" (29 Dec 2021, 1768 Bytes) of package /linux/www/elasticsearch-6.8.23-src.tar.gz:

Painless Language Specification

Comments

Keywords

Literals

Integers

Floats

Strings

Characters

Identifiers

Variables

Declaration

Assignment

Types

Primitive Types

Reference Types

Dynamic Types

String Type

void Type

Array Type

Casting

Numeric Type Casting

Reference Type Casting

Dynamic Type Casting

String to Character Casting

Boxing and Unboxing

Promotion

Allowed Casts

Operators

Operators: General

Precedence

Function Call

Cast

Conditional

Assignment

Compound Assignment

Operators: Numeric

Post Increment

Post Decrement

Pre Increment

Pre Decrement

Unary Positive

Unary Negative

Bitwise Not

Multiplication

Division

Remainder

Addition

Subtraction

Left Shift

Right Shift

Unsigned Right Shift

Bitwise And

Bitwise Xor

Bitwise Or

Operators: Boolean

Boolean Not

Greater Than

Greater Than Or Equal

Less Than

Less Than Or Equal

Instanceof

Equality Equals

Equality Not Equals

Identity Equals

Identity Not Equals

Boolean Xor

Boolean And

Boolean Or

Operators: Reference

Method Call

Field Access

Null Safe

List Initialization

List Access

Map Initialization

Map Access

New Instance

String Concatenation