Bitwise OR Assignment

The |= operator is the compound assignment operator for the bitwise inclusive OR (or logical inclusive OR) operation. It evaluates the inclusive OR of its left and right operands, assigns the resulting value to the left operand, and returns that new value.

The expression:

x |= y;

is semantically equivalent to:

x = (T)(x | y);

where T is the type of x, with the strict exception that the left operand x is evaluated only once. The explicit cast (T) is a fundamental part of the C# specification because bitwise operations on integral types smaller than int (such as byte or short) implicitly promote their operands to int and return an int.

Operand Compatibility and Behavior

The |= operator behaves differently depending on the data types of the operands:

1. Integral Numeric Types (int, long, byte, etc.) and char The operator performs a bitwise inclusive OR operation on the binary representation of the operands. For each bit position, the resulting bit is 1 if the corresponding bit in either or both operands is 1. It is 0 only if both corresponding bits are 0.

byte a = 0b_1010_0000; // Decimal: 160
byte b = 0b_0000_1100; // Decimal: 12

a |= b; 

// Evaluation:
//   1010 0000 (a)
// | 0000 1100 (b)
// --------
//   1010 1100 (Result implicitly cast back to byte and assigned to a: Decimal 172)

2. Boolean Types (bool) When applied to bool operands, |= performs a logical inclusive OR operation. The left operand evaluates to true if either the left or the right operand evaluates to true.

Unlike the conditional OR operator (||), the | operation does not short-circuit. Both the left and right operands are fully evaluated before the assignment occurs.

bool x = false;
bool y = true;

x |= y; // x becomes true

3. Nullable Value Types (T?) For nullable value types, the |= operator utilizes lifted operators. For numeric and enum types, if either operand is null, the result of the | operation is null.

However, for the nullable boolean type (bool?), the | operator implements three-valued logic:

• true | null evaluates to true.
• false | null evaluates to null.
• null | null evaluates to null.

bool? flag1 = false;
flag1 |= null; // flag1 becomes null

bool? flag2 = true;
flag2 |= null; // flag2 remains true

4. Enumeration Types (enum) For enum types, the |= operator performs the bitwise OR operation on the underlying integral type of the enumeration.

[Flags]
enum Status { None = 0, Active = 1, Pending = 2 }

Status current = Status.Active;
current |= Status.Pending; 
// current is now Status.Active | Status.Pending (Underlying value: 3)

Evaluation Order

In the expression x |= y, the evaluation sequence is strictly defined to handle complex left-hand side expressions (such as properties or indexers):

1. The left operand x is evaluated to determine the target variable, property access, or indexer access.
2. The right operand y is evaluated.
3. The value of x is fetched. If x is a property or indexer, its get accessor is invoked.
4. The | operation is performed on the values.
5. The result is assigned back to x. If x is a property or indexer, its set accessor is invoked.

Operator Overloading

C# explicitly forbids overloading compound assignment operators directly. A user-defined type (a class or struct) cannot overload the |= operator.

However, if a user-defined type overloads the binary | operator, the |= operator is automatically and implicitly overloaded.

public struct BitMask
{
    public int Value { get; }
    public BitMask(int value) => Value = value;

    // Overloading the binary | operator
    public static BitMask operator |(BitMask left, BitMask right)
    {
        return new BitMask(left.Value | right.Value);
    }
}

// The |= operator is now implicitly supported
BitMask mask1 = new BitMask(1);
BitMask mask2 = new BitMask(2);
mask1 |= mask2; 

Master C# with Deep Grasping Methodology!

Learn More