.NET 10 Generic Math Shift Masking: Catch Overshifts That Now Wrap

.NET 10 generic math shift masking changes the result of some oversized shifts on small integer types. If a helper uses IShiftOperators<T, int, T>, code such as a generic byte << 8 can return 1 on .NET 10 where it returned 0 on .NET 9. That is a narrow behavioral change, but it can matter in bit-field parsing, binary protocols, compact identifiers, and any test fixture that treats an out-of-range count as an implicit zero.

I treat this as a contract problem. The runtime now behaves consistently; the application still has to decide whether an oversized count is valid.

Why .NET 10 generic math shift masking changes results

The official breaking-change note says generic shifts now mask the shift amount as appropriate for all built-in integer types. The affected small types are byte, char, sbyte, short, and ushort, and the affected operators are <<, >>, and >>>.

This is specifically about operators dispatched through generic math. A concrete C# expression involving a byte can be promoted to int; a generic method constrained by IShiftOperators<T, int, T> returns T. That distinction is why a normal happy-path unit test may not reveal the upgrade boundary.

Here is the core of the reproducer:

static T ShiftLeft<T>(T value, int count)
    where T : IShiftOperators<T, int, T> => value << count;

static T UnsignedShiftRight<T>(T value, int count)
    where T : IShiftOperators<T, int, T> => value >>> count;

The generic math guide explains the static interface-member model behind these constraints. The syntax did not change here. The built-in implementations did.

Reproduce the .NET 9 and .NET 10 boundary

The runnable sample multi-targets net9.0 and net10.0, then runs the same cases under both installed runtimes. It checks counts equal to the type width and one greater than the width. It also includes int << 32 as a control because int already masks its shift count.

The relevant output is deliberately small:

.NET 9:  byte-left-8=0, byte-left-9=0
.NET 10: byte-left-8=1, byte-left-9=2

.NET 9:  byte-unsigned-right-8=0
.NET 10: byte-unsigned-right-8=128

both:    int-left-32-control=1

For the .NET 10 byte cases, a count of 8 becomes 0 after masking, and 9 becomes 1. The value is therefore shifted by zero or one position. The .NET 9 result reflected the previous inconsistent small-integer behavior.

The count is not clamped to the largest legal position. It is reduced according to the operand width, so every additional full width repeats the same positions. That makes 8, 16, and 24 equivalent counts for an eight-bit implementation. It also explains why an overshift may produce a nonzero value rather than clearing all bits. Tests should assert the domain rule, not a vague expectation that a “large enough” shift becomes zero.

For an upgrade audit, I search for IShiftOperators, IBinaryInteger, generic <</>> helpers, and methods that accept an unvalidated count. I then prioritize small built-in types. Calls whose count is a compile-time constant below the width are not affected; input-derived counts, sentinels equal to the width, and reusable bit-packers deserve the cross-runtime test. Searching only for byte << misses helpers where T hides the eventual operand type.

The verifier builds both targets, requires the exact output, and fails on any unexpected exit code. It has no package references and needs no credentials, clock, random input, or network call at runtime. The associated sample pull request records the complete validation commands and results.

Make the shift-count policy explicit

Runtime consistency is useful, but silent normalization is not always the right application rule. I prefer to name one of two policies at the boundary.

For a protocol offset or serialized bit index, reject a count outside the value width:

static T ShiftLeftReject<T>(T value, int count, int width)
    where T : IShiftOperators<T, int, T>
{
    ArgumentOutOfRangeException.ThrowIfNegative(count);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);

    if (count >= width)
        throw new ArgumentOutOfRangeException(nameof(count));

    return value << count;
}

For a domain where cyclic counts are intentional, normalize them yourself:

static T ShiftLeftModulo<T>(T value, int count, int width)
    where T : IShiftOperators<T, int, T>
{
    ArgumentOutOfRangeException.ThrowIfNegative(count);
    ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width);
    return value << (count % width);
}

With the matching built-in value width, both versions behave the same on .NET 9 and .NET 10. More importantly, a reviewer can see the policy without knowing a runtime-specific operator rule.

Keep width close to the numeric type rather than accepting an unrelated caller-provided value. In a reusable library, a type-specific helper or a small metadata table is clearer than letting every call site guess. The sample passes the width explicitly so the two policies remain visible, testable, and easy to adapt.

When not to use modulo masking

Do not add % width simply to preserve the new output. If an oversized count signals corrupt input, masking turns an invalid value into a plausible one. Rejection is usually safer for parsers, authorization bitsets, storage formats, and externally supplied offsets.

This sample also does not define semantics for custom numeric types; their operator implementations remain their own contracts. Review rotations, sign extension, negative counts, and cryptographic code separately. A shift verifier can expose a changed result, but it cannot decide whether that result is correct for the domain.

.NET 10 is a stable LTS release, and the current 10.0.11 release notes list the SDK/runtime builds used for this check. If your library targets multiple runtimes, I would keep the cross-target assertion until the oldest affected target leaves support.

Would your code reject an oversized shift count, or is modulo behavior part of its contract?

Happy coding!