### Install SubstreamSharp via NuGet

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Use the .NET CLI to add the SubstreamSharp package to your project.

```bash
dotnet add package SubstreamSharp
```

--------------------------------

### Flush Operation Example

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Illustrates how the Flush method on a substream propagates to the underlying stream, ensuring buffered data is written to storage. This example writes data to a substream and then flushes it to a file.

```csharp
using SubstreamSharp;
using System.IO;

using (var fileStream = new FileStream("output.bin", FileMode.Create, FileAccess.Write))
{
    // Pre-allocate file with zeros
    fileStream.SetLength(1024);

    var substream = new Substream(fileStream, 128L, 256L);

    // Write data to substream
    var data = new byte[256];
    for (int i = 0; i < data.Length; i++)
        data[i] = (byte)(i % 256);

    substream.Write(data, 0, data.Length);

    // Flush ensures data is written to disk
    substream.Flush();

    Console.WriteLine("Data flushed to underlying file stream");
}
```

--------------------------------

### Stream Properties Example

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Demonstrates how substreams inherit properties like CanRead, CanWrite, and CanSeek from the underlying stream. It also shows the fixed Length property and the unsupported SetLength operation.

```csharp
using SubstreamSharp;
using System.IO;

var data = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
using (var memoryStream = new MemoryStream(data))
{
    var substream = new Substream(memoryStream, 2L, 4L);

    // Inherited properties from underlying stream
    Console.WriteLine($"CanRead: {substream.CanRead}");     // True
    Console.WriteLine($"CanWrite: {substream.CanWrite}");   // True
    Console.WriteLine($"CanSeek: {substream.CanSeek}");     // True
    Console.WriteLine($"CanTimeout: {substream.CanTimeout}"); // False for MemoryStream

    // Fixed length property
    Console.WriteLine($"Length: {substream.Length}");       // 4

    // SetLength is not supported for substreams
    try
    {
        substream.SetLength(8L);
    }
    catch (NotSupportedException ex)
    {
        Console.WriteLine($"SetLength error: {ex.Message}");
        // Output: SetLength error: Cannot set the length of a fixed substream.
    }
}
```

--------------------------------

### Create a Substream from a FileStream

Source: https://github.com/connorhaigh/substreamsharp/blob/master/ReadMe.md

Demonstrates two ways to initialize a substream from a file stream, either by instantiating the Substream class directly or using the extension method.

```csharp
using SubstreamSharp;

using (var fileStream = new FileStream("file", FileMode.Open))
{
	var substream = new Substream(fileStream, 128L, 1024L);
}
```

```csharp
using SubstreamSharp;

using (var fileStream = new FileStream("file", FileMode.Open))
{
	var substream = fileStream.Substream(128L, 1024L);
}
```

--------------------------------

### Initialize Substream via Constructor

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Create a new substream instance by specifying the underlying stream, offset, and length. The underlying stream must support seeking.

```csharp
using SubstreamSharp;
using System.IO;

// Create a file stream and extract a substream from bytes 128-1151 (1024 bytes)
using (var fileStream = new FileStream("archive.bin", FileMode.Open, FileAccess.Read))
{
    // Create substream starting at offset 128 for 1024 bytes
    var substream = new Substream(fileStream, 128L, 1024L);

    // Read from the substream - this reads bytes 128-1151 from the file
    var buffer = new byte[256];
    int bytesRead = substream.Read(buffer, 0, buffer.Length);

    Console.WriteLine($"Read {bytesRead} bytes from substream");
    Console.WriteLine($"Substream position: {substream.Position}");
    Console.WriteLine($"Substream length: {substream.Length}");
}
```

--------------------------------

### Working with Multiple Substreams

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Shows how to create multiple substreams from the same underlying stream to access different regions independently. It highlights that the underlying stream's position can become undefined when switching between substreams, potentially requiring explicit seeking.

```csharp
using SubstreamSharp;
using System.IO;

// Simulate a container file with multiple embedded files
var containerData = new byte[1024];
// Header at 0-127, File1 at 128-383, File2 at 384-639, File3 at 640-895

using (var containerStream = new MemoryStream(containerData))
{
    // Create substreams for each embedded file
    var header = new Substream(containerStream, 0L, 128L);
    var file1 = new Substream(containerStream, 128L, 256L);
    var file2 = new Substream(containerStream, 384L, 256L);
    var file3 = new Substream(containerStream, 640L, 256L);

    // Write to file2 without affecting other regions
    var file2Data = new byte[256];
    Array.Fill(file2Data, (byte)0xAB);
    file2.Write(file2Data, 0, file2Data.Length);

    // Read from file1 (unaffected by file2 write)
    var buffer = new byte[10];
    file1.Read(buffer, 0, 10);
    Console.WriteLine($"File1 first 10 bytes: [{string.Join(", ", buffer)}]");
    // Output: File1 first 10 bytes: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

    // Verify file2 was written
    file2.Position = 0;
    file2.Read(buffer, 0, 10);
    Console.WriteLine($"File2 first 10 bytes: [{string.Join(", ", buffer)}]");
    // Output: File2 first 10 bytes: [171, 171, 171, 171, 171, 171, 171, 171, 171, 171]

    Console.WriteLine($"Each substream has independent position tracking");
    Console.WriteLine($"Header position: {header.Position}, File1: {file1.Position}, File2: {file2.Position}");
}
```

--------------------------------

### Write to a Substream in C#

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Demonstrates writing data to a substream, showing how writes are truncated if they exceed the defined region bounds.

