binary 1.5.0

  • Readme
  • Changelog
  • Example
  • Installing
  • 75

Binary #

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

Binary on pub.dev Code coverage Github action status Dartdocs Style guide

Getting started #

Using package:binary is easy, we have almost no dependencies:

# Add a new dependency to "pubspec.yaml".
dependencies:
  binary:
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.

CHANGELOG #

1.5.0 #

  • Added BitPatternGroup's constructor, deprecating .toGroup().
  • Added BitPart.zero and BitPart.one and deprecated BitPart(int).

1.4.0 #

  • Added List<int>.toBits() as a replacement for List<int>.parseBits().
  • Added String.bits as a replacement for String.parseBits().
  • Deprecated List<int>.parseBits() and String.parseBits().
  • Deprecated int.as[U]Int{N} functions in favor of manual wrapping.

1.3.0 #

  • Added comparison operators (>, >=, <, <=) to Integral.
  • Added <Integral>.checkRange and <Integral>.assertRange static methods.
  • Added the abiltiy to extend Integral to create custom-sized integers.

1.2.2 #

  • Fixed a bug where _InterpretedBitPattern (the BitPattern generated from BitPatternBuilder) was sorted in an incorrect order (ascending instead of descending), which would not match correctly in some scenarios.

1.2.1 #

  • Fixed a bug where BitPatternBuilder.parse('00AA_AABB') incorrectly threw a FormatException assuming that _ deliniated the end of the A variable segment and the subsequent A was a new segment (which is invalid). It now correctly parses the above as just two variable segments (AAAA, BB).

1.2.0 #

  • Added BitPatternBuilder.parse, a simplified-format for building BitPattern from a string of alpha-numeric characters, where 0 and 1 are pre-defined (static) flags for matching, and charaters are variable segments:

    // Create a BitPattern (Data Structures).
    final $01V = BitPatternBuilder([
      BitPart(0),
      BitPart(1),
      BitPart.v(1, 'A'),
    ]).build();
    
    // Create a BitPattern (Parse a String).
    final $01Vs = BitPatternBuilder.parse('01A').build();
    print($01V == $01Vs); // true
    
  • Fixed a bug where it was not possible to capture variables that were >8-bit.

1.1.0 #

  • Added BitPatternBuilder, BitPattern, BitPart: a new API in order to build bit-based patterns and match against arbitrary sets of bits, optionally extracting variable names. This API is intended to make it easier to build apps and packages around implementing emulators and other decoders.

1.0.0 #

A large update to bring into line for Dart 2, as well take advantage of newer langauge features like extension methods over top-level methods. As a result, the new API is not compatible with previous versions, but migration should be trivial.

0.1.3 #

  • Added arithmeticShiftRight

0.1.2 #

  • Moved into a standalone repository (outside of gba.dart).
  • Added signExtend as a method to Integral.
  • Added areSet.
  • Added msb.

0.1.1 #

  • Added signExtend

0.1.0 #

  • Fixed a bug where int128 and uint128 only had a length of 64.

0.0.4 #

  • Updated the documentation and README.

0.0.3 #

  • Added isZero.

0.0.2 #

  • Added isNegative, hasCarryBit, doesAddOverflow, doesSubOverflow, mask.
  • Added parseBits.

0.0.1 #

  • Add top-level isSet and isClear, Integral#isSet, Integral#isClear.
  • Add checked-mode range checks to bitChunk and bitRange.
  • Fix a bug in the implementation of bitChunk and bitRange.
  • Added a top-level fromBits and Integral#fromBits

0.0.0 #

  • Initial commit, feedback welcome!

example/main.dart

// ignore_for_file: avoid_print
import 'package:binary/binary.dart';

void main() {
  // Using extension methods.
  //                  String         int
  //                 vvvvvvvvvv   vvvvvvvvvv
  print('0111' '1111'.bits.shiftRight(5, 8));

  // Using boxed types.
  final int8 = Int8('0111' '1111'.bits);
  // Note we did not need to pass in the length, it is provided by the class.
  print(int8.shiftRight(5));

  // Using bit patterns.
  final $01V = BitPatternBuilder(const [
    BitPart.zero,
    BitPart.one,
    BitPart.v(1, 'V'),
  ]).build();
  print($01V.matches('011'.bits)); // true
  print($01V.capture('011'.bits)); // [1]

  // Alternative bit pattern.
  final $01Vs = BitPatternBuilder.parse('01V').build();
  print($01V == $01Vs); // true
}

Use this package as a library

1. Depend on it

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


dependencies:
  binary: ^1.5.0

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter pub get

Alternatively, your editor might support pub get or flutter pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:binary/binary.dart';
  
Popularity:
Describes how popular the package is relative to other packages. [more]
51
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
75
Learn more about scoring.

We analyzed this package on Jul 9, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.8.4
  • pana: 0.13.14

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.8.0 <3.0.0
meta ^1.1.8 1.2.2 1.3.0-nullsafety
Dev dependencies
pedantic ^1.9.0
test ^1.15.0
test_coverage ^0.4.1