[API Proposal]: Add EndiannessAwarePair<TUpper, TLower>

[LEI-Hongfaan]

Background and motivation

Third-party libraries that need endianness-aware layout for a pair of fields must either:

• compile and distribute separate little-endian and big-endian builds, or
• implement complex conditional logic, ref T shims, or manual byte-swapping.

This increases maintenance, package size, and the chance of subtle bugs and performance regressions. A small BCL primitive that encodes endianness-aware semantics would let library authors write one build that behaves correctly and efficiently on all platforms.

API Proposal

namespace System.Runtime.InteropServices {

    [StructLayout(LayoutKind.Sequential)]
    public struct EndiannessAwarePair<TUpper, TLower>
        where TUpper : unmanaged
        where TLower : unmanaged {

#if BIGENDIAN
        public TUpper Upper;
        public TLower Lower;
#else
        public TLower Lower;
        public TUpper Upper;
#endif

        public static EndianAwarePair<TLower, TUpper> FromUpperAndLower(TUpper upper, TUpper lower);
        public static EndianAwarePair<TLower, TUpper> FromLowerAndUpper(TLower lower, TLower upper);
    }
}

API Usage

public readonly struct MyInt128 {
    readonly EndiannessAwarePair<Int64, UInt64> bits;
}

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/interop-contrib
See info in area-owners.md if you want to be subscribed.

[huoyaoyuan]

Third-party libraries that need endianness-aware layout for a pair of fields

How can this be achieved without ifdef in C code? If so, it's natural to require ifdef in managed code.

Moreover, managed code can define different P/Invoke signatures for the same target.

[LEI-Hongfaan]

Third-party libraries that need endianness-aware layout for a pair of fields

How can this be achieved without ifdef in C code? If so, it's natural to require ifdef in managed code.

Moreover, managed code can define different P/Invoke signatures for the same target.

This is similar to the situation with (U)IntPtr, C(U)Long, and NFloat. Providing these types simplifies the work of library authors. It doesn't mean that the relevant functionality cannot be implemented in managed code without these types.

[huoyaoyuan]

As mentioned in #80663, endianness-aware layout isn't defined for arbitrary types. The well know ABIs only define layout for limited known set of types, up to int 128. The BCL is going to support that limited set.

[LEI-Hongfaan]

It can be useful for situations beyond numeric types.

[huoyaoyuan]

It can be useful for situations beyond numeric types.

Please demonstrate the case. Endianness is usually not a concept for non-numeric areas.