```csharp
using SubstreamSharp;
using System.IO;

var data = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
using (var memoryStream = new MemoryStream(data))
{
    // Create substream for bytes at indices 2-5
    var substream = new Substream(memoryStream, 2L, 4L);

    // Write new values to the substream region
    substream.Write(new byte[] { 9, 10, 11, 12 }, 0, 4);

    // Original stream is modified only within the substream region
    var result = memoryStream.ToArray();
    Console.WriteLine($"Modified data: [{string.Join(", ", result)}]");
    // Output: Modified data: [1, 2, 9, 10, 11, 12, 7, 8]

    // Attempting to write beyond bounds is safely truncated
    substream.Position = 0;
    substream.Write(new byte[] { 20, 21, 22, 23, 24, 25, 26, 27 }, 0, 8);

    result = memoryStream.ToArray();
    Console.WriteLine($"After overflow write: [{string.Join(", ", result)}]");
    // Output: After overflow write: [1, 2, 20, 21, 22, 23, 7, 8]
    // Only 4 bytes written despite 8 being requested
}
```

--------------------------------

### Manage Position Property in C#

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Illustrates direct manipulation of the Position property and handling of invalid position assignments.

```csharp
using SubstreamSharp;
using System.IO;

var data = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
using (var memoryStream = new MemoryStream(data))
{
    var substream = new Substream(memoryStream, 2L, 4L);

    // Get current position
    Console.WriteLine($"Initial position: {substream.Position}");
    // Output: Initial position: 0

    // Set position directly
    substream.Position = 2;
    Console.WriteLine($"After setting to 2: {substream.Position}");
    // Output: After setting to 2: 2

    // Read from current position
    var buffer = new byte[2];
    substream.Read(buffer, 0, 2);
    Console.WriteLine($"Read from position 2: [{string.Join(", ", buffer)}]");
    // Output: Read from position 2: [5, 6]

    // Invalid positions throw exceptions
    try
    {
        substream.Position = -1;
    }
    catch (ArgumentOutOfRangeException)
    {
        Console.WriteLine("Cannot set negative position");
    }

    try
    {
        substream.Position = 10; // Beyond length of 4
    }
    catch (ArgumentOutOfRangeException)
    {
        Console.WriteLine("Cannot set position beyond length");
    }
}
```

--------------------------------

### Create Substream via Extension Method

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Use the fluent Substream extension method on any Stream object as a convenient alternative to the constructor.

```csharp
using SubstreamSharp;
using System.IO;

using (var fileStream = new FileStream("archive.bin", FileMode.Open, FileAccess.ReadWrite))
{
    // Create substream using extension method
    var substream = fileStream.Substream(128L, 1024L);

    // The substream behaves like any other stream
    var data = new byte[100];
    substream.Read(data, 0, data.Length);

    Console.WriteLine($"Position after read: {substream.Position}");
}
```

--------------------------------

### Read Data from a Substream

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Demonstrates how read operations are constrained to the defined region and how the substream handles reads that exceed its bounds.

```csharp
using SubstreamSharp;
using System.IO;

// Create a memory stream with sample data
var data = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
using (var memoryStream = new MemoryStream(data))
{
    // Create substream for bytes at indices 2-5 (values 3, 4, 5, 6)
    var substream = new Substream(memoryStream, 2L, 4L);

    var buffer = new byte[4];
    int bytesRead = substream.Read(buffer, 0, buffer.Length);

    // buffer now contains: { 3, 4, 5, 6 }
    Console.WriteLine($"Read {bytesRead} bytes: [{string.Join(", ", buffer)}]");
    // Output: Read 4 bytes: [3, 4, 5, 6]

    // Reading beyond bounds returns only available bytes
    substream.Position = 0;
    var largeBuffer = new byte[8];
    bytesRead = substream.Read(largeBuffer, 0, largeBuffer.Length);

    // Only 4 bytes read (the substream length), rest remains zero
    Console.WriteLine($"Read {bytesRead} bytes: [{string.Join(", ", largeBuffer)}]");
    // Output: Read 4 bytes: [3, 4, 5, 6, 0, 0, 0, 0]
}
```

--------------------------------

### Seek Within a Substream in C#

Source: https://context7.com/connorhaigh/substreamsharp/llms.txt

Shows how to use Seek with different origins. Note that seeking outside the substream bounds will throw an ArgumentOutOfRangeException.

```csharp
using SubstreamSharp;
using System.IO;

var data = new byte[] { 1, 2, 3, 4, 5, 6, 7, 8 };
using (var memoryStream = new MemoryStream(data))
{
    var substream = new Substream(memoryStream, 0L, 8L);

    // Seek from beginning
    substream.Seek(2L, SeekOrigin.Begin);
    Console.WriteLine($"Position after Seek(2, Begin): {substream.Position}");
    // Output: Position after Seek(2, Begin): 2

    // Seek from end (negative offset)
    substream.Seek(-2L, SeekOrigin.End);
    Console.WriteLine($"Position after Seek(-2, End): {substream.Position}");
    // Output: Position after Seek(-2, End): 6

    // Seek from current position
    substream.Position = 2;
    substream.Seek(2L, SeekOrigin.Current);
    Console.WriteLine($"Position after Seek(2, Current): {substream.Position}");
    // Output: Position after Seek(2, Current): 4

    // Attempting to seek outside bounds throws exception
    try
    {
        substream.Seek(100L, SeekOrigin.Begin);
    }
    catch (ArgumentOutOfRangeException ex)
    {
        Console.WriteLine($"Exception: {ex.Message}");
        // Output: Exception: Offset cannot be greater than the length of the substream.
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.