DefineOperator

The DefineOperator method allows you to create new operators, giving you the power to define custom syntax for your expressions. This is a cornerstone feature for building Domain-Specific Languages (DSLs) within uCalc.

Operator definitions share many concepts with function definitions (see DefineFunction), but this topic focuses on their unique characteristics.

Operator Anatomy (Prefix, Infix, Postfix)

You can define three kinds of operators:

• Infix (Binary): Sits between two operands (e.g., x + y).
• Prefix (Unary): Comes before a single operand (e.g., -x).
• Postfix (Unary): Comes after a single operand (e.g., x!).

Operands in the definition string must be enclosed in curly braces {}.

using uCalcSoftware;

var uc = new uCalc();

// Infix operator with an alphanumeric name
uc.DefineOperator("{x} Plus {y} = x + y");

// Prefix operator with a symbolic name
uc.DefineOperator("neg {x} = -x");

// Postfix operator with a symbolic name
uc.DefineOperator("{x}% = x / 100");

Data type placement

To specify a data type for a parameter, add As [type] next to the operand within curly braces. You can also have a return type (e.g., {x As Int} + {y As Int} As Int = x + y).

Key Concepts

Operator Names

Unlike functions, an operator name can be either fully alphanumeric (e.g., Plus, times) or consist entirely of non-alphanumeric symbols (e.g., +, ++, &&, @#%). A mix of character types is not allowed.

Reducible Tokens

When the parser encounters a sequence of symbols, it greedily matches the longest defined operator. This is known as using reducible tokens. For example, if you have operators for - (prefix and infix) and -- (postfix), an expression like a---b is parsed as a-- - b because a-- is the first and longest valid match.

The set of characters that can form a symbolic operator is configurable. You can inspect the current definition via uc.ItemOf("_Token_Reducible").Regex().

Precedence

Every operator requires a precedence level. This numeric value determines the order of operations. Higher numbers bind more tightly. For example, * has a higher precedence than +, so 2 + 3 * 4 is 2 + (3 * 4).

Rather than using arbitrary numbers, it's best practice to base new operator precedence on existing ones:

using uCalcSoftware;

var uc = new uCalc();

// Give 'times' the same precedence as the multiplication operator '*'
var prec = uc.ItemOf("*", ItemIs.Infix).Precedence();
uc.DefineOperator("{a} times {b} = a * b", prec);

// Place a new operator between '+' and '*'
var prec_between = (uc.ItemOf("+").Precedence() + uc.ItemOf("*").Precedence()) / 2;
uc.DefineOperator("{a} custom {b} = ...", prec_between);

Associativity

When operators of the same precedence appear together, associativity determines their grouping. The default is LeftToRight.

• LeftToRight: a - b - c is parsed as (a - b) - c.
• RightToLeft: a = b = c is parsed as a = (b = c).

This is controlled by the associativity parameter, using the Associativity enum.

Definition Shortcuts

You can embed the precedence and associativity directly into the definition string, which will override the method parameters:

using uCalcSoftware;

var uc = new uCalc();

// Define 'MyOp' with precedence 123 and default LeftToRight associativity
uc.DefineOperator("123 {a} MyOp {b} = a + b");

// Define 'MyOp' with precedence 123 and RightToLeft (RL) associativity
uc.DefineOperator("123:RL {a} MyOp {b} = a + b");

💡 Comparative Analysis: uCalc vs. Native Operator Overloading

Many compiled languages like C++ and C# support operator overloading, which allows developers to redefine how operators work for their custom classes. However, this has key limitations:

1. Compile-Time Only: You can only overload a fixed set of existing operators (+, -, *, ==, etc.). You cannot invent new ones, and the definitions are baked into the compiled binary.
2. Fixed Precedence: You cannot change the precedence or associativity of operators. + will always have lower precedence than *.

uCalc's DefineOperator is fundamentally different and more powerful:

• Runtime Definition: Operators can be defined, redefined, or removed dynamically at runtime. This allows an application to adapt its syntax based on user input, configuration files, or different modes of operation.
• New Syntax: You can invent entirely new operators (e.g., within, matches, $$) with custom precedence and associativity, enabling the creation of highly readable, domain-specific languages (DSLs) without an external compiler or pre-processor.

This makes uCalc an ideal engine for applications requiring configurable or user-extendable logic.