Change argument type of `contains`. (#51)
* Change argument type of `contains`.
Changes the argument type of `contains` to `String` (covariantly).
This only affects the interface, the implementation still accepts `Object?`
and can be safely cast to `Iterable<Object>`.
Documents `contains` better.
Co-authored-by: Nate Bosch <nbosch@google.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 68aa55b..194b5cc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,10 @@
## 1.2.0
* Adds `Characters.empty` constant and makes `Characters("")` return it.
+* Changes the argument type of `Characters.contains` to (covariant) `String`.
+ The implementation still accepts `Object?`, so it can be cast to
+ `Iterable<Object?>`, but you get warned if you try to call directly with a
+ non-`String`.
## 1.1.0
diff --git a/lib/src/characters.dart b/lib/src/characters.dart
index b8b7949..a020674 100644
--- a/lib/src/characters.dart
+++ b/lib/src/characters.dart
@@ -54,15 +54,19 @@
/// as well as controlling the iteration in more detail.
CharacterRange get iteratorAtEnd;
- /// Whether [other] is an element of this sequence of
- /// others.
+ /// Whether [singleCharacterString] occurs in this
+ /// sequence of characters.
///
- /// Returns false if [other] is not a string containing
- /// a single character,
- /// because then it is not a single element of this [Iterable]
- /// of characters.
+ /// Returns true only if [singleCharacterString] is
+ /// a string containing a *single* character
+ /// and that character is one of the characters
+ /// in this character sequence, and false otherwise.
+ /// This behavior is inherited from `Iterable<String>`,
+ /// which is why it is not [Character] based.
+ /// Use [containsAll] for a method which acts like
+ /// [String.contains] for characters.
@override
- bool contains(Object? other);
+ bool contains(covariant String singleCharacterString);
/// Whether this sequence of characters contains [other]
/// as a subsequence.
diff --git a/lib/src/characters_impl.dart b/lib/src/characters_impl.dart
index 389400c..63140c8 100644
--- a/lib/src/characters_impl.dart
+++ b/lib/src/characters_impl.dart
@@ -113,16 +113,16 @@
}
@override
- bool contains(Object? element) {
- if (element is String) {
- if (element.isEmpty) return false;
- var next =
- Breaks(element, 0, element.length, stateSoTNoBreak).nextBreak();
- if (next != element.length) return false;
- // [element] is single grapheme cluster.
- return _indexOf(string, element, 0, string.length) >= 0;
- }
- return false;
+ // ignore: avoid_renaming_method_parameters
+ bool contains(Object? singleCharacterString) {
+ if (singleCharacterString is! String) return false;
+ if (singleCharacterString.isEmpty) return false;
+ var next = Breaks(singleCharacterString, 0, singleCharacterString.length,
+ stateSoTNoBreak)
+ .nextBreak();
+ if (next != singleCharacterString.length) return false;
+ // [singleCharacterString] is single grapheme cluster.
+ return _indexOf(string, singleCharacterString, 0, string.length) >= 0;
}
@override
diff --git a/pubspec.yaml b/pubspec.yaml
index 0e5a5cf..065c191 100644
--- a/pubspec.yaml
+++ b/pubspec.yaml
@@ -1,5 +1,5 @@
name: characters
-version: 1.1.1-dev
+version: 1.2.0
description: String replacement with operations that are Unicode/grapheme cluster aware.
repository: https://www.github.com/dart-lang/characters
