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.

Testing

The library includes comprehensive test coverage with 279+ tests covering:

• Basic operations: All read/write methods for each data type
• Endianness: Big-endian and little-endian operations
• Edge cases: Boundary conditions, overflow, special values (NaN, Infinity)
• UTF-8 handling: Multi-byte characters, emoji, malformed sequences
• Buffer management: Expansion, growth strategy, memory efficiency
• Integration tests: Complete read-write cycles and round-trip validation
• Performance tests: Benchmark measurements for optimization

Run tests with:

dart test

Analyze code quality:

dart analyze

License

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