Add pragma package and use internally.

renggli · Jan 5, 2025 · 5ee66cf · 5ee66cf
1 parent 08d332f
commit 5ee66cf
Show file tree

Hide file tree

Showing 25 changed files with 64 additions and 29 deletions.
diff --git a/lib/more.dart b/lib/more.dart
@@ -12,6 +12,7 @@ export 'package:more/graph.dart';
 export 'package:more/interval.dart';
 export 'package:more/math.dart';
 export 'package:more/number.dart';
+export 'package:more/pragma.dart';
 export 'package:more/printer.dart';
 export 'package:more/temporal.dart';
 export 'package:more/tuple.dart';
diff --git a/lib/pragma.dart b/lib/pragma.dart
@@ -0,0 +1,34 @@
+/// The Dart compilers consider various user annotations (pragmas) during
+/// compilation. This library makes their use easier.
+///
+/// Make sure to study and understand the documentation for the
+/// [Dart VM](https://github.com/dart-lang/sdk/blob/main/runtime/docs/pragmas.md)
+/// and
+/// [Dart2JS](https://github.com/dart-lang/sdk/blob/main/pkg/compiler/doc/pragmas.md)
+/// before using any of this code.
+library;
+
+import 'feature.dart';
+
+// region Pragmas for general use.
+
+/// Never inline a function or method.
+const neverInline = isJavaScript ? neverInlineJs : neverInlineVm;
+const neverInlineJs = pragma('dart2js:never-inline');
+const neverInlineVm = pragma('vm:never-inline');
+
+/// Inline a function or method when possible.
+const preferInline = isJavaScript ? preferInlineJs : preferInlineVm;
+const preferInlineJs = pragma('dart2js:prefer-inline');
+const preferInlineVm = pragma('vm:prefer-inline');
+
+// endregion
+
+// region Unsafe pragmas for general use.
+
+/// Removes all array bounds checks.
+const noBoundsChecks = isJavaScript ? noBoundsChecksJs : noBoundsChecksVm;
+const noBoundsChecksVm = pragma('vm:unsafe:no-bounds-checks');
+const noBoundsChecksJs = pragma('dart2js:index-bounds:trust');
+
+// endregion
diff --git a/lib/src/char_matcher/ascii/ascii.dart b/lib/src/char_matcher/ascii/ascii.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class AsciiCharMatcher extends CharMatcher {
+final class AsciiCharMatcher extends CharMatcher {
   const AsciiCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/digit.dart b/lib/src/char_matcher/ascii/digit.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class DigitCharMatcher extends CharMatcher {
+final class DigitCharMatcher extends CharMatcher {
   const DigitCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/letter.dart b/lib/src/char_matcher/ascii/letter.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class LetterCharMatcher extends CharMatcher {
+final class LetterCharMatcher extends CharMatcher {
   const LetterCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/letter_or_digit.dart b/lib/src/char_matcher/ascii/letter_or_digit.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class LetterOrDigitCharMatcher extends CharMatcher {
+final class LetterOrDigitCharMatcher extends CharMatcher {
   const LetterOrDigitCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/lower_case.dart b/lib/src/char_matcher/ascii/lower_case.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class LowerCaseLetterCharMatcher extends CharMatcher {
+final class LowerCaseLetterCharMatcher extends CharMatcher {
   const LowerCaseLetterCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/punctuation.dart b/lib/src/char_matcher/ascii/punctuation.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class PunctuationCharMatcher extends CharMatcher {
+final class PunctuationCharMatcher extends CharMatcher {
   const PunctuationCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/upper_case.dart b/lib/src/char_matcher/ascii/upper_case.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class UpperCaseLetterCharMatcher extends CharMatcher {
+final class UpperCaseLetterCharMatcher extends CharMatcher {
   const UpperCaseLetterCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/ascii/whitespace.dart b/lib/src/char_matcher/ascii/whitespace.dart
@@ -1,6 +1,6 @@
 import '../char_matcher.dart';
 
-class WhitespaceCharMatcher extends CharMatcher {
+final class WhitespaceCharMatcher extends CharMatcher {
   const WhitespaceCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/basic/lookup.dart b/lib/src/char_matcher/basic/lookup.dart
@@ -2,7 +2,7 @@ import '../../../printer.dart';
 import '../../collection/bitlist.dart';
 import '../char_matcher.dart';
 
-class LookupCharMatcher extends CharMatcher {
+final class LookupCharMatcher extends CharMatcher {
   const LookupCharMatcher(this.start, this.stop, this.buffer);
 
   final int start;

diff --git a/lib/src/char_matcher/basic/range.dart b/lib/src/char_matcher/basic/range.dart
@@ -1,7 +1,7 @@
 import '../../../printer.dart';
 import '../char_matcher.dart';
 
-class RangeCharMatcher extends CharMatcher {
+final class RangeCharMatcher extends CharMatcher {
   const RangeCharMatcher(this.start, this.stop)
       : assert(start <= stop, 'Invalid range: $start-$stop');
 

diff --git a/lib/src/char_matcher/basic/ranges.dart b/lib/src/char_matcher/basic/ranges.dart
@@ -1,7 +1,7 @@
 import '../../../printer.dart';
 import '../char_matcher.dart';
 
-class RangesCharMatcher extends CharMatcher {
+final class RangesCharMatcher extends CharMatcher {
   const RangesCharMatcher(this.length, this.starts, this.stops)
       : assert(starts.length == length, '`starts` has invalid length'),
         assert(stops.length == length, '`stops` has invalid length');

diff --git a/lib/src/char_matcher/basic/single.dart b/lib/src/char_matcher/basic/single.dart
@@ -1,7 +1,7 @@
 import '../../../printer.dart';
 import '../char_matcher.dart';
 
-class SingleCharMatcher extends CharMatcher {
+final class SingleCharMatcher extends CharMatcher {
   const SingleCharMatcher(this.codePoint);
 
   final int codePoint;

diff --git a/lib/src/char_matcher/operator/any.dart b/lib/src/char_matcher/operator/any.dart
@@ -1,7 +1,7 @@
 import '../char_matcher.dart';
 import 'none.dart';
 
-class AnyCharMatcher extends CharMatcher {
+final class AnyCharMatcher extends CharMatcher {
   const AnyCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/operator/conjunctive.dart b/lib/src/char_matcher/operator/conjunctive.dart
@@ -3,7 +3,7 @@ import '../char_matcher.dart';
 import 'any.dart';
 import 'none.dart';
 
-class ConjunctiveCharMatcher extends CharMatcher {
+final class ConjunctiveCharMatcher extends CharMatcher {
   factory ConjunctiveCharMatcher(Iterable<CharMatcher> matchers) =>
       ConjunctiveCharMatcher._(List.of(matchers, growable: false));
 

diff --git a/lib/src/char_matcher/operator/disjunctive.dart b/lib/src/char_matcher/operator/disjunctive.dart
@@ -3,7 +3,7 @@ import '../char_matcher.dart';
 import 'any.dart';
 import 'none.dart';
 
-class DisjunctiveCharMatcher extends CharMatcher {
+final class DisjunctiveCharMatcher extends CharMatcher {
   factory DisjunctiveCharMatcher(Iterable<CharMatcher> matchers) =>
       DisjunctiveCharMatcher._(List.of(matchers, growable: false));
 

diff --git a/lib/src/char_matcher/operator/negate.dart b/lib/src/char_matcher/operator/negate.dart
@@ -1,7 +1,7 @@
 import '../../../printer.dart';
 import '../char_matcher.dart';
 
-class NegateCharMatcher extends CharMatcher {
+final class NegateCharMatcher extends CharMatcher {
   const NegateCharMatcher(this.matcher);
 
   final CharMatcher matcher;

diff --git a/lib/src/char_matcher/operator/none.dart b/lib/src/char_matcher/operator/none.dart
@@ -1,7 +1,7 @@
 import '../char_matcher.dart';
 import 'any.dart';
 
-class NoneCharMatcher extends CharMatcher {
+final class NoneCharMatcher extends CharMatcher {
   const NoneCharMatcher();
 
   @override

diff --git a/lib/src/char_matcher/unicode/unicode.dart b/lib/src/char_matcher/unicode/unicode.dart
@@ -7,7 +7,7 @@ import 'property.dart' as property;
 
 /// Character matcher function that classifies characters using official Unicode
 /// categories and properties.
-class UnicodeCharMatcher extends CharMatcher {
+final class UnicodeCharMatcher extends CharMatcher {
   const UnicodeCharMatcher(this.data, this.mask)
       : assert(data.length == _unicodeCharCount),
         assert(mask <= 0xffffffff);

diff --git a/lib/src/collection/bitlist.dart b/lib/src/collection/bitlist.dart
@@ -4,8 +4,7 @@ import 'dart:typed_data' show Uint32List;
 
 import 'package:collection/collection.dart' show NonGrowableListMixin;
 
-import '../math/bit.dart';
-import 'range/integer.dart' show IntegerRange;
+import '../../more.dart';
 
 /// An space efficient [List] that stores boolean values.
 abstract class BitList extends ListBase<bool> {
@@ -75,8 +74,8 @@ abstract class BitList extends ListBase<bool> {
 
   /// Returns the value of the bit with the given [index]. The behavior is
   /// undefined if [index] is outside of bounds.
-  @pragma('vm:prefer-inline')
-  @pragma('dart2js:tryInline')
+  @preferInline
+  @noBoundsChecks
   bool getUnchecked(int index) =>
       (buffer[index >>> bitShift] & bitSetMask[index & bitOffset]) != 0;
 
@@ -89,8 +88,8 @@ abstract class BitList extends ListBase<bool> {
 
   /// Sets the [value] of the bit with the given [index]. The behavior is
   /// undefined if [index] is outside of bounds.
-  @pragma('vm:prefer-inline')
-  @pragma('dart2js:tryInline')
+  @preferInline
+  @noBoundsChecks
   void setUnchecked(int index, bool value) => value
       ? buffer[index >>> bitShift] |= bitSetMask[index & bitOffset]
       : buffer[index >>> bitShift] &= bitClearMask[index & bitOffset];
@@ -120,8 +119,8 @@ abstract class BitList extends ListBase<bool> {
 
   /// Sets the bit at the specified [index] to the complement of its current
   /// value. The behavior is undefined if [index] is outside of bounds.
-  @pragma('vm:prefer-inline')
-  @pragma('dart2js:tryInline')
+  @preferInline
+  @noBoundsChecks
   void flipUnchecked(int index) =>
       buffer[index >>> bitShift] ^= bitSetMask[index & bitOffset];
 

diff --git a/lib/src/collection/range.dart b/lib/src/collection/range.dart
@@ -12,6 +12,7 @@ import 'iterable/mixins/unmodifiable.dart';
 /// parameters. A range essentially implements a sequence of values of type [E]
 /// as a [List]. The advantage is that a range uses very little memory no matter
 /// its size.
+@immutable
 abstract class Range<E> extends ListBase<E> with UnmodifiableListMixin<E> {
   /// Constructor of the abstract [Range].
   const Range();

diff --git a/lib/src/collection/range/bigint.dart b/lib/src/collection/range/bigint.dart
@@ -11,7 +11,7 @@ import '../range.dart';
 ///    // ...
 /// }
 /// ```
-class BigIntRange extends Range<BigInt> {
+final class BigIntRange extends Range<BigInt> {
   /// The empty range.
   static final empty = BigIntRange._(BigInt.zero, BigInt.zero, BigInt.one, 0);
 

diff --git a/lib/src/collection/range/double.dart b/lib/src/collection/range/double.dart
@@ -12,7 +12,7 @@ import '../range.dart';
 ///    // ...
 /// }
 /// ```
-class DoubleRange extends Range<double> {
+final class DoubleRange extends Range<double> {
   /// The empty range.
   static const empty = DoubleRange._(0, 0, 1, 0);
 

diff --git a/lib/src/collection/range/integer.dart b/lib/src/collection/range/integer.dart
@@ -11,7 +11,7 @@ import '../range.dart';
 ///    // ...
 /// }
 /// ```
-class IntegerRange extends Range<int> {
+final class IntegerRange extends Range<int> {
   /// The empty range.
   static const empty = IntegerRange._(0, 0, 1, 0);