Add some extra functionality.

CHANGELOG.md

@@ -1,8 +1,15 @@
+## 1.1.0-nullsafety.3
+
+* Added `stringBeforeLength` and `stringAfterLength` to `CharacterRange`.
+* Added `CharacterRange.at` constructor.
+* Added `getRange(start, end)` and `characterAt(pos)` to `Characters`
+  as alternative to `.take(end).skip(start)` and `getRange(pos, pos + 1)`.
+* Change some positional parameter names from `other` to `characters`.
+
 ## 1.1.0-nullsafety.2
 
 * Update for the 2.10 dev sdk.
 
-
 ## 1.1.0-nullsafety.1
 
 * Allow the <=2.9.10 stable sdks.

analysis_options.yaml

@@ -1,8 +1,6 @@
-include: package:pedantic/analysis_options.yaml
+include: package:pedantic/analysis_options.1.9.0.yaml
 analyzer:
   errors:
-    omit_local_variable_types: ignore
-    annotate_overrides: ignore
     prefer_single_quotes: ignore
     use_function_type_syntax_for_parameters: ignore
   enable-experiment:

benchmark/benchmark.dart

@@ -9,8 +9,8 @@ import "package:characters/characters.dart";
 import "../test/src/text_samples.dart";
 
 double bench(int Function() action, int ms) {
-  int elapsed = 0;
-  int count = 0;
+  var elapsed = 0;
+  var count = 0;
   var stopwatch = Stopwatch()..start();
   do {
     count += action();
@@ -20,7 +20,7 @@ double bench(int Function() action, int ms) {
 }
 
 int iterateIndicesOnly() {
-  int graphemeClusters = 0;
+  var graphemeClusters = 0;
   var char = Characters(hangul).iterator;
   while (char.moveNext()) {
     graphemeClusters++;
@@ -33,7 +33,7 @@ int iterateIndicesOnly() {
 }
 
 int iterateStrings() {
-  int codeUnits = 0;
+  var codeUnits = 0;
   var char = Characters(hangul).iterator;
   while (char.moveNext()) {
     codeUnits += char.current.length;
@@ -58,7 +58,7 @@ int reverseStrings() {
 }
 
 int replaceStrings() {
-  int count = 0;
+  var count = 0;
   {
     const language = "한글";
     assert(language.length == 6);
@@ -85,7 +85,7 @@ String reverse(String input) {
 }
 
 void main(List<String> args) {
-  int count = 1;
+  var count = 1;
   if (args.isNotEmpty) count = int.tryParse(args[0]) ?? 1;
 
   // Warmup.
@@ -94,7 +94,7 @@ void main(List<String> args) {
   bench(reverseStrings, 250);
   bench(replaceStrings, 250);
 
-  for (int i = 0; i < count; i++) {
+  for (var i = 0; i < count; i++) {
     var performance = bench(iterateIndicesOnly, 2000);
     print("Index Iteration: $performance gc/ms");
     performance = bench(iterateStrings, 2000);

example/main.dart

@@ -3,7 +3,7 @@ import 'package:characters/characters.dart';
 // Small API examples. For full API docs see:
 // https://pub.dev/documentation/characters/latest/characters/characters-library.html
 void main() {
-  String hi = 'Hi 🇩🇰';
+  var hi = 'Hi 🇩🇰';
   print('String is "$hi"\n');
 
   // Length.
@@ -19,7 +19,7 @@ void main() {
   print('Skipping last character: "${hi.characters.skipLast(1)}"\n');
 
   // Replace characters.
-  Characters newHi =
+  var newHi =
       hi.characters.replaceAll('🇩🇰'.characters, '🇺🇸'.characters);
   print('Change flag: "$newHi"');
 }

lib/src/characters.dart

@@ -35,6 +35,7 @@ abstract class Characters implements Iterable<String> {
   /// Allows iterating the characters of [string] as a plain iterator,
   /// using [CharacterRange.moveNext],
   /// as well as controlling the iteration in more detail.
+  @override
   CharacterRange get iterator;
 
   /// Iterator over the characters of this string.
@@ -54,6 +55,7 @@ abstract class Characters implements Iterable<String> {
   /// a single character,
   /// because then it is not a single element of this [Iterable]
   /// of characters.
+  @override
   bool contains(Object? other);
 
   /// Whether this sequence of characters contains [other]
@@ -92,22 +94,57 @@ abstract class Characters implements Iterable<String> {
   ///
   /// Tests each character against [test], and returns the
   /// characters of the concatenation of those character strings.
+  @override
   Characters where(bool Function(String) test);
 
   /// Eagerly selects all but the first [count] characters.
   ///
   /// If [count] is greater than [length], the count of character
   /// available, then the empty sequence of characters
   /// is returned.
+  @override
   Characters skip(int count);
 
   /// Eagerly selects the first [count] characters.
   ///
   /// If [count] is greater than [length], the count of character
   /// available, then the entire sequence of characters
   /// is returned.
+  @override
   Characters take(int count);
 
+  /// Eagerly selects the range of characters from [start] to [end].
+  ///
+  /// The [start] value must be non-negative,
+  /// and [end], if supplied, must be greater than or equal to [start].
+  ///
+  /// A `characters.getRange(start, end)` is equivalent to
+  /// ```dart
+  ///  (end != null ? characters.take(end) : characters).skip(start)
+  /// ```
+  /// if [end] is omitted, the call is equivalent to `characters.skip(start)`.
+  ///
+  /// If [start] is greater than or equal to [length]
+  /// the returned characters is empty.
+  /// Otherwise, if [end] is greater than [length], or omitted,
+  /// [end] is equivalent to [length].
+  Characters getRange(int start, [int? end]);
+
+  /// Returns the single-character sequence of the [position]th character.
+  ///
+  /// The [position] must be non-negative and less than [length].
+  ///
+  /// This operation must iterate characters up to [position] to find
+  /// the result, just like [elementAt].
+  /// It is not an efficient way to iterate over the individual characters
+  /// of a `Characters`.
+  ///
+  /// An call to `chars.characterAt(n)`
+  /// is equivalent to `chars.elementAt(n).characters`,
+  /// or to `chars.getRange(n, n + 1)`
+  /// (except that [getRange] allows `n` to be larger than [length]).
+  Characters characterAt(int position);
+
   /// Eagerly selects all but the last [count] characters.
   ///
   /// If [count] is greater than [length], the count of character
@@ -131,6 +168,7 @@ abstract class Characters implements Iterable<String> {
   ///
   /// If no characters test `false`, the result is an empty sequence
   /// of characters.
+  @override
   Characters skipWhile(bool Function(String) test);
 
   /// Eagerly selects a leading sequence of characters.
@@ -142,6 +180,7 @@ abstract class Characters implements Iterable<String> {
   ///
   /// If no characters test `false`, the entire sequence of character
   /// is returned.
+  @override
   Characters takeWhile(bool Function(String) test);
 
   /// Eagerly selects a leading sequence of characters.
@@ -236,12 +275,15 @@ abstract class Characters implements Iterable<String> {
   Characters toUpperCase();
 
   /// The hash code of [string].
+  @override
   int get hashCode;
 
   /// Whether [other] to another [Characters] with the same [string].
+  @override
   bool operator ==(Object other);
 
   /// The [string] content of these characters.
+  @override
   String toString();
 }
 
@@ -281,6 +323,28 @@ abstract class CharacterRange implements Iterator<String> {
   /// of [string].
   factory CharacterRange(String string) = StringCharacterRange;
 
+  /// Creates a new character iterator on [string].
+  ///
+  /// The iterator starts with a current range containing the
+  /// substring from [startIndex] to [endIndex] of [string].
+  /// If [startIndex] is not a character boundary,
+  /// the range starts at the beginning of the character
+  /// that [startIndex] is pointing into.
+  /// If [endIndex] is not a character boundary,
+  /// the range end at then end of the character
+  /// that [endIndex] is pointing into.
+  /// If [endIndex] is not provided,
+  /// it defaults to the same index as [startIndex].
+  ///
+  /// So, if no [endIndex] is provided,
+  /// and [startIndex] is at a character boundary,
+  /// the resulting iterator's current range is empty.
+  /// Otherwise, the range will contain the characters
+  /// of the substring from [startIndex] to [endIndex],
+  /// extended so that it contains entire characters of the original [string].
+  factory CharacterRange.at(String string, int startIndex, [int? endIndex]) =
+      StringCharacterRange.at;
+
   /// The character sequence that this range is a sub-sequence of.
   Characters get source;
 
@@ -302,9 +366,15 @@ abstract class CharacterRange implements Iterator<String> {
   /// The string of the characters before the current range.
   String get stringBefore;
 
+  /// The length, in code units, of [stringBefore].
+  int get stringBeforeLength;
+
   /// The string of the characters after the current range.
   String get stringAfter;
 
+  /// The length, in code units, of [stringAfter].
+  int get stringAfterLength;
+
   /// Creates a copy of this [CharacterRange].
   ///
   /// The copy is in the exact same state as this iterator.
@@ -336,6 +406,7 @@ abstract class CharacterRange implements Iterator<String> {
   ///
   /// Returns `true` if there were [count] following characters
   /// and `false` if not.
+  @override
   bool moveNext([int count = 1]);
 
   /// Moves the range to be everything after the current range.