diff --git a/docs/articles/core/binary/datastream.md b/docs/articles/core/binary/datastream.md index a55ac1db..85ee7565 100644 --- a/docs/articles/core/binary/datastream.md +++ b/docs/articles/core/binary/datastream.md @@ -38,6 +38,14 @@ Another use case is reading a binary format with sections. By creating a modular and safe. It would prevent reading data outside the range of the section. +We can create a _sub-stream_ from the `DataStream` constructor: + +[!code-csharp[SubStreamConstructor](./../../../../src/Yarhl.Examples/IO/DataStreamExamples.cs?name=SubStreamConstructor)] + +or from the `Slice` API: + +[!code-csharp[SubStreamConstructor](./../../../../src/Yarhl.Examples/IO/DataStreamExamples.cs?name=SubStreamSlice)] + ## Factory The constructors of `DataStream` takes a `Stream` with optional offset and diff --git a/src/Yarhl.Examples/IO/DataStreamExamples.cs b/src/Yarhl.Examples/IO/DataStreamExamples.cs new file mode 100644 index 00000000..32a684e0 --- /dev/null +++ b/src/Yarhl.Examples/IO/DataStreamExamples.cs @@ -0,0 +1,44 @@ +// Copyright (c) 2023 SceneGate + +// Permission is hereby granted, free of charge, to any person obtaining a copy +// of this software and associated documentation files (the "Software"), to deal +// in the Software without restriction, including without limitation the rights +// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the Software is +// furnished to do so, subject to the following conditions: + +// The above copyright notice and this permission notice shall be included in all +// copies or substantial portions of the Software. + +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +// SOFTWARE. +namespace Yarhl.Examples.IO; + +using Yarhl.IO; + +public static class DataStreamExamples +{ + public static void CreateSubStreamConstructor() + { + #region SubStreamConstructor + var baseStream = new FileStream("container.bin", FileMode.Open); + using var file1Stream = new DataStream(baseStream, 0x100, 0x2C0); + using var file2Stream = new DataStream(baseStream, 0x3C0, 0x80); + #endregion + } + + public static void CreateSubStreamSlice() + { + #region SubStreamSlice + DataStream containerStream = DataStreamFactory.FromFile("container.bin", FileOpenMode.Read); + using DataStream file1Stream = containerStream.Slice(0x100, 0x2C0); + using DataStream file2Stream = containerStream.Slice(0x3C0, 0x80); + using DataStream lastFileStream = containerStream.Slice(0x8400); + #endregion + } +} diff --git a/src/Yarhl.UnitTests/IO/DataStreamTests.cs b/src/Yarhl.UnitTests/IO/DataStreamTests.cs index e93f214c..b77b3bae 100644 --- a/src/Yarhl.UnitTests/IO/DataStreamTests.cs +++ b/src/Yarhl.UnitTests/IO/DataStreamTests.cs @@ -979,6 +979,107 @@ public void ReadBufferOutOfRange() stream.Dispose(); } + [Test] + public void SliceUsesSameBaseStream() + { + baseStream.Write(new byte[] { 0xCA, 0xFE }); + using var parent = new DataStream(baseStream); + + using DataStream slice = parent.Slice(1); + + Assert.That(parent.BaseStream, Is.SameAs(baseStream)); + Assert.That(slice.BaseStream, Is.SameAs(baseStream)); + } + + [Test] + public void SliceStream() + { + using var stream = new DataStream(); + stream.WriteByte(0xBE); + stream.WriteByte(0xBA); + stream.WriteByte(0xCA); + stream.WriteByte(0xFE); + + using DataStream testSlice = stream.Slice(2); + Assert.That(testSlice, Is.Not.Null); + + Assert.Multiple(() => { + Assert.That(testSlice.Position, Is.EqualTo(0)); + Assert.That(testSlice.Offset, Is.EqualTo(2)); + Assert.That(testSlice.Length, Is.EqualTo(2)); + Assert.That(testSlice.ReadByte(), Is.EqualTo(0xCA)); + }); + } + + [Test] + public void SliceWithLength() + { + baseStream.Write(new byte[] { 0xBE, 0xBA, 0xCA, 0xFE }); + using var stream = new DataStream(baseStream); + + using DataStream testSlice = stream.Slice(2, 1); + + Assert.That(testSlice, Is.Not.Null); + Assert.Multiple(() => { + Assert.That(testSlice.Position, Is.EqualTo(0)); + Assert.That(testSlice.Offset, Is.EqualTo(2)); + Assert.That(testSlice.Length, Is.EqualTo(1)); + Assert.That(testSlice.ReadByte(), Is.EqualTo(0xCA)); + }); + } + + [Test] + public void SliceZeroLengthSucceeds() + { + baseStream.Write(new byte[] { 0xBE, 0xBA, 0xCA, 0xFE }); + using var stream = new DataStream(baseStream); + + using DataStream testSlice = stream.Slice(2, 0); + + Assert.That(testSlice, Is.Not.Null); + Assert.Multiple(() => { + Assert.That(testSlice.Offset, Is.EqualTo(2)); + Assert.That(testSlice.Length, Is.EqualTo(0)); + }); + + using DataStream endSlice = stream.Slice(4); + Assert.That(endSlice, Is.Not.Null); + Assert.Multiple(() => { + Assert.That(endSlice.Offset, Is.EqualTo(4)); + Assert.That(endSlice.Length, Is.EqualTo(0)); + }); + } + + [Test] + public void SliceCannotExpand() + { + baseStream.Write(new byte[] { 0xBE, 0xBA, 0xCA, 0xFE }); + using var stream = new DataStream(baseStream); + + using DataStream testSlice = stream.Slice(2, 1); + + testSlice.Position = 1; + Assert.That(() => testSlice.WriteByte(0xC0), Throws.InstanceOf()); + + using DataStream endSlice = stream.Slice(4, 0); + Assert.That(() => endSlice.WriteByte(0xC0), Throws.InstanceOf()); + } + + [Test] + public void SliceThrowsWithInvalidArgs() + { + baseStream.Write(new byte[] { 0xBE, 0xBA, 0xCA, 0xFE }); + using var stream = new DataStream(baseStream); + + Assert.Multiple(() => { + Assert.That(() => stream.Slice(-1), Throws.InstanceOf()); + Assert.That(() => stream.Slice(5), Throws.InstanceOf()); + Assert.That(() => stream.Slice(-1, 1), Throws.InstanceOf()); + Assert.That(() => stream.Slice(5, 1), Throws.InstanceOf()); + Assert.That(() => stream.Slice(0, 5), Throws.InstanceOf()); + }); + } + [Test] public void WritesAByteAndIncreasePosition() { diff --git a/src/Yarhl/IO/DataStream.cs b/src/Yarhl/IO/DataStream.cs index b57dccd6..18bf9331 100644 --- a/src/Yarhl/IO/DataStream.cs +++ b/src/Yarhl/IO/DataStream.cs @@ -720,6 +720,39 @@ public bool Compare(Stream otherStream) return result; } + /// + /// Creates a substream starting in a defined position. + /// + /// The substream defined by offset and length parameters. + /// Defined starting position. + public DataStream Slice(long start) + { + if (start < 0 || start > Length) { + throw new ArgumentOutOfRangeException(nameof(start)); + } + + return new DataStream(this, start, Length - start); + } + + /// + /// Creates a substream starting in a defined position and with a defined length. + /// + /// The substream defined by offset and length parameters. + /// Defined starting position. + /// Defined length to be written. + public DataStream Slice(long start, long length) + { + if (start < 0 || start > Length) { + throw new ArgumentOutOfRangeException(nameof(start)); + } + + if (length < 0 || start + length > Length) { + throw new ArgumentOutOfRangeException(nameof(length)); + } + + return new DataStream(this, start, length); + } + /// /// Releases all resource used by the /// object.