Binary

Utilities for accessing binary data and bit manipulation in Dart and Flutter.

Getting started

Using package:binary is easy, we have almost no dependencies. Use pub add:

dart pub add binary

Then, import the package and start using it:

import 'package:binary/binary.dart';

// Start using package:binary.

If you are not familiar with extension methods in Dart, it is worth reading the documentation before using this package, which has heavy use of extensions for most functionality. A small primer is instead of writing something like:

void main() {
  // Old API in version <= 0.1.3:
  print(toBinaryPadded(0x0C, 8)); // 00001100
}

You now use toBinaryPadded (and other methods) as an extension method:

void main() {
  // New API.
  print(0x0C.toBinaryPadded(8)); // 00001100
}

Usage

This package provides a few sets of APIs extension methods and boxed classes.

See the API docs for complete documentation.

Most users will use the extension methods on int or String:

// Uses "parseBits" (on String) and "shiftRight" (on int).
void main() {
  test('shiftRight should work identical to >>> in JavaScript', () {
    expect(
      '0111' '1111'.bits.shiftRight(5, 8),
      '0000' '0011'.bits,
    );
  });
}

For convenience, extension methods are also present on List<int>:

// Uses "rotateRight" (on List<int>).
void main() {
  test('rotateRight should work similarly to int.rotateRight', () {
    final list = ['0110' '0000'.bits];
    expect(
      list.rotateRight(0, 1).toBinaryPadded(8),
      '0011' '0000',
    );
  });
}

There are also some specialized extension methods on the typed_data types:

Uint8List, Int8List
Uint16List, Int16List
Uint32List, Int32List

Boxed Types

It is possible to sacrifice performance in order to get more type safety and range checking. For apps or libraries where this is a suitable tradeoff, we provide these boxed types/classes:

Bit
Int4 and Uint4
Int8 and Uint8
Int16 and Uint16
Int32 and Uint32

Bit Patterns

There is also builder-type API for generating patterns to match against bits. The easiest way to explain this API is it is like RegExp, except for matching and capturing components of bits:

void main() {
  // Create a BitPattern.
  final $01V = BitPatternBuilder([
    BitPart.zero,
    BitPart.one,
    BitPart.v(1),
  ]).build();

  // Match it against bits.
  print($01V.matches('011'.bits)); // true

  // Capture variables (if any), similar to a RegExp.
  print($01V.capture('011'.bits)); // [1]
}

Compatibility

This package is intended to work identically and well in both the standalone Dart VM, Flutter, and web builds of Dart and Flutter (both in DDC and Dart2JS). As a result, there are no built-in ways to access integers > 32-bit provided (as web integers are limited).

Feel free to file an issue if you'd like limited support for 64 and 128-bit.

matanlurey / binary.dart