SharpEndian 1.0.2

SharpEndian Library Documentation

Overview

SharpEndian is a .NET library that provides endian-aware binary I/O operations. It allows you to read and write binary data while handling byte order (endianness) transparently, which is essential when working with binary file formats, network protocols, or cross-platform data interchange.

Core Concepts

• Endianness refers to the order in which bytes are stored in memory:
• Little Endian: Least significant byte first (e.g., x86/x64 processors)
• Big Endian: Most significant byte first (e.g., network byte order, many file formats)

Installation

# Add reference to your project
dotnet add reference SharpEndian.dll

Getting Started

Basic Usage

using SharpEndian;

// Reading a file with big-endian data
using var io = new EndianIO("data.bin", EndianStyle.BigEndian);
int value = io.Reader.ReadInt32();
string text = io.Reader.ReadUnicodeString(10);

// Writing data
io.Writer.Write(42);
io.Writer.WriteStringNullTerminated("Hello");

Class Reference

EndianIO

The main class that combines reading and writing operations with endian-aware I/O.

Constructors

// Open a file with specified endian style and file mode
EndianIO(string filePath, EndianStyle endianStyle, FileMode fileMode)

// Open a file with default FileMode.Open
EndianIO(string filePath, EndianStyle endianStyle)

// Work with an existing stream
EndianIO(Stream stream, EndianStyle endianStyle)

// Work with a byte array in memory
EndianIO(byte[] buffer, EndianStyle endianStyle)

Properties

Methods

void Close()              // Closes all streams and releases resources
byte[] ToArray()          // Converts MemoryStream to byte array
void Dispose()            // Disposes and releases all resources

Example Usage

// File-based I/O
using var io = new EndianIO("game.dat", EndianStyle.BigEndian, FileMode.OpenOrCreate);
io.Writer.Write(12345);
io.Position = 0;  // Rewind
int value = io.Reader.ReadInt32();

// Memory-based I/O
byte[] buffer = new byte[1024];
using var memIO = new EndianIO(buffer, EndianStyle.LittleEndian);
memIO.Writer.Write((short)100);
memIO.Position = 0;
short result = memIO.Reader.ReadInt16();

// Get byte array from memory stream
byte[] output = memIO.ToArray();

EndianReader

Provides methods for reading binary data with configurable endianness.

Core Read Methods

short ReadInt16()                        // Read 16-bit signed integer
short ReadInt16(EndianStyle style)       // Read with explicit endian style

ushort ReadUInt16()                      // Read 16-bit unsigned integer
ushort ReadUInt16(EndianStyle style)

int ReadInt24()                          // Read 24-bit signed integer
int ReadInt24(EndianStyle style)

int ReadInt32()                          // Read 32-bit signed integer
int ReadInt32(EndianStyle style)

uint ReadUInt32()                        // Read 32-bit unsigned integer
uint ReadUInt32(EndianStyle style)

long ReadInt64()                         // Read 64-bit signed integer
long ReadInt64(EndianStyle style)

ulong ReadUInt64()                       // Read 64-bit unsigned integer
ulong ReadUInt64(EndianStyle style)

float ReadSingle()                       // Read single-precision float
float ReadSingle(EndianStyle style)

double ReadDouble()                      // Read double-precision float
double ReadDouble(EndianStyle style)

String Read Methods

// Read fixed-length Unicode string (UTF-16)
string ReadUnicodeString(int length)
string ReadUnicodeString(int length, EndianStyle style)

// Read null-terminated Unicode string
string ReadUnicodeNullTermString()
string ReadUnicodeNullTermString(EndianStyle style)

// Read null-terminated ASCII string
string ReadStringNullTerminated()

Utility Methods

void Seek(long position)           // Set stream position
uint SeekAndRead(long address)     // Seek and read uint32

Example Usage

using var io = new EndianIO("data.bin", EndianStyle.BigEndian);
var reader = io.Reader;

// Read various data types
short version = reader.ReadInt16();
int fileSize = reader.ReadInt32();
float ratio = reader.ReadSingle();

// Read strings
string name = reader.ReadUnicodeString(20);  // Fixed 20 chars
string path = reader.ReadStringNullTerminated();

// Mix endianness in same file
int bigEndianValue = reader.ReadInt32(EndianStyle.BigEndian);
int littleEndianValue = reader.ReadInt32(EndianStyle.LittleEndian);

// Seek to specific position
reader.Seek(100);
uint header = reader.SeekAndRead(0);  // Read from offset 0

EndianWriter

Provides methods for writing binary data with configurable endianness.

Core Write Methods

void Write(short value)                      // Write 16-bit signed integer
void Write(short value, EndianStyle style)

void Write(ushort value)                     // Write 16-bit unsigned integer
void Write(ushort value, EndianStyle style)

void WriteInt24(int value)                   // Write 24-bit signed integer
void WriteInt24(int value, EndianStyle style)

void Write(int value)                        // Write 32-bit signed integer
void Write(int value, EndianStyle style)

void Write(uint value)                       // Write 32-bit unsigned integer
void Write(uint value, EndianStyle style)

