Readme

Introduction

A package for writing, reading, and debugging binary data.

Issues & contributing

• Found a bug? Create an issue in Github.
• Contributing code? Create a pull request in Github.

A walkthrough

Key classes

• RawWriter:
  • Writes bytes to a buffer.
  • Automatically expands the buffer when isExpanding is true.
• RawReader:
  • Reads bytes from a buffer.
  • If reading fails, throw descriptive exceptions.
• SelfEncoder
  • Classes that know how to encode state using RawWriter.
• SelfDecoder
  • Classes that know how to decode state using RawReader.
• SelfCodec
  • Classes that implement both SelfEncoder and SelfDecoder.

Example of SelfCodec

A typical implementation of SelfCodec looks like this:

class MyStruct extends SelfCodec {
  int intField = 0;
  String stringField = "";
  
  @override
  void encodeSelf(RawWriter writer) {
    writer.writeInt32(intField);
    writer.writeUint32(stringField.length, Endian.little);
    writer.writeUtf8(stringField);
  }
  
  @override
  void decodeSelf(RawReader reader) {
    intField = reader.readInt32();
    final stringLength = reader.readUint32(Endian.little);
    stringField = reader.readUtf(stringLength);
  }
}

Supported primitives

• Numeric types
  • Unsigned/signed integers
    • Uint8 / Int8
    • Uint16 / Int16
    • Uint32 / Int32
    • FixInt64 / FixInt64 (Int64 from fixnum)
  • Floating- point values
    • Float32
    • Float64
  • Variable-length integers (identical with Protocol Buffers encoding)
    • VarUint
    • VarInt
• Sequence types
  • Uint8List
  • ByteData
  • Strings
    • Utf8 / Utf8NullEnding
    • Utf8SingleByte / Utf8SingleByteNullEnding
  • Zeroes

Helpers for testing

import 'package:test/test.dart';
import 'package:raw/raw_test.dart';

void main() {
  test("an example", () {
    final value = [9,8,7];
    final expected = [1,2,3];
    expect(value, byteListEquals(expected));
    
    // Output:
    // 0x0000: 0908 07
    //     (0) ^^^^ ^^
    //         0102 03
  });
}

If your class implements SelfEncoder, use selfEncoderEquals:

class MyStruct extends SelfCodec {
  // ...
}

void main() {
  test("an example", () {
    // ...
    expect(myStruct, selfEncoderEquals(expected));
  });
}

Converting hex formats to bytes

DebugHexDecoder is able to import hex formats such as:

• "0000000: 0123 4567 89ab cdef 0123 4567 89ab cdef ................"
• "0000010: 012345678 ............ # comment"
• "012345678abcdef // no prefix"

Converting bytes to hex-based descriptions

DebugHexEncoder converts bytes to the following format:

0x0000: 0123 4567 89ab cdef  0123 4567 89ab cdef
    (0)
0x0010: 0123 4567 89ab cdef  0123 4567 89ab cdef
   (16)

If expected byte list is specified, bytes are converted to the following format:

0x0000: 0123 5555 89ab cdef  0123 4567 89ab cdef
    (0)      ^ ^^                                 <-- index of the first error: 0x02 (decimal: 2)
             4 67
0x0010: 0123 4567 89ab cdef  0123 4567 89
   (16)                                  ^^ ^^^^  <-- index of the first error: 0x0D (decimal: 13)
                                         ab cdef