feat: Support read-only spans

Author: ResurrectedTrader

src/D2SSharp/Model/D2SaveOverlay.cs

@@ -595,6 +595,21 @@ public static ref D2SaveLayout From(Span<byte> data)
         return ref layout;
     }
 
+    /// <summary>
+    /// Gets a read-only reference to the layout from a read-only byte span.
+    /// Throws InvalidDataException if magic values are invalid or version is >= 104.
+    /// For v104+ saves, use <see cref="D2SaveLayoutV104.FromReadOnly(ReadOnlySpan{byte})"/> instead.
+    /// </summary>
+    public static ref readonly D2SaveLayout FromReadOnly(ReadOnlySpan<byte> data)
+    {
+        ref readonly var layout = ref MemoryMarshal.AsRef<D2SaveLayout>(data);
+        if (!layout.IsValid)
+            throw new InvalidDataException("Invalid D2 save file: magic values do not match.");
+        if (layout.Header.Version >= 104)
+            throw new InvalidDataException("Save version >= 104 uses a different header layout. Use D2SaveLayoutV104.FromReadOnly() instead.");
+        return ref layout;
+    }
+
     /// <summary>
     /// Updates the checksum in the provided data buffer.
     /// </summary>
@@ -652,44 +667,20 @@ public static ref D2SaveLayoutV104 From(Span<byte> data)
     }
 
     /// <summary>
-    /// Updates the checksum in the provided data buffer.
-    /// </summary>
-    public static void UpdateChecksum(Span<byte> data)
-        => ChecksumCalculator.Update(data);
-}
-
-/// <summary>
-/// Blittable layout for the fixed 64-byte header of a shared stash tab.
-/// Provides zero-copy access to tab header fields without parsing items.
-/// </summary>
-[StructLayout(LayoutKind.Explicit, Size = Size)]
-public unsafe struct D2StashTabLayout
-{
-    /// <summary>Size of the stash tab header in bytes.</summary>
-    public const int Size = 64;
-
-    [FieldOffset(0)] public uint Magic;
-    [FieldOffset(4)] public uint StashFormat;
-    [FieldOffset(8)] public uint ItemFormat;
-    [FieldOffset(12)] public uint Gold;
-    [FieldOffset(16)] public ushort TabSize;
-    [FieldOffset(18)] public ushort Season;
-    [FieldOffset(20)] public StashTabType TabType;
-    [FieldOffset(21)] private fixed byte _reserved[43];
-
-    private readonly bool IsValid => Magic == D2StashTab.Magic;
-
-    /// <summary>
-    /// Gets a reference to the layout from a byte span at the given offset.
+    /// Gets a read-only reference to the layout from a read-only byte span.
+    /// Throws InvalidDataException if magic values are invalid or version is &lt; 104.
     /// </summary>
-    public static ref D2StashTabLayout From(Span<byte> data, int offset = 0)
+    public static ref readonly D2SaveLayoutV104 FromReadOnly(ReadOnlySpan<byte> data)
     {
-        if (data.Length - offset < Size)
-            throw new InvalidDataException($"Data too small for stash tab header: {data.Length - offset} bytes, need {Size}.");
-        ref var layout = ref MemoryMarshal.AsRef<D2StashTabLayout>(data[offset..]);
+        ref readonly var layout = ref MemoryMarshal.AsRef<D2SaveLayoutV104>(data);
         if (!layout.IsValid)
-            throw new InvalidDataException($"Invalid stash tab magic: 0x{layout.Magic:X8}, expected 0x{D2StashTab.Magic:X8}");
+            throw new InvalidDataException("Invalid D2 save file: magic values do not match or version < 104.");
         return ref layout;
     }
 
-}
+    /// <summary>
+    /// Updates the checksum in the provided data buffer.
+    /// </summary>
+    public static void UpdateChecksum(Span<byte> data)
+        => ChecksumCalculator.Update(data);
+}

src/D2SSharp/Model/D2StashTabOverlay.cs

@@ -0,0 +1,52 @@
+using System.Runtime.InteropServices;
+using D2SSharp.Enums;
+
+namespace D2SSharp.Model;
+
+/// <summary>
+/// Blittable layout for the fixed 64-byte header of a shared stash tab.
+/// Provides zero-copy access to tab header fields without parsing items.
+/// </summary>
+[StructLayout(LayoutKind.Explicit, Size = Size)]
+public unsafe struct D2StashTabLayout
+{
+    /// <summary>Size of the stash tab header in bytes.</summary>
+    public const int Size = 64;
+
+    [FieldOffset(0)] public uint Magic;
+    [FieldOffset(4)] public uint StashFormat;
+    [FieldOffset(8)] public uint ItemFormat;
+    [FieldOffset(12)] public uint Gold;
+    [FieldOffset(16)] public ushort TabSize;
+    [FieldOffset(18)] public ushort Season;
+    [FieldOffset(20)] public StashTabType TabType;
+    [FieldOffset(21)] private fixed byte _reserved[43];
+
+    private readonly bool IsValid => Magic == D2StashTab.Magic;
+
+    /// <summary>
+    /// Gets a mutable reference to the layout from a byte span.
+    /// </summary>
+    public static ref D2StashTabLayout From(Span<byte> data)
+    {
+        if (data.Length < Size)
+            throw new InvalidDataException($"Data too small for stash tab header: {data.Length} bytes, need {Size}.");
+        ref var layout = ref MemoryMarshal.AsRef<D2StashTabLayout>(data);
+        if (!layout.IsValid)
+            throw new InvalidDataException($"Invalid stash tab magic: 0x{layout.Magic:X8}, expected 0x{D2StashTab.Magic:X8}");
+        return ref layout;
+    }
+
+    /// <summary>
+    /// Gets a read-only reference to the layout from a read-only byte span.
+    /// </summary>
+    public static ref readonly D2StashTabLayout FromReadOnly(ReadOnlySpan<byte> data)
+    {
+        if (data.Length < Size)
+            throw new InvalidDataException($"Data too small for stash tab header: {data.Length} bytes, need {Size}.");
+        ref readonly var layout = ref MemoryMarshal.AsRef<D2StashTabLayout>(data);
+        if (!layout.IsValid)
+            throw new InvalidDataException($"Invalid stash tab magic: 0x{layout.Magic:X8}, expected 0x{D2StashTab.Magic:X8}");
+        return ref layout;
+    }
+}