Clean-up of minor details. Deprecated `newInstance `methods. (#103)
* Clean-up on implementation of `DigestSink` to not use `late`.
* Update documentation for implementation classes, deprecate `newInstance` instance method.
* Update CHANGELOG.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 51c0463..7c508f2 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,7 +10,9 @@
2.10.0-2.0.dev, which is the first version where this package will appear in the
null safety allow list.
- * AddsSHA-2 512/224 and SHA-2 512/256 from FIPS 180-4
+* Adds SHA-2 512/224 and SHA-2 512/256 from FIPS 180-4
+
+* Deprecates `newInstance` instance members on some classes and updates documentation.
## 2.1.5
diff --git a/lib/src/digest.dart b/lib/src/digest.dart
index 2cade77..1bb46a3 100644
--- a/lib/src/digest.dart
+++ b/lib/src/digest.dart
@@ -21,10 +21,10 @@
if (other is Digest) {
final a = bytes;
final b = other.bytes;
- if (a.length != b.length) {
+ final n = a.length;
+ if (n != b.length) {
return false;
}
- final n = a.length;
var mismatch = 0;
for (var i = 0; i < n; i++) {
mismatch |= a[i] ^ b[i];
diff --git a/lib/src/digest_sink.dart b/lib/src/digest_sink.dart
index 39b865b..008c8b9 100644
--- a/lib/src/digest_sink.dart
+++ b/lib/src/digest_sink.dart
@@ -6,22 +6,25 @@
/// A sink used to get a digest value out of `Hash.startChunkedConversion`.
class DigestSink extends Sink<Digest> {
- /// The value added to the sink, if any.
- Digest get value => _value;
+ /// The value added to the sink.
+ ///
+ /// A value must have been added using [add] before reading the `value`.
+ Digest get value => _value!;
- late final Digest _value;
+ Digest? _value;
/// Adds [value] to the sink.
///
/// Unlike most sinks, this may only be called once.
@override
void add(Digest value) {
+ assert(_value == null);
_value = value;
}
@override
void close() {
// Ensure late final field was assigned before closing.
- assert((_value as dynamic) != null);
+ assert(_value != null);
}
}
diff --git a/lib/src/hash_sink.dart b/lib/src/hash_sink.dart
index 8cd4b99..adebf22 100644
--- a/lib/src/hash_sink.dart
+++ b/lib/src/hash_sink.dart
@@ -25,8 +25,10 @@
/// used across invocations of [_iterate].
final Uint32List _currentChunk;
- /// Messages with more than 2^53-1 bits are not supported. (This is the
- /// largest value that is representable on both JS and the Dart VM.)
+ /// Messages with more than 2^53-1 bits are not supported.
+ ///
+ /// This is the largest value that is precisely representable
+ /// on both JS and the Dart VM.
/// So the maximum length in bytes is (2^53-1)/8.
static const _maxMessageLengthInBytes = 0x0003ffffffffffff;
diff --git a/lib/src/md5.dart b/lib/src/md5.dart
index 9874011..fa7d8b3 100644
--- a/lib/src/md5.dart
+++ b/lib/src/md5.dart
@@ -27,8 +27,7 @@
/// **Warning**: MD5 has known collisions and should only be used when required
/// for backwards compatibility.
///
-/// Note that it's almost always easier to use [md5] rather than creating a new
-/// instance.
+/// Use the [md5] object to perform MD5 hashing.
class MD5 extends Hash {
@override
final int blockSize = 16 * bytesPerWord;
diff --git a/lib/src/sha256.dart b/lib/src/sha256.dart
index 6040d5e..27a8440 100644
--- a/lib/src/sha256.dart
+++ b/lib/src/sha256.dart
@@ -28,14 +28,14 @@
///
/// [rfc]: http://tools.ietf.org/html/rfc6234
///
-/// Note that it's almost always easier to use [sha256] rather than creating a
-/// new instance.
+/// Use the [sha256] object to perform SHA-256 hashing.
class Sha256 extends Hash {
@override
final int blockSize = 16 * bytesPerWord;
Sha256._();
+ @deprecated
Sha256 newInstance() => Sha256._();
@override
@@ -47,14 +47,15 @@
///
/// [rfc]: http://tools.ietf.org/html/rfc6234
///
-/// Note that it's almost always easier to use [sha224] rather than creating a
-/// new instance.
+///
+/// Use the [sha224] object to perform SHA-224 hashing.
class Sha224 extends Hash {
@override
final int blockSize = 16 * bytesPerWord;
Sha224._();
+ @deprecated
Sha224 newInstance() => Sha224._();
@override
diff --git a/lib/src/sha512.dart b/lib/src/sha512.dart
index 39e9595..fcb34fd 100644
--- a/lib/src/sha512.dart
+++ b/lib/src/sha512.dart
@@ -42,14 +42,14 @@
///
/// [rfc]: http://tools.ietf.org/html/rfc6234
///
-/// Note that it's almost always easier to use [sha384] rather than creating a
-/// new instance.
+/// Use the [sha384] object to perform SHA-384 hashing
class Sha384 extends Hash {
@override
final int blockSize = 32 * bytesPerWord;
const Sha384._();
+ @deprecated
Sha384 newInstance() => Sha384._();
@override
@@ -61,14 +61,14 @@
///
/// [rfc]: http://tools.ietf.org/html/rfc6234
///
-/// Note that it's almost always easier to use [sha512] rather than creating a
-/// new instance.
+/// Use the [sha512] object to perform SHA-512 hashing
class Sha512 extends Hash {
@override
final int blockSize = 32 * bytesPerWord;
const Sha512._();
+ @deprecated
Sha512 newInstance() => Sha512._();
@override
@@ -80,8 +80,7 @@
///
/// [FIPS]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
///
-/// Note that it's almost always easier to use [sha512224] rather than creating
-/// a new instance.
+/// Use the [sha512224] object to perform SHA-512/224 hashing
class _Sha512224 extends Hash {
@override
final int blockSize = 32 * bytesPerWord;
@@ -97,8 +96,7 @@
///
/// [FIPS]: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf
///
-/// Note that it's almost always easier to use [sha512256] rather than creating
-/// a new instance.
+/// Use the [sha512256] object to perform SHA-512/256 hashing
class _Sha512256 extends Hash {
@override
final int blockSize = 32 * bytesPerWord;
