binarize 1.0.0

Binarize allows for a more streamlined and extendable binary creation experience.

Binarize

From Wiktionary:

Etymology

binary + size

Verb

binarize (third-person singular simple present binarizes, present participle binarizing, simple past and past participle binarized)

1. (mathematics) To represent in binary (base 2) notation
2. To convert (an image) to only black and white.
3. (statistics) To dichotomize a variable.

Binarize is a package that wraps the ByteData functionality into a more streamlined and extendable payload system.

With Binarize you can easily create and read binary data into to the correct value types without having to check for the correct byte offset or figure out which ByteData method you need to use.

Installation

Add binarize as a dependency to your pubspec.yaml file (what?).

Import Binarize:

import 'package:binarize/binarize.dart';

Docs & API

The API Docs provide information about how to use Binarize.

If you want to see Binarize in practice, check the example. It showcases most of types that Binarize provides.

Usage

Writing

You can create a writer using the Payload.write method and then use that writer to set your different values and their corresponding types:

import 'package:binarize/binarize.dart';

void main() {
  final writer = Payload.write();
  writer.set(uint8, 16);

  // Binarize the writer to a Uint8List.
  final bytes = binarize(writer);
}

Reading

You can create a reader using the Payload.read method. The reader reads the binary step by step meaning that you will need to read each type in the order that it was written:

import 'package:binarize/binarize.dart';

void main() {
  final writer = Payload.write();
  writer.set(uint8, 16);
  writer.set(string, 'Hello World');

  // Binarize the writer to a Uint8List.
  final bytes = binarize(writer);

  final reader = Payload.read(bytes);
  final ourInt = reader.get(uint8); // First read.
  final ourString = reader.get(string); // Second read.
}

Creating custom PayloadTypes

PayloadTypes are the backbone of Binarize, they do all the heavy lifting for you. Binarize already provides all the basis types that the ByteData class has to offer. But in some cases you want to create your own PayloadType, for instance to convert a custom class into binary and back.

Thankfully Binarize allows you to create your own PayloadType, a good example would be one for the Vector2 from the vector_math package:

import 'package:binarize/binarize.dart';
import 'package:vector_math/vector_math.dart';

// The class is private as we will only exposes a single constant instance of it.
class _Vector2 extends PayloadType<Vector2> {
  const _Vector2();

  @override
  int length(Vector2 value) => 8; // Returns byte offset based on value, in this case just 8 bytes.

  @override
  Vector2 get(ByteData data, int offset) {
    return Vector2(
      data.getFloat32(offset),
      data.getFloat32(offset + 4), // We add 4 otherwise we are getting the same value again.
    );
  }

  @override
  void set(Vector2 value, ByteData data, int offset) {
    data.setFloat32(offset, value.x);
    data.setFloat32(offset + 4, value.y);  // We add 4 so we dont overwriting the previous value.
  }
}

// Public facing constant.
const vector2 = _Vector2();

And we can now use this ParamType in our writer:

import 'package:binarize/binarize.dart';
import 'package:vector_math/vector_math.dart';

import './types/vector2.dart';

void main() {
  final writer = Payload.write();
  writer.set(vector2, Vector2(100.5, 200));

  // Binarize the writer to a Uint8List.
  final bytes = binarize(writer);

  final reader = Payload.read(bytes);
  final ourVector2 = reader.get(vector2);
}