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
andUint4
Int8
andUint8
Int16
andUint16
Int32
andUint32
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.
Libraries
- binary
- Utilities for working with binary data within Dart.