Add support for struct.iter_unpack (#729)

* Add support for struct.iter_unpack

* Removed dependency on n/N formats from iter_unpack test.

* Hide the .NET members from Python layer.

* Marked appropriate fields as readonly.

* Added validation for given buffer length.

Author: in-code-i-trust

Src/IronPython.Modules/_struct.cs

@@ -373,6 +373,15 @@ public void pack_into(CodeContext/*!*/ context, [NotNull]ByteArray/*!*/ buffer,
                 return unpack_from(context, buffer.ToByteArray(), offset);
             }
 
+            [Documentation("iteratively unpack the current format from the specified array.")]
+            public PythonUnpackIterator iter_unpack(CodeContext/*!*/ context, [BytesConversion][NotNull]IList<byte>/*!*/ buffer, int offset = 0) {
+                return new PythonUnpackIterator(this, context, buffer, offset);
+            }
+
+            [Documentation("iteratively unpack the current format from the specified array.")]
+            public PythonUnpackIterator iter_unpack(CodeContext/*!*/ context, [NotNull]ArrayModule.array/*!*/ buffer, int offset = 0) {
+                return new PythonUnpackIterator(this, context, buffer, offset);
+            }
 
             [Documentation("gets the number of bytes that the serialized string will occupy or are required to deserialize the data")]
             public int size {
@@ -582,6 +591,88 @@ internal static Struct Create(string/*!*/ format) {
             #endregion
         }
 
+        [PythonType("unpack_iterator"), Documentation("Represents an iterator returned by _struct.iter_unpack()")]
+        public class PythonUnpackIterator : System.Collections.IEnumerator, System.Collections.IEnumerable {
+            private object _iter_current;
+            private int _next_offset;
+
+            private readonly CodeContext _context;
+            private readonly IList<byte> _buffer;
+            private readonly int _start_offset;
+            private readonly Struct _owner;
+
+            private PythonUnpackIterator() { }
+
+            internal PythonUnpackIterator(Struct/*!*/ owner, CodeContext/*!*/ context, IList<byte>/*!*/ buffer, int offset) {
+                _context = context;
+                _buffer = buffer;
+                _start_offset = offset;
+                _owner = owner;
+
+                Reset();
+                ValidateBufferLength();
+            }
+
+            internal PythonUnpackIterator(Struct/*!*/ owner, CodeContext/*!*/ context, ArrayModule.array/*!*/ buffer, int offset) {
+                _context = context;
+                _buffer = buffer.ToByteArray();
+                _start_offset = offset;
+                _owner = owner;
+
+                Reset();
+                ValidateBufferLength();
+            }
+
+            private void ValidateBufferLength() {
+                if (_buffer.Count - _start_offset < _owner.size) {
+                    throw Error(_context, $"iterative unpacking requires a buffer of a multiple of {_owner.size} bytes");
+                }
+            }
+
+            #region IEnumerable
+            [PythonHidden]
+            public System.Collections.IEnumerator GetEnumerator() {
+                return this;
+            }
+            #endregion
+
+            #region IEnumerator
+            [PythonHidden]
+            public object Current => _iter_current;
+
+            [PythonHidden]
+            public bool MoveNext() {
+                if (_buffer.Count - _next_offset < _owner.size) {
+                    return false;
+                }
+
+                _iter_current = _owner.unpack_from(_context, _buffer, _next_offset);
+                _next_offset += _owner.size;
+                return true;
+            }
+
+            [PythonHidden]
+            public void Reset() {
+                _iter_current = null;
+                _next_offset = _start_offset;
+            }
+            #endregion
+
+            public object __iter__() {
+                return this;
+            }
+
+            public object __next__() {
+                if (!MoveNext()) {
+                    throw PythonOps.StopIteration();
+                }
+                return Current;
+            }
+
+            public int __length_hint__() {
+                return (_buffer.Count - _next_offset) / _owner.size;
+            }
+        }
         #endregion
 
         #region Compiled Format
@@ -738,6 +829,15 @@ public static void pack_into(CodeContext/*!*/ context, object fmt, [NotNull]Byte
             return GetStructFromCache(context, fmt).unpack_from(context, buffer, offset);
         }
 
+        [Documentation("Iteratively unpack the buffer, containing packed C structure data, according to\nfmt, starting at offset. Requires len(buffer[offset:]) >= calcsize(fmt).")]
+        public static PythonUnpackIterator/*!*/ iter_unpack(CodeContext/*!*/ context, object fmt, [BytesConversion][NotNull]IList<byte>/*!*/ buffer, int offset = 0) {
+            return GetStructFromCache(context, fmt).iter_unpack(context, buffer, offset);
+        }
+
+        [Documentation("Iteratively unpack the buffer, containing packed C structure data, according to\nfmt, starting at offset. Requires len(buffer[offset:]) >= calcsize(fmt).")]
+        public static PythonUnpackIterator/*!*/ iter_unpack(CodeContext/*!*/ context, object fmt, [NotNull]ArrayModule.array/*!*/ buffer, int offset = 0) {
+            return GetStructFromCache(context, fmt).iter_unpack(context, buffer, offset);
+        }
         #endregion
 
         #region Write Helpers

Tests/test_struct.py

@@ -79,4 +79,22 @@ def assertStructError(func, *args, **kwargs):
                 assertStructError(struct.pack, format, 0)
                 assertStructError(struct.unpack, format, b"")
 
+    def test_iter_unpack(self):
+        import operator
+
+        packed = struct.pack('hlhlhl', 1, 2, 3, 4, 5, 6)
+        it = struct.iter_unpack('hl', packed)
+
+        self.assertEqual(operator.length_hint(it), 3)
+        self.assertEqual(it.__next__(), (1, 2))
+        self.assertEqual(operator.length_hint(it), 2)
+        self.assertEqual(it.__next__(), (3, 4))
+        self.assertEqual(operator.length_hint(it), 1)
+        self.assertEqual(it.__next__(), (5, 6))
+        self.assertEqual(operator.length_hint(it), 0)
+        self.assertRaises(StopIteration, next, it)
+
+        # struct.error: iterative unpacking requires a buffer of a multiple of {N} bytes
+        self.assertRaises(struct.error, struct.iter_unpack, "h", b"\0")
+
 run_test(__name__)