What does the xor function do in MATLAB / RunMat?

xor(A, B) returns the element-wise logical exclusive OR of its inputs. The result is true exactly when one, and only one, operand evaluates to non-zero (with NaN counting as non-zero). Outputs are logical scalars when the broadcasted shape has a single element, or logical arrays otherwise.

How does the xor function behave in MATLAB / RunMat?

• Accepts logical, numeric, complex, and character arrays; character code points of zero evaluate to false.
• Supports MATLAB-style implicit expansion so scalars and singleton dimensions broadcast automatically.
• Propagates empty dimensions: if a broadcasted axis has length 0, the output is an empty logical array with the same shape.
• Treats NaN values as true, matching MATLAB's element-wise logical semantics.
• Keeps gpuArray inputs on device when the active provider exposes the logical_xor hook; otherwise the runtime gathers to host transparently.

Examples of using the xor function in MATLAB / RunMat

Checking if exactly one condition is true

result = xor(true, false)

Expected output:

result =
  logical
     1

Performing XOR on numeric arrays element-wise

A = [1 0 2 0];
B = [3 4 0 0];
C = xor(A, B)

Expected output:

C =
  1×4 logical array
     0     1     1     0

Applying XOR with implicit expansion against a scalar

mask = [1; 0; 3; 0];
flag = xor(mask, 1)

Expected output:

flag =
  4×1 logical array
     0
     1
     0
     1

Comparing character arrays with XOR

lhs = ['R' 'u' 0];
rhs = ['R' 0 'n'];
diff = xor(lhs, rhs)

Expected output:

diff =
  1×3 logical array
     0     1     1

Running xor directly on gpuArray inputs

G1 = gpuArray([0 2 0 4]);
G2 = gpuArray([1 0 3 4]);
deviceResult = xor(G1, G2);
hostResult = gather(deviceResult)

Expected output:

deviceResult =
  1×4 gpuArray logical array
     1     1     1     0
hostResult =
  1×4 logical array
     1     1     1     0

xor Function GPU Execution Behaviour

When both operands reside on the GPU and the active provider implements the logical_xor hook, RunMat lowers the call into a device kernel that writes 0 or 1 for each element. The fusion planner treats xor as an element-wise operation, so fused expressions (for example, xor(A > 0, B)) stay on device without intermediate gathers. The native auto-offload planner also recognizes the builtin's elementwise tag, promoting mixed CPU/GPU operands to the active device when it is profitable. If the provider lacks the hook, the runtime gathers the inputs to host memory automatically and executes the CPU implementation instead of failing.

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray explicitly. RunMat's native auto-offload logic moves data to the GPU when a fused expression benefits from device execution, and results stay resident until you gather them or the planner needs host access. Call gpuArray only when you want to seed residency manually, or when you are porting MATLAB code that already uses explicit device transfers.

FAQ

Does xor return logical values?

Yes. The result is a logical scalar (true/false) when the broadcasted shape contains exactly one element; otherwise the function returns a logical array. On the GPU the kernel writes 0.0/1.0 elements, and the runtime converts them back to logical values when you gather.

How are NaN values handled?

NaN counts as true. For example, xor(NaN, 5) returns false because both operands evaluate to non-zero, whereas xor(NaN, 0) returns true.

Is implicit expansion supported?

Yes. The inputs follow MATLAB-style implicit expansion rules: dimensions of length 1 broadcast across the other input. Fully incompatible shapes raise a size-mismatch error.

Can I use xor with complex numbers?

Yes. Real or complex inputs return true when exactly one operand has a non-zero real or imaginary component. For example, xor(0 + 0i, 0 + 2i) returns true, while xor(1 + 0i, 0 + 2i) returns false.

What happens when only one input is a gpuArray?

RunMat promotes the other input to the GPU before dispatch when the auto-offload planner decides it is profitable. If the provider lacks a device implementation, both operands gather to host automatically and the logical result executes on the CPU.

See Also

and, or, gpuArray, gather