Prepare for v4.0+7.

Author: matanlurey

CHANGELOG.md

@@ -9,6 +9,12 @@
 
 [file an issue]: https://github.com/matanlurey/binary.dart/issues
 
+## 4.0.0-alpha+7
+
+- Added `<Int>.lsb`.
+- Removed bit-operations from `IntExtension`; they are too easy to use
+  incorrectly in the JS VM.
+
 ## 4.0.0-alpha+6
 
 - Just kidding, `checkRange` will return `{{Int}}` if no error is thrown.

lib/src/descriptor.dart

@@ -185,7 +185,7 @@ final class IntDescriptor<T> {
   int countOnes(int v) {
     var count = 0;
     for (var i = 0; i < width; i++) {
-      if (v.nthBit(i)) {
+      if (nthBit(v, i)) {
         count++;
       }
     }
@@ -198,7 +198,7 @@ final class IntDescriptor<T> {
   int countLeadingOnes(int v) {
     var count = 0;
     for (var i = width - 1; i >= 0; i--) {
-      if (v.nthBit(i)) {
+      if (nthBit(v, i)) {
         count++;
       } else {
         break;
@@ -213,7 +213,7 @@ final class IntDescriptor<T> {
   int countLeadingZeros(int v) {
     var count = 0;
     for (var i = width - 1; i >= 0; i--) {
-      if (!v.nthBit(i)) {
+      if (!nthBit(v, i)) {
         count++;
       } else {
         break;
@@ -228,7 +228,7 @@ final class IntDescriptor<T> {
   int countTrailingOnes(int v) {
     var count = 0;
     for (var i = 0; i < width; i++) {
-      if (v.nthBit(i)) {
+      if (nthBit(v, i)) {
         count++;
       } else {
         break;
@@ -243,7 +243,7 @@ final class IntDescriptor<T> {
   int countTrailingZeros(int v) {
     var count = 0;
     for (var i = 0; i < width; i++) {
-      if (!v.nthBit(i)) {
+      if (!nthBit(v, i)) {
         count++;
       } else {
         break;
@@ -416,14 +416,18 @@ final class IntDescriptor<T> {
   @pragma('dart2js:tryInline')
   @pragma('vm:prefer-inline')
   T uncheckedBinaryAnd(int a, int b) {
+    return _uncheckedCast(_overflowingBinaryAnd(a, b));
+  }
+
+  int _overflowingBinaryAnd(int a, int b) {
     // coverage:ignore-start
     if (!_isJsNumerics || unsigned) {
       // coverage:ignore-end
-      return _uncheckedCast(a & b);
+      return a & b;
     }
     // coverage:ignore-start
     final result = a.toUnsigned(width) & b.toUnsigned(width);
-    return _uncheckedCast(result.toSigned(width));
+    return result.toSigned(width);
     // coverage:ignore-end
   }
 
@@ -514,6 +518,46 @@ final class IntDescriptor<T> {
     // coverage:ignore-end
   }
 
+  /// Returns whether the n-th bit is set.
+  @pragma('dart2js:tryInline')
+  @pragma('vm:prefer-inline')
+  bool nthBit(int v, int n) {
+    // Same as `v & (1 << n) != 0`.
+    return _overflowingBinaryAnd(v, overflowingShiftLeft(1, n)) != 0;
+  }
+
+  /// Returns `true` iff `value == 2^n` for some integer `n`.
+  @pragma('dart2js:tryInline')
+  @pragma('vm:prefer-inline')
+  bool isPowerOf2(int v) {
+    // Same as `v > 0 && (v & (v - 1)) == 0`.
+    return v > 0 && uncheckedBinaryAnd(v, v - 1) == 0;
+  }
+
+  /// Returns the smallest power of two greater than or equal to `v`.
+  ///
+  /// If `v` is already a power of two, it is returned.
+  ///
+  /// `v` must be a positive integer.
+  @pragma('dart2js:tryInline')
+  @pragma('vm:prefer-inline')
+  int overflowingNextPowerOf2(int v) {
+    if (isPowerOf2(v)) {
+      return v;
+    }
+    return overflowingShiftLeft(1, v.log2() + 1);
+  }
+
+  /// Calculates the smallest value greater than or equal to `this` that is
+  /// a multiple of [n].
+  ///
+  /// `n` must be a positive integer.
+  @pragma('dart2js:tryInline')
+  @pragma('vm:prefer-inline')
+  int overflowingNextMultipleOf(int v, int n) {
+    return ((v + n - 1) ~/ RangeError.checkNotNegative(n)) * n;
+  }
+
   /// Returns [v] as a binary string.
   String toBinaryString(int v, {bool padded = true}) {
     var result = v.toUnsigned(width).toRadixString(2);

lib/src/extension.dart

@@ -5,7 +5,7 @@ import 'dart:math' as math;
 /// This extension provides additional functionality for integers that is not
 /// provided by the standard library. This includes convenience methods for
 /// accessing `dart:math` functions, as well as behavior that is not provided by
-/// the standard library such as [midpoint] and [isPowerOf2].
+/// the standard library such as [midpoint].
 ///
 /// Methods in [IntExtension] make no assumptions about the size of the
 /// integer.
@@ -119,69 +119,4 @@ extension IntExtension on int {
     // Uses ~/ to ensure that the operation is the same in the VM and JS.
     return (this + other) ~/ 2;
   }
-
-  /// Returns `true` iff `value == 2^n` for some integer `n`.
-  ///
-  /// ## Example
-  ///
-  /// ```dart
-  /// 8.isPowerOf2(); // true
-  /// 9.isPowerOf2(); // false
-  /// ```
-  @pragma('dart2js:tryInline')
-  @pragma('vm:prefer-inline')
-  bool isPowerOf2() => this > 0 && (this & (this - 1)) == 0;
-
-  /// Returns whether the n-th bit is set.
-  ///
-  /// ## Example
-  ///
-  /// ```dart
-  /// 0x0F.nthBit(0); // true
-  /// 0x0F.nthBit(1); // true
-  /// 0x0F.nthBit(2); // true
-  /// 0x0F.nthBit(3); // true
-  /// 0x0F.nthBit(4); // false
-  /// ```
-  @pragma('dart2js:tryInline')
-  @pragma('vm:prefer-inline')
-  bool nthBit(int n) => (this & (1 << n)) != 0;
-
-  /// Returns whether the n-th bit is set.
-  ///
-  /// This is an alias for [nthBit].
-  bool operator [](int n) => nthBit(n);
-
-  /// Returns the smallest power of two greater than or equal to `this`.
-  ///
-  /// If `this` is already a power of two, it is returned.
-  ///
-  /// `this` must be a positive integer.
-  ///
-  /// ## Example
-  ///
-  /// ```dart
-  /// 7.nextPowerOf2(); // 8
-  /// 8.nextPowerOf2(); // 8
-  /// ```
-  @pragma('dart2js:tryInline')
-  @pragma('vm:prefer-inline')
-  int nextPowerOf2() => isPowerOf2() ? this : 1 << (log2() + 1);
-
-  /// Calculates the smallest value greater than or equal to `this` that is
-  /// a multiple of [n].
-  ///
-  /// `n` must be a positive integer.
-  ///
-  /// ## Example
-  ///
-  /// ```dart
-  /// 7.nextMultipleOf(3); // 9
-  /// 8.nextMultipleOf(3); // 9
-  /// ```
-  @pragma('dart2js:tryInline')
-  @pragma('vm:prefer-inline')
-  int nextMultipleOf(int n) {
-    return ((this + n - 1) ~/ RangeError.checkNotNegative(n)) * n;
-  }
 }

lib/src/int16.dart

@@ -98,7 +98,7 @@ extension type const Int16._(int _) implements int {
   static bool isValid(int v) => v >= minInt && v <= maxInt;
 
   /// Returns [value] if its in a valid range for Int16.
-  static Int16 checkRange(int value) {
+  factory Int16.checkRange(int value) {
     RangeError.checkValueInInterval(value, minInt, maxInt, 'value');
     return Int16.fromUnchecked(value);
   }
@@ -335,13 +335,18 @@ extension type const Int16._(int _) implements int {
   }
 
   /// Returns whether the n-th bit is set.
-  bool nthBit(int n) => _.nthBit(n);
+  bool nthBit(int n) => _descriptor.nthBit(_, n);
 
   /// Returns whether the n-th bit is set.
   ///
   /// This is an alias for [nthBit].
   bool operator [](int n) => nthBit(n);
 
+  /// Returns whether the least significant bit is set.
+  ///
+  /// This is equivalent to `nthBit(0)`.
+  bool get lsb => nthBit(0);
+
   /// Returns whether the most significant bit is set.
   ///
   /// This is equivalent to `nthBit(width - 1)`.
@@ -399,7 +404,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).nextPowerOf2(); // 4
   /// ```
-  Int16 nextPowerOf2() => Int16(_.nextPowerOf2());
+  Int16 nextPowerOf2() {
+    return Int16(_descriptor.overflowingNextPowerOf2(_));
+  }
 
   /// Returns the smallest power of two greater than or equal to `this`.
   ///
@@ -408,7 +415,9 @@ extension type const Int16._(int _) implements int {
   /// `this` must be a positive integer.
   ///
   /// If the result is out of range, the behavior is undefined.
-  Int16 uncheckedNextPowerOf2() => Int16.fromUnchecked(_.nextPowerOf2());
+  Int16 uncheckedNextPowerOf2() {
+    return Int16.fromUnchecked(_descriptor.overflowingNextPowerOf2(_));
+  }
 
   /// Returns the smallest power of two greater than or equal to `this`.
   ///
@@ -428,7 +437,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).tryNextPowerOf2(); // 4
   /// ```
-  Int16? tryNextPowerOf2() => tryFrom(_.nextPowerOf2());
+  Int16? tryNextPowerOf2() {
+    return tryFrom(_descriptor.overflowingNextPowerOf2(_));
+  }
 
   /// Returns the smallest power of two greater than or equal to `this`.
   ///
@@ -448,7 +459,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).wrappedNextPowerOf2(); // 4
   /// ```
-  Int16 wrappedNextPowerOf2() => Int16.fromWrapped(_.nextPowerOf2());
+  Int16 wrappedNextPowerOf2() {
+    return Int16.fromWrapped(_descriptor.overflowingNextPowerOf2(_));
+  }
 
   /// Returns the smallest power of two greater than or equal to `this`.
   ///
@@ -468,7 +481,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).clampedNextPowerOf2(); // 4
   /// ```
-  Int16 clampedNextPowerOf2() => Int16.fromClamped(_.nextPowerOf2());
+  Int16 clampedNextPowerOf2() {
+    return Int16.fromClamped(_descriptor.overflowingNextPowerOf2(_));
+  }
 
   /// Calculates the smallest value greater than or equal to `this` that is
   /// a multiple of [n].
@@ -488,7 +503,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).nextMultipleOf(2); // 4
   /// ```
-  Int16 nextMultipleOf(Int16 n) => Int16(_.nextMultipleOf(n._));
+  Int16 nextMultipleOf(Int16 n) {
+    return Int16(_descriptor.overflowingNextMultipleOf(_, n));
+  }
 
   /// Calculates the smallest value greater than or equal to `this` that is
   ///
@@ -498,7 +515,7 @@ extension type const Int16._(int _) implements int {
   ///
   /// If the result is out of range, the behavior is undefined.
   Int16 uncheckedNextMultipleOf(Int16 n) {
-    return Int16.fromUnchecked(_.nextMultipleOf(n._));
+    return Int16.fromUnchecked(_descriptor.overflowingNextMultipleOf(_, n));
   }
 
   /// Calculates the smallest value greater than or equal to `this` that is
@@ -519,7 +536,9 @@ extension type const Int16._(int _) implements int {
   /// ```dart
   /// Int16(3).tryNextMultipleOf(2); // 4
   /// ```
-  Int16? tryNextMultipleOf(Int16 n) => tryFrom(_.nextMultipleOf(n._));
+  Int16? tryNextMultipleOf(Int16 n) {
+    return tryFrom(_descriptor.overflowingNextMultipleOf(_, n));
+  }
 
   /// Calculates the smallest value greater than or equal to `this` that is
   /// a multiple of [n].
@@ -540,7 +559,7 @@ extension type const Int16._(int _) implements int {
   /// Int16(3).wrappedNextMultipleOf(2); // 4
   /// ```
   Int16 wrappedNextMultipleOf(Int16 n) {
-    return Int16.fromWrapped(_.nextMultipleOf(n._));
+    return Int16.fromWrapped(_descriptor.overflowingNextMultipleOf(_, n));
   }
 
   /// Calculates the smallest value greater than or equal to `this` that is
@@ -562,7 +581,7 @@ extension type const Int16._(int _) implements int {
   /// Int16(3).clampedNextMultipleOf(2); // 4
   /// ```
   Int16 clampedNextMultipleOf(Int16 n) {
-    return Int16.fromClamped(_.nextMultipleOf(n._));
+    return Int16.fromClamped(_descriptor.overflowingNextMultipleOf(_, n));
   }
 
   /// Returns the number of `1`s in the binary representation of `this`.