pro_binary

Efficient binary serialization library for Dart with comprehensive boundary checks and detailed error messages.

Features

✅ Read/write operations for all primitive types (int8/16/32/64, uint8/16/32/64, float32/64)
✅ Big-endian and little-endian support
✅ Comprehensive boundary checks with detailed error messages
✅ UTF-8 string encoding with multibyte character support
✅ Dynamic buffer resizing with efficient memory management
✅ Zero-copy operations where possible

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  pro_binary: ^2.1.0

Then, run pub get to install the package.

Quick Start

Writing

import 'package:pro_binary/pro_binary.dart';

void main() {
  final writer = BinaryWriter()
    ..writeUint8(42)
    ..writeUint32(1000000, Endian.little)
    ..writeFloat64(3.14159)
    ..writeString('Hello');

  final bytes = writer.takeBytes();
  print('Written ${bytes.length} bytes');
}

Reading

import 'dart:typed_data';
import 'package:pro_binary/pro_binary.dart';

void main() {
  final data = Uint8List.fromList([42, 64, 66, 15, 0]);
  final reader = BinaryReader(data);

  final value1 = reader.readUint8();           // 42
  final value2 = reader.readUint32(Endian.little); // 1000000
  
  print('Read: $value1, $value2');
  print('Remaining: ${reader.availableBytes} bytes');
}

API Overview

BinaryWriter

final writer = BinaryWriter(initialBufferSize: 64);

// Write operations
writer.writeUint8(255);
writer.writeInt8(-128);
writer.writeUint16(65535, Endian.big);
writer.writeInt16(-32768, Endian.big);
writer.writeUint32(4294967295, Endian.big);
writer.writeInt32(-1000, Endian.big);
writer.writeUint64(9223372036854775807, Endian.big);
writer.writeInt64(-9223372036854775808, Endian.big);
writer.writeFloat32(3.14, Endian.big);
writer.writeFloat64(3.14159, Endian.big);
writer.writeBytes([1, 2, 3]);
writer.writeString('text');

// Buffer operations
final bytes = writer.toBytes();      // Get view without reset
final result = writer.takeBytes();   // Get view and reset
writer.reset();                       // Reset without returning
print(writer.bytesWritten);          // Check written size

BinaryReader

final reader = BinaryReader(buffer);

// Read operations
final u8 = reader.readUint8();
final i8 = reader.readInt8();
final u16 = reader.readUint16(Endian.big);
final i16 = reader.readInt16(Endian.big);
final u32 = reader.readUint32(Endian.big);
final i32 = reader.readInt32(Endian.little);
final u64 = reader.readUint64(Endian.big);
final i64 = reader.readInt64(Endian.big);
final f32 = reader.readFloat32(Endian.big);
final f64 = reader.readFloat64(Endian.big);
final bytes = reader.readBytes(10);
final text = reader.readString(5);

// Peek without advancing position
final peeked = reader.peekBytes(4);  // View without consuming

// Navigation
reader.skip(4);                      // Skip bytes
final pos = reader.offset;           // Current position
final used = reader.usedBytes;       // Bytes read so far
reader.reset();                      // Reset to start
print(reader.availableBytes);        // Remaining bytes

Error Handling

All read operations validate boundaries and provide detailed error messages:

try {
  reader.readUint32(); // Not enough bytes
} catch (e) {
  // AssertionError: Not enough bytes to read Uint32: 
  // required 4 bytes, available 2 bytes at offset 10
}

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on:

How to set up the development environment
Running tests and coverage
Code style and formatting
Submitting pull requests

For bugs and features, use the issue templates.

License

This project is licensed under the MIT License. See the LICENSE file for more details.