Operators & Expressions

Flame’s expression and operator syntax is designed to be simple, explicit, predictable, and readable. Whether writing control feedback loops for robotics, manipulating hardware registers on microcontrollers, or building multithreaded desktop automations, Flame provides intuitive operator semantics without hidden implicit casting or ambiguous syntax surprises.

---

1. Keyword Logical Operators (and, or, not)

In mission-critical systems and robotics engineering, deeply nested symbol operators (&&, ||, !) can easily become visually ambiguous or prone to misreading during critical code audits. Flame embraces clean, explicit keyword logical operators (and, or, not) as first-class standard syntax.

Operator	Meaning	Example	Behavior
and / &&	Logical AND	is_online and is_calibrated	Evaluates to true only if both operands are true. Short-circuits if left-hand is false.
or / ||	Logical OR	manual_override or emergency_stop	Evaluates to true if either operand is true. Short-circuits if left-hand is true.
not / !	Logical NOT	not is_faulted	Inverts a boolean condition (true becomes false, and vice-versa).

Clean Boolean Logic Example

let motor_ready: Bool = true
let lidar_online: Bool = true
let safety_trip: Bool = false

if motor_ready and lidar_online and not safety_trip {
    print("[SYSTEM OK] All sub-systems operational. Engaging autonomous routing.")
} else {
    print("[FAULT] Cannot engage system: safety conditions unmet.")
}

Tip

Flame fully supports both keyword forms (and, or, not) and conventional symbolic styles (&&, ||, !). For automation and hardware logic, using keyword forms is recommended for enhanced clarity.

---

2. Arithmetic, Increment & Decrement Operators

Flame provides full precision mathematical operators along with ergonomic unary increment and decrement primitives for loop counters, encoders, and iterative accumulation.

Basic Arithmetic Operators

Operator	Description	Example	Notes
+	Addition	velocity + offset	Also concatenates strings ("Sensor: " + id).
-	Subtraction / Negation	100 - error_margin, -voltage	Unary negation flips sign on numeric values.
*	Multiplication	voltage * current_amps	Computes mathematical product.
/	Division	distance / time_seconds	Standard float or integer division.
%	Modulo (Remainder)	encoder_ticks % 360	Computes remainder of integer division.

---

3. Increment & Decrement Operators (++, --)

When managing real-time hardware timers, sensor scan passes, or step-motor sequences, adjusting mutable variables by 1 is a continuous requirement. Flame natively supports both prefix and postfix increment and decrement operations on mutable variables and struct properties:

Syntax	Name	Behavior
var++	Postfix Increment	Evaluates the expression using current value, then increments var by 1.
++var	Prefix Increment	Increments var by 1 immediately, then evaluates to the new value.
var--	Postfix Decrement	Evaluates the expression using current value, then decrements var by 1.
--var	Prefix Decrement	Decrements var by 1 immediately, then evaluates to the new value.

Usage in Automation Loops

let mut encoder_count: Int = 0
let mut timeout_ticks: Int = 10

// Postfix incrementing encoder pulses
encoder_count++
print($"Current encoder pulse: {encoder_count}") // 1

// Prefix decrementing timer countdown
while --timeout_ticks > 0 {
    if read_sensor_ack() {
        print("Sensor acknowledged before timeout!")
        break
    }
}

---

4. Compound Assignment Operators (+=, -=, etc.)

Compound assignment operators combine a binary operation with variable assignment, streamlining cumulative calculations such as PID control integral sum accumulation or energy consumption trackers.

Operator	Meaning	Expansion Equivalent	Typical Robotics Application
+=	Add and Assign	x = x + y	Accumulating integrated distance or position adjustments.
-=	Subtract and Assign	x = x - y	Decrementing remaining battery buffer or reducing velocity speed trims.
*=	Multiply and Assign	x = x * y	Applying gain amplification coefficients.
/=	Divide and Assign	x = x / y	Scaling down resolution or normalizing sensory readings.
%=	Modulo and Assign	x = x % y	Wrapping angle orientations within 0–360 degrees.

PID Trim Accumulator Example

let mut throttle: Int = 1000
let trim_adjustment: Int = 25

// Increase throttle speed smoothly
throttle += trim_adjustment
print($"Adjusted throttle: {throttle} RPM") // 1025

// Apply braking reduction
throttle -= 150
print($"Decelerated throttle: {throttle} RPM") // 875

---

5. Bitwise Operators (Hardware & Register Manipulation)

For low-level microcontrollers, GPIO interface buses, and industrial communication protocols (SPI/I2C/CAN), precise bitwise manipulation of configuration registers is essential. Flame offers standard 64-bit and 32-bit bitwise primitives:

Operator	Name	Example	Description
&	Bitwise AND	status_reg & 0x01	Evaluates bit intersection; used for checking flag masks.
|	Bitwise OR	control_reg | 0x80	Evaluates bit union; used for setting specific configuration bits.
^	Bitwise XOR	flags ^ TOGGLE_MASK	Evaluates exclusive OR; used for toggling hardware output pins.
<<	Left Shift	1 << pin_number	Shifts bits left; creates power-of-two positional masks.
>>	Right Shift	raw_adc >> 4	Shifts bits right; extracts high-order payload nibbles.

Checking Register Status Flags