void Write(long value)                       // Write 64-bit signed integer
void Write(long value, EndianStyle style)

void Write(ulong value)                      // Write 64-bit unsigned integer
void Write(ulong value, EndianStyle style)

void Write(float value)                      // Write single-precision float
void Write(float value, EndianStyle style)

void Write(double value)                     // Write double-precision float
void Write(double value, EndianStyle style)

String Write Methods

// Write fixed-length Unicode string (pads with nulls if needed)
void WriteUnicodeString(int length)
void WriteUnicodeString(string value, int length)
void WriteUnicodeString(string value, int length, EndianStyle style)

// Write null-terminated Unicode string
void WriteUnicodeNullTerminatedString(string value)
void WriteUnicodeNullTerminatedString(string value, EndianStyle style)

// Write null-terminated ASCII string
void WriteStringNullTerminated(string value)

Utility Methods

void Seek(long position)                     // Set stream position
void SeekAndWrite(long position, int value)  // Seek and write int32
void SeekAndWrite(long position, uint value) // Seek and write uint32
void SeekAndWrite(long position, short value)
void SeekAndWrite(long position, ushort value)

Example Usage

using var io = new EndianIO("output.bin", EndianStyle.BigEndian, FileMode.Create);
var writer = io.Writer;

// Write various data types
writer.Write((short)1);        // Version
writer.Write(1024);            // File size
writer.Write(1.5f);            // Ratio

// Write strings
writer.WriteUnicodeString("Player1", 20);  // Pad to 20 chars
writer.WriteStringNullTerminated("Level 1");

// Write with different endianness
writer.Write(0x12345678, EndianStyle.BigEndian);
writer.Write(0xABCDEF00, EndianStyle.LittleEndian);

// Update value at specific position
writer.SeekAndWrite(0, 1000);  // Update size at offset 0

// Write 24-bit value
writer.WriteInt24(0x123456);

Common Patterns

Reading a Binary File Format

using var io = new EndianIO("game.sav", EndianStyle.BigEndian);

// Read header
string magic = io.Reader.ReadStringNullTerminated();
int version = io.Reader.ReadInt32();
int recordCount = io.Reader.ReadInt32();

// Read records
for (int i = 0; i < recordCount; i++)
{
    string name = io.Reader.ReadUnicodeString(32);
    int score = io.Reader.ReadInt32();
    float time = io.Reader.ReadSingle();
}

Creating a Binary File

using var io = new EndianIO("output.dat", EndianStyle.LittleEndian, FileMode.Create);

// Write header
io.Writer.WriteStringNullTerminated("MYFORMAT");
io.Writer.Write(1);  // Version
io.Writer.Write(items.Count);

// Write data
foreach (var item in items)
{
    io.Writer.WriteUnicodeString(item.Name, 32);
    io.Writer.Write(item.Value);
}

Working with Memory Buffers

// Create in-memory buffer
byte[] buffer = new byte[1024];
using var io = new EndianIO(buffer, EndianStyle.BigEndian);

// Write data
io.Writer.Write(0x12345678);
io.Writer.WriteStringNullTerminated("Test");

// Read it back
io.Position = 0;
int value = io.Reader.ReadInt32();
string text = io.Reader.ReadStringNullTerminated();

// Get final buffer
byte[] result = io.ToArray();

Mixing Endianness

Some file formats use different endianness for different sections:

using var io = new EndianIO("mixed.bin", EndianStyle.LittleEndian);

// Header in little endian (uses default)
int headerSize = io.Reader.ReadInt32();

// Data section in big endian
int dataValue = io.Reader.ReadInt32(EndianStyle.BigEndian);

Updating Existing Files

using var io = new EndianIO("config.dat", EndianStyle.LittleEndian, FileMode.Open);

// Read current value
io.Position = 100;
int oldValue = io.Reader.ReadInt32();

// Update it
io.Writer.SeekAndWrite(100, oldValue + 1);

Best Practices

1. Always use using statements to ensure proper disposal of resources
2. Choose the correct endianness based on your file format or protocol specification
3. Handle exceptions when working with files (IOException, ArgumentException, etc.)
4. Use fixed-length strings when the format requires specific field sizes
5. Document your byte order choices in comments for maintainability
6. Consider memory vs file operations - use byte[] constructor for small data, file constructor for large files

Error Handling

try
{
    using var io = new EndianIO("data.bin", EndianStyle.BigEndian);
    // Perform operations
}
catch (FileNotFoundException ex)
{
    Console.WriteLine($"File not found: {ex.Message}");
}
catch (IOException ex)
{
    Console.WriteLine($"I/O error: {ex.Message}");
}
catch (ArgumentException ex)
{
    Console.WriteLine($"Invalid argument: {ex.Message}");
}

Performance Tips

• Reuse EndianIO instances when reading/writing multiple values
• Use byte arrays for small in-memory operations
• Consider buffering when working with streams
• Use SeekAndWrite/SeekAndRead for random access patterns

License

The project is licensed under the MIT license.