Operators [painless-operators]

Operators are the fundamental building blocks for data manipulation in Painless scripts. They enable calculations, comparisons, logical operations, and data access across all {{es}} scripting contexts.

An operator performs a specific action to evaluate values in a script. An expression combines one or more operators to produce a result. Precedence determines evaluation order when multiple operators are present, while associativity controls evaluation direction for operators with equal precedence.

Painless operators use Java-like syntax with {{es}} specific enhancements such as null-safe navigation and specialized data structure access.

Operator categories

Painless organizes operators into five functional categories based on their purpose.

graph TB
    A["Painless Operators"]

    B["General"]
    C["Numeric"]
    D["Boolean"]
    E["Reference"]
    F["Array"]

    B1["Control expression flow and
value assignment"]
    C1["Mathematical operations and
bit manipulation"]
    D1["Boolean logic and
conditional evaluation"]
    E1["Object interaction and
safe data access"]
    F1["Array manipulation and
element access"]

    B2["Precedence ( )
Function Call ( )
Cast ( )
Conditional ? :
Elvis ?:
Assignment =
Compound Assignment $="]
    C2["Post/Pre Increment ++
Post/Pre Decrement --
Unary +/-
Bitwise Not ~
Multiplication *
Division /
Remainder %
Addition +
Subtraction -
Shift <<, >>, >>>
Bitwise And &
Bitwise Xor ^
Bitwise Or |"]
    D2["Boolean Not !
Comparison >, >=, <, <=
Instanceof instanceof
Equality ==, !=
Identity ===, !==
Boolean Xor ^
Boolean And &&
Boolean Or ||"]
    E2["Method Call . ( )
Field Access .
Null Safe ?.
New Instance new ( )
String Concatenation +
List/Map Init [ ], [ : ]
List/Map Access [ ]"]
    F2["Array Init [ ] { }
Array Access [ ]
Array Length .length
New Array new [ ]"]

    A --> B & C & D & E & F
    B --> B1
    C --> C1
    D --> D1
    E --> E1
    F --> F1
    B1 --> B2
    C1 --> C2
    D1 --> D2
    E1 --> E2
    F1 --> F2
    
    classDef rootNode fill:#0B64DD,stroke:#101C3F,stroke-width:2px,color:#fff
    classDef categoryBox fill:#e1f5fe,stroke:#01579b,stroke-width:2px,color:#343741
    classDef descBox fill:#48EFCF,stroke:#343741,stroke-width:2px,color:#343741
    classDef exampleBox fill:#f5f7fa,stroke:#343741,stroke-width:2px,color:#343741

    class A rootNode
    class B,C,D,E,F categoryBox
    class B1,C1,D1,E1,F1 descBox
    class B2,C2,D2,E2,F2 exampleBox

General operators

Control the fundamental flow and structure of expressions in Painless scripts. These operators manage how expressions are evaluated, values are assigned, and conditional logic is run.

• Precedence (): Controls evaluation order by overriding default precedence rules
• Function call (): Executes user-defined functions with arguments
• Cast () : Forces explicit type conversion between compatible types
• Conditional ? : : Provides inline if-else logic for expressions
• Elvis ?: : Returns first non-null value for null coalescing
• Assignment = : Stores values in variables or fields
• Compound assignment $= : Combines binary operations with assignment (+=, -=, and so on)

Numeric operators

Perform mathematical calculations and bit-level manipulations on numeric values. These operators handle arithmetic, bitwise operations, and value modifications essential for numerical computations.

• Increment/Decrement (++. --) : Increases or decreases values by one (pre/post variants)
• Unary (+, -) : preserves or negates numeric values
• Bitwise not ~ : inverts all bits in integer values
• Multiplication/Division/Remainder * / % : Basic arithmetic operations
• Addition/Subtraction + - : Basic arithmetic operations
• Shift (<<, >>, >>>) : Shifts bits left or right within integer values
• Bitwise and & : Performs AND operations on corresponding bits
• Bitwise xor ^ : Performs XOR operations on corresponding bits
• Bitwise or |: Performs OR operations on corresponding bits

Boolean operators

Handle logical evaluation, comparisons, and conditional expressions. These operators are fundamental for creating filters, conditional logic, and boolean expressions in scripts

• Boolean not !:Inverts boolean values (true becomes false)
• Comparison > >= < <= : Compares numeric values for ordering
• Instanceof instanceof: Checks if an object is an instance of a specific type
• Equality == != : Compares values for equality (calls equals() method)
• Identity === !== : Compares object references for same instance
• Boolean xor ^: Returns true if exactly one operand is true
• Boolean and &&: Returns true only if both operands are true
• Boolean or ||: Returns true if at least one operand is true

Reference operators

Enable interaction with objects, method calls, and data structure manipulation. These operators are essential for working with documents, collections, and complex data types in {{es}} contexts.

• Method call . (): Invokes methods on objects with optional arguments
• Field access .: Accesses object properties and member fields
• Null safe ?.: Safely accesses fields/methods without null pointer exceptions
• List/Map initialization [] [:]: Creates new List or Map collections with initial values
• List/Map access []: Retrieves or sets elements in collections by key/index
• New instance new (): Creates new object instances with constructor arguments
• String concatenation + : Joins strings and converts other types to strings

Array operators

Provide specialized functionality for array creation, element access, and array property retrieval. These operators are essential when working with multi-value fields and array data structures.

• Array initialization [] {}`: Creates arrays with predefined values
• Array access []: Retrieves or sets array elements by index position
• Array length .: Returns the number of elements in an array
• New array new []: Creates arrays with specified dimensions and sizes

Complete operator reference