Utilities for accessing binary data and bit manipulation in Dart and Flutter.
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
}
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
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
andUint4
Int8
andUint8
Int16
andUint16
Int32
andUint32
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]
}
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.