const FLAG_OVERTEMP: Int = 1 << 0   // 0x01 (Bit 0)
const FLAG_OVERVOLTAGE: Int = 1 << 1 // 0x02 (Bit 1)

let register_value: Int = 0x03       // Both flags active

let is_overtemp = (register_value & FLAG_OVERTEMP) != 0
let is_overvoltage = (register_value & FLAG_OVERVOLTAGE) != 0

if is_overtemp and is_overvoltage {
    print("[CRITICAL] Dual hardware thermal and electrical fault detected!")
}

Deterministic Pseudo-Random Generation & Bitmasking (LCG Pattern)

A classic real-world systems pattern combining arithmetic operators, grouping parentheses, and bitwise masking is the Linear Congruential Generator (LCG), as featured in Flame’s benchmark pipeline (examples/benchmark/src/main.fm):

// Deterministic pseudo-random generation (31-bit positive LCG)
seed = (seed * 1103515245 + 12345) & 0x7FFFFFFF

Detailed Breakdown & Uses:

1. Recurrence Relation: Computes the next pseudo-random integer using the linear recurrence formula:

   X_{n+1} = (a · X_n + c) mod m

   Here, a = 1103515245 (multiplier) and c = 12345 (increment), which are the standard POSIX / ANSI C constants for fast linear congruential generation.

2. Bitwise AND (&) as Fast Modulo: In binary arithmetic, modulo by a power of two (2^k) is equivalent to bitwise masking with (2^k - 1).

   • Modulo 2^31 corresponds to masking with 2^31 - 1 = 2147483647, written in hexadecimal as 0x7FFFFFFF.
   • The binary representation of 0x7FFFFFFF is 01111111 11111111 11111111 11111111.
   • Masking with & 0x7FFFFFFF clears the most significant sign bit (bit 31), guaranteeing that the result is strictly a positive 31-bit integer while avoiding expensive CPU hardware division instructions (%).

3. Operator Precedence: Multiplicative (*, Level 4) and additive (+, Level 5) operations have higher precedence than bitwise AND (&, Level 9). Enclosing (seed * 1103515245 + 12345) in parentheses ensures that the multiplication and addition complete before applying the bitmask, making the arithmetic explicit and portable.

4. Practical Use Cases in Flame:

   • Deterministic Benchmarking: As used in examples/benchmark/src/main.fm, this pattern creates a predictable, reproducible stream of event records (user_id, category, value) across diverse machines without variability.
   • Zero-Dependency PRNG: Generates pseudo-random numbers without importing external crates or initializing OS entropy pools.
   • Game Development & Procedural Generation: Ideal for seed-based procedural world generation, terrain meshes, and particle effects.
   • Hardware & Sensor Simulation: Simulates noisy sensor signals, encoder jitter, and network telemetry in edge test suites.

---

6. Comparison & Relational Operators

All comparison operations evaluate to a boolean truth value (Bool). Flame allows equality comparisons across primitives, objects, and optional nil values without implicit surprises:

Operator	Description	Example
==	Equality Check	voltage == 3.3, sensor == nil
!=	Inequality Check	state != Mode.Standby, driver != nil
<	Less Than	temperature < 75.0
<=	Less Than or Equal	pressure <= MAX_PSI_THRESHOLD
>	Greater Than	battery_level > 20.0
>=	Greater Than or Equal	speed_rpm >= target_rpm

---

7. Nil Safety Operators Summary

To prevent unexpected crashes in automation, Flame provides dedicated operators for safe navigation and fallback evaluation when dealing with optional types (Type?):

Operator	Name	Syntax	Description
?.	Safe Navigation	bot?.motor?.speed	Accesses field or calls method only if object is non-nil; otherwise yields nil.
?:	Nil Coalescing	val ?: default	Returns val if present; otherwise evaluates and returns default.
!	Non-Null Assertion	val!	Unwraps optional asserting presence; panics safely if value is nil.

Tip

For an in-depth exploration of optional variables, binding patterns (if let), and robotics safety workflows, read the complete guide on Nil Safety & Optionals.

---

8. Complete Operator Precedence & Associativity Table

When expressions contain multiple operators, evaluation order is strictly dictated by the precedence hierarchy below, from highest (evaluated first) down to lowest (evaluated last):

Level	Category	Operators	Associativity
1	Primary / Safe Access / Calls	(), [], ., ?., !(), ident()	Left-to-right
2	Postfix / Unary Increment	var++, var--	Left-to-right
3	Unary / Prefix Increment	++var, --var, not, !, - (unary), &, &mut, mut	Right-to-left
4	Multiplicative	*, /, %	Left-to-right
5	Additive	+, -	Left-to-right
6	Bitwise Shifts	<<, >>	Left-to-right
7	Relational Comparisons	<, <=, >, >=	Left-to-right
8	Equality Comparisons	==, !=	Left-to-right
9	Bitwise AND	&	Left-to-right
10	Bitwise XOR	^	Left-to-right
11	Bitwise OR	|	Left-to-right
12	Nil Coalescing	?:	Right-to-left
13	Logical AND	and, &&	Left-to-right
14	Logical OR	or, ||	Left-to-right
15	Assignment & Compound	=, +=, -=, *=, /=, %=	Right-to-left