Prepare to publish stable release.

Author: matanlurey

CHANGELOG.md

@@ -1,5 +1,9 @@
 # CHANGELOG
 
+## 4.0.0
+
+Stable release!
+
 > [!IMPORTANT]
 > Version 4.0.0 has a _large_ set of breaking changes, including removing the
 > vast majority of extension methods and boxed classes, in favor of using the
@@ -9,6 +13,13 @@
 
 [file an issue]: https://github.com/matanlurey/binary.dart/issues
 
+**New features**:
+
+- Added `viewOrCopyAsBytes`.
+- Added `BytesBuilderExtension`.
+
+Read the release notes _below_ for a summary of changes.
+
 ## 4.0.0-beta
 
 - Update Dart SDK to `^3.5.0`.

README.md

@@ -1,6 +1,6 @@
 # Binary
 
-Utilities for accessing binary data and bit manipulation in Dart and Flutter.
+Utilities for accessing binary data and bit manipulation in Dart.
 
 [![Binary on pub.dev][pub_img]][pub_url]
 [![Code coverage][cov_img]][cov_url]

lib/binary.dart

@@ -18,8 +18,9 @@
 /// [little endian]: https://en.wikipedia.org/wiki/Endianness
 library;
 
-export 'src/async.dart' show collectBytes;
+export 'src/as_bytes.dart';
 export 'src/bit_list.dart';
+export 'src/collect_bytes.dart';
 export 'src/descriptor.dart';
 export 'src/extension.dart';
 export 'src/int16.dart';

lib/src/as_bytes.dart

@@ -0,0 +1,17 @@
+import 'dart:typed_data';
+
+/// Returns a [Uint8List] representation of the given [bytesOrBuffer].
+///
+/// This method attempts to avoid unnecessary copying of the buffer, and will
+/// return the buffer as-is if it is already a [Uint8List], or a type that can
+/// be viewed as a [Uint8List] (such as a [Uint8ClampedList] or [Uint16List]).
+@pragma('vm:always-consider-inlining')
+Uint8List viewOrCopyAsBytes(List<int> bytesOrBuffer) {
+  // View the buffer as a Uint8List if possible.
+  if (bytesOrBuffer case final TypedData data) {
+    return data.buffer.asUint8List();
+  }
+
+  // Otherwise, copy the buffer into a new Uint8List.
+  return Uint8List.fromList(bytesOrBuffer);
+}

lib/src/async.dart renamed to lib/src/collect_bytes.dart

@@ -9,17 +9,10 @@ import 'dart:typed_data';
 (Future<Uint8List>, Future<void> Function() cancel) collectBytes(
   Stream<List<int>> stream,
 ) {
-  final completer = Completer<Uint8List>.sync();
   final builder = BytesBuilder(copy: false);
-  late final StreamSubscription<void> sub;
-  sub = stream.listen(
-    builder.add,
-    onDone: () async {
-      completer.complete(builder.toBytes());
-      await sub.cancel();
-    },
-    onError: completer.completeError,
-    cancelOnError: true,
-  );
-  return (completer.future, sub.cancel);
+  final sub = stream.listen(builder.add);
+
+  // Intentionally don't await, the goal is to return the future.
+  // ignore: discarded_futures
+  return (sub.asFuture(builder).then((b) => b.takeBytes()), sub.cancel);
 }

lib/src/extension.dart

@@ -1,4 +1,9 @@
+/// @docImport 'uint16.dart';
+/// @docImport 'uint32.dart';
+library;
+
 import 'dart:math' as math;
+import 'dart:typed_data';
 
 /// Additional functionality for any integer, without size restrictions.
 ///
@@ -120,3 +125,60 @@ extension IntExtension on int {
     return (this + other) ~/ 2;
   }
 }
