lmxopcua/src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT/TwinCATArrayCodec.cs

using System.Buffers.Binary;

namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;

/// <summary>
///     Decodes a PLC array's raw bytes — laid out by <see cref="TwinCATTypeGuard.CheckArray"/> — into the
///     element-typed CLR array an array tag publishes (<c>bool[]</c>, <c>short[]</c>, <c>float[]</c>,
///     <c>string[]</c>, …). Both the poll read and the native notification decode here, so the two paths
///     publish identical values, element type and length by construction.
/// </summary>
/// <remarks>
///     The driver reads arrays as raw bytes rather than through the Beckhoff typed array read, which a live
///     TwinCAT 2.11 target showed failing for most real arrays (2026-10-07, Elma cleaner Z33856): the CLR
///     element type had to match the PLC's exactly (<c>ARRAY OF TIME</c> as <c>uint[]</c> threw), a
///     multi-dimensional array demanded a rank-N CLR array, and a dotted MEMBER array was sliced by the
///     under-reported symbol size (<c>ArgumentOutOfRangeException</c>). Elements are little-endian (every
///     TwinCAT target is x86/x64/ARM-LE); a STRING / WSTRING element is decoded by
///     <see cref="TwinCATStringCodec"/> within its fixed stride, so each ends at its own first NUL.
/// </remarks>
internal static class TwinCATArrayCodec
{
    /// <summary>Decodes <paramref name="layout"/>.ElementCount elements of <paramref name="declared"/>.</summary>
    /// <param name="declared">The tag's declared element type.</param>
    /// <param name="bytes">The PLC bytes from the array's first element (at least <see cref="TwinCATArrayLayout.ByteLength"/>).</param>
    /// <param name="layout">The planned layout.</param>
    /// <param name="utf8">True when the target reports UTF-8 STRING data (else Windows-1252).</param>
    /// <returns>The element-typed CLR array.</returns>
    /// <exception cref="ArgumentException">The buffer is shorter than the layout.</exception>
    public static Array Decode(TwinCATDataType declared, ReadOnlySpan<byte> bytes, TwinCATArrayLayout layout, bool utf8)
    {
        if (layout.ElementCount < 0 || layout.Stride <= 0 || bytes.Length < layout.ByteLength)
            throw new ArgumentException(
                $"An array buffer of {bytes.Length} B cannot hold {layout.ElementCount} × {layout.Stride} B elements",
                nameof(bytes));

        var n = layout.ElementCount;
        var stride = layout.Stride;
        switch (declared)
        {
            case TwinCATDataType.Bool:
            {
                var a = new bool[n];
                for (var i = 0; i < n; i++) a[i] = bytes[i * stride] != 0;
                return a;
            }
            case TwinCATDataType.SInt:
            {
                var a = new sbyte[n];
                for (var i = 0; i < n; i++) a[i] = unchecked((sbyte)bytes[i * stride]);
                return a;
            }
            case TwinCATDataType.USInt:
            {
                var a = new byte[n];
                for (var i = 0; i < n; i++) a[i] = bytes[i * stride];
                return a;
            }
            case TwinCATDataType.Int:
            {
                var a = new short[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadInt16LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.UInt:
            {
                var a = new ushort[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadUInt16LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.DInt:
            {
                var a = new int[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadInt32LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.UDInt:
            {
                var a = new uint[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadUInt32LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.Time or TwinCATDataType.TimeOfDay:
            {
                // TIME / TOD publish milliseconds as double — the same CLR shape a scalar publishes (#306).
                var a = new double[n];
                for (var i = 0; i < n; i++)
                    a[i] = (double)TwinCATTemporalCodec.Decode(declared, BinaryPrimitives.ReadUInt32LittleEndian(bytes[(i * stride)..]));
                return a;
            }
            case TwinCATDataType.Date or TwinCATDataType.DateTime:
            {
                // DATE / DT publish a UTC DateTime, as a scalar does (#306).
                var a = new DateTime[n];
                for (var i = 0; i < n; i++)
                    a[i] = (DateTime)TwinCATTemporalCodec.Decode(declared, BinaryPrimitives.ReadUInt32LittleEndian(bytes[(i * stride)..]));
                return a;
            }
            case TwinCATDataType.LInt:
            {
                var a = new long[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadInt64LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.ULInt:
            {
                var a = new ulong[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadUInt64LittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.Real:
            {
                var a = new float[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadSingleLittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.LReal:
            {
                var a = new double[n];
                for (var i = 0; i < n; i++) a[i] = BinaryPrimitives.ReadDoubleLittleEndian(bytes[(i * stride)..]);
                return a;
            }
            case TwinCATDataType.String:
            {
                var a = new string[n];
                for (var i = 0; i < n; i++) a[i] = TwinCATStringCodec.DecodeString(bytes.Slice(i * stride, stride), utf8);
                return a;
            }
            case TwinCATDataType.WString:
            {
                var a = new string[n];
                for (var i = 0; i < n; i++) a[i] = TwinCATStringCodec.DecodeWString(bytes.Slice(i * stride, stride));
                return a;
            }
            default:
                throw new NotSupportedException($"TwinCATDataType {declared} has no array element decoding");
        }
    }
}