Operators

Below is the list of operators ordered by precedence in descending order:

Factorial

Factorial ('!') is a special post-operator that is applicable to a value or expression that evaluates to an integer value. The resulting expression is binary, and the number of exclamation marks determines the type of factorial (standard, double, triple etc.).

  • !: standard factorial
  • !!: double factorial
  • !!!: triple factorial
  • !....!: some multifactorial

Examples:

(1+2)!
20!!!

Percent

Percent is a post-operator that alters the way the operand is interpreted. A percent value is marked with a % character placed after a numeric value or expression.

Examples:

5% + 2%
100 * 5%
200 + 10%
200 - 5%
50 / 5%
(1+2)%

When you perform operations on percent values, the result of the operation is also a percent. When an arithmetic operation is performed on a number by applying a percent value, the result is a number.

Exponential

Exponential operators perform exponentiation.

  • ** : Exponentiation
  • ^ : Exponentiation (Only in Programmer's layout)
  • ↑ (U+2291): Exponentiation

Examples:

2 ** 2
2 ^ 3
3 ↑ 4

Unary

Unary operators operate on a single operand.

  • - : Negation
  • not : Logical NOT
  • bit_not : Bitwise NOT
  • ! : Logical NOT (Only in Programmer's layout)
  • ~ : Bitwise NOT (Only in Programmer's layout)
  • ¬ (U+00AC) : Logical NOT
  • √ (U+221A) : Square root
  • ∛ (U+221B) : Cube root
  • ∜ (U+221C) : Fourth root

Examples:

not true
!(1 != 2)
√4
∜(4*4)

Multiplicative

Multiplicative operators perform multiplication, division, and modulus operations.

  • * : Multiplication

  • / : Division

  • \\ : Integer Division (Basic-like - floating-point operands are truncated first)

  • div : Integer Division (Basic-like - floating-point operands are truncated first)

  • mod : Modulus

  • *= : Multiplication with assignment of the result to the left operand

  • /= : Division with assignment of the result to the left operand

  • × (U+00D7) : Multiplication

  • ∙ (U+2219) : Multiplication

  • ∶ (U+2236) : Division

  • ÷ (U+00F7) : Division

  • ×= : Multiplication with assignment of the result to the left operand

  • ∙= : Multiplication with assignment of the result to the left operand

  • ÷= : Division with assignment of the result to the left operand

Examples:

1 * 2 mod 3

It is possible to perform the following additional operations:

  • multiply a time period value by a number and obtain a time period as a result;
  • divide a time period value by a number and obtain a time period as a result.

When Unicode characters are enabled, they can also be used for multiplication with assignment and division with assignment.

The non-AOT version of NCalc can perform multiplication, division, and modulus operations on any types which have these operations defined (overloaded). This includes non-numeric types. The AOT version can handle only numbers (including BigInteger and BigDecimal) and multiplication and division of TimeSpan values by numbers.

Additive

Additive operators perform addition and subtraction.

  • + : Addition
  • - : Subtraction
  • += : Addition with assignment of the result to the left operand
  • -= : Subtraction with assignment of the result to the left operand

Examples:

1 + 2 - 3

It is possible to perform the following additional operations with dates and time periods:

  • add a time period value (TimeSpan) to a date (DateTime) or another time period (TimeSpan) value;
  • add ticks (100ns per tick) to a date or time period value;
  • subtract a time period value from a date or another time period value;
  • subtract a date value from another date value;
  • subtract ticks (100ns per tick) from a date or time period value.

Relational

Relational operators compare two values and return a boolean result.

Equality and Inequality Operators

These operators compare two values to check equality or inequality.

  • == : Equal to
  • = : Equal to (unless the option to use = for assignment is set)
  • !=, <>, ≠ : Not equal to

Examples:

42 == 42            // true
"hello" == "world"  // false
10 != 5             // true
"apple" != "apple"  // false

Comparison Operators

These operators compare two values to determine their relative order.

  • < : Less than
  • <= : Less than or equal to
  • ≤ (U+2264) : Less than or equal to
  • > : Greater than
  • >= : Greater than or equal to
  • ≥ (U+2265) : Greater than or equal to

Examples:

3 < 5          // true
10 <= 10       // true
7 > 3          // true
8 >= 12        // false

Values that are not compatible (e.g., a string and a number) are considered to be not equal. Note that character values and numbers are compatible; a single character specified in single quotes (e.g. 'A') will be equal to its Unicode code (e.g. 65 for 'A').

IN and NOT IN

The IN and NOT IN operators check whether a value is present or absent within a specified list or string.

  • IN : Returns true if the left operand is found in the right operand (which can be a list or a string).
  • ∈ (U+2208) : Returns true if the left operand is found in the right operand (which can be a list or a string).
  • NOT IN : Returns true if the left operand is not found in the right operand.
  • ∉ (U+2209) : Returns true if the left operand is not found in the right operand.

The right operand must be either a string or a list.

Examples:

'Insert' IN ('Insert', 'Update')          // True
42 NOT IN (1, 2, 3)                       // True
'Sergio' IN 'Sergio is at Argentina'      // True
'Mozart' NOT IN ('Chopin', 'Beethoven')   // True
945 IN (202, 303, 945)                    // True
945 ∈ (202, 303, 945)                     // True

LIKE and NOT LIKE

The LIKE and NOT LIKE operators compare a string against a pattern.

  • LIKE : Checks if the string matches the specified pattern.
  • NOT LIKE : Checks if the string does not match the specified pattern.

The patterns may include:

  • % to match any sequence of characters.
  • _ to match any single character.

Examples:

'HelloWorld' LIKE 'Hello%'     // True
'Test123' NOT LIKE 'Test__'    // False
'2024-08-28' LIKE '2024-08-__' // True
'abc' LIKE 'a%'                // True

Bitwise

Bitwise operators perform bitwise operations on integers. The and operator has the highest priority, followed by xor and then by or.

  • << : Left shift
  • >> : Right shift
  • BIT_AND : Bitwise AND
  • BIT_XOR : Bitwise XOR
  • BIT_OR : Bitwise OR
  • &= : Bitwise AND with assignment of the result to the left operand
  • ^= : Bitwise XOR with assignment of the result to the left operand
  • |= : Bitwise OR with assignment of the result to the left operand

Examples:

2 >> 3

The following operator symbols may be used in Programmer's layout:

  • & : Bitwise AND
  • ^ : Bitwise XOR
  • | : Bitwise OR

Logical

Logical operators perform logical comparisons between expressions. By default, binary logic is used, where null or a non-boolean value is not accepted as an operand. When the option to use Ternary Logic is set in the application settings, logic operations are performed in Kleene’s Strong Three-Valued Logic, where null and non-boolean values are treated as Unknown, and null is the result of logical operation yields Unknown.

The and operator has the highest priority, followed by xor and then by or.

  • or, || : Logical OR
  • ∨ (U+2228) : Logical OR
  • and, && : Logical AND
  • ∧ (U+2229) : Logical AND
  • xor : Logical XOR
  • ⊕ (U+2295) : Logical XOR
  • ⊻ (U+22BB) : Logical XOR

Examples:

true or false and true    // Evaluates to true
(1 == 1) || false        // Evaluates to true

Note: The and operator has higher priority than the or or xor operator. Hence, in the example above, false and true is evaluated first.

Ternary

The ternary operator works as a short form of an "if then else" statement in regular programming languages and takes the form of "x ? y : z" where x is the condition, y and z are values or expressions that evaluate to values. if x is true, the value of y is returned, otherwise the value of z is returned.

Examples:

x > 0 ? x : 0 // Returns the larger of x and 0.