+
+/// Additional functionality for [BytesBuilder].
+extension BytesBuilderExtension on BytesBuilder {
+  /// Appends [word] to the current contents of this builder.
+  ///
+  /// The [word] will be truncated to a [Uint16].
+  void addWord(int word, [Endian endian = Endian.big]) {
+    final byte1 = (word >> 8) & 0xFF;
+    final byte2 = word & 0xFF;
+    if (endian == Endian.big) {
+      addByte(byte1);
+      addByte(byte2);
+    } else {
+      addByte(byte2);
+      addByte(byte1);
+    }
+  }
+
+  /// Appends [words] to the current contents of this builder.
+  ///
+  /// Each value of [words] will be truncated to a [Uint16].
+  void addWords(List<int> words, [Endian endian = Endian.big]) {
+    for (final word in words) {
+      addWord(word, endian);
+    }
+  }
+
+  /// Appends [dword] to the current contents of this builder.
+  ///
+  /// The [dword] will be truncated to a [Uint32].
+  void addDWord(int dword, [Endian endian = Endian.big]) {
+    final byte1 = (dword >> 24) & 0xFF;
+    final byte2 = (dword >> 16) & 0xFF;
+    final byte3 = (dword >> 8) & 0xFF;
+    final byte4 = dword & 0xFF;
+    if (endian == Endian.big) {
+      addByte(byte1);
+      addByte(byte2);
+      addByte(byte3);
+      addByte(byte4);
+    } else {
+      addByte(byte4);
+      addByte(byte3);
+      addByte(byte2);
+      addByte(byte1);
+    }
+  }
+
+  /// Appends [dwords] to the current contents of this builder.
+  ///
+  /// Each value of [dwords] will be truncated to a [Uint32].
+  void addDWords(List<int> dwords, [Endian endian = Endian.big]) {
+    for (final dword in dwords) {
+      addDWord(dword, endian);
+    }
+  }
+}

pubspec.yaml

@@ -1,8 +1,8 @@
 # Format: https://dart.dev/tools/pub/pubspec
 
 name: binary
-description: Utilities for accessing binary data and bit manipulation in Dart and Flutter
-version: 4.0.0-beta
+description: Utilities for accessing binary data and bit manipulation in Dart.
+version: 4.0.0
 
 environment:
   sdk: ^3.5.0

test/src/prelude.dart renamed to test/_prelude.dart

@@ -0,0 +1,63 @@
+import 'dart:typed_data';
+
+import 'package:binary/binary.dart';
+
+import '_prelude.dart';
+
+void main() {
+  test('view a Uint8List', () {
+    final buffer = Uint8List.fromList([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+    final view = viewOrCopyAsBytes(buffer);
+    check(view).deepEquals(buffer);
+
+    // Change the view to see if the buffer is modified.
+    view[0] = 0;
+    check(buffer).deepEquals([0, 2, 3, 4, 5, 6, 7, 8, 9]);
+  });
+
+  test('view a Uint16List', () {
+    final buffer = Uint16List.fromList([
+      0x0102,
+      0x0304,
+      0x0506,
+      0x0708,
+      0x090A,
+    ]);
+
+    final view = viewOrCopyAsBytes(buffer);
+    check(view).deepEquals([
+      0x02,
+      0x01,
+      0x04,
+      0x03,
+      0x06,
+      0x05,
+      0x08,
+      0x07,
+      0x0A,
+      0x09,
+    ]);
+
+    // Change the view to see if the buffer is modified.
+    view[0] = 0;
+    view[1] = 0;
+
+    check(buffer).deepEquals([
+      0x0000,
+      0x0304,
+      0x0506,
+      0x0708,
+      0x090A,
+    ]);
+  });
+
+  test('copy a List<int>', () {
+    final buffer = [1, 2, 3, 4, 5, 6, 7, 8, 9];
+    final copy = viewOrCopyAsBytes(buffer);
+    check(copy).deepEquals(buffer);
+
+    // Change the copy to see the buffer is *not* modified.
+    copy[0] = 0;
+    check(buffer).deepEquals([1, 2, 3, 4, 5, 6, 7, 8, 9]);
+  });
+}

test/as_bytes_test.dart

@@ -1,6 +1,6 @@
 import 'package:binary/binary.dart' show BitList;
 
-import 'src/prelude.dart';
+import '_prelude.dart';
 
 void main() {
   group('fixed-length 16 bits', () {