[M] Change in dart/sdk[main]: Deprecate NullThrownError and CyclicInitializetionError.
Lasse Nielsen (Gerrit)
Attention is currently required from: Michael Thomsen.
Lasse Nielsen would like Michael Thomsen to review this change.
Deprecate NullThrownError and CyclicInitializetionError.
Both exceptions are used only in pre-null-safe code.
They can safely be removed when all code has been
migrated to null safety, and non-null-safe code is
no longer supported.
Change-Id: I13624d0da369c2241b8f6d66da01ea91bc0b45f4
---
M CHANGELOG.md
M sdk/lib/core/errors.dart
2 files changed, 79 insertions(+), 24 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e2b17a..f93a123 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -50,7 +50,7 @@
library-level documentation comments, and with this new feature, you don't
have to provide a unique name for each library directive. Instead, a name can
simply be omitted (see [#1073][]).
-
+
[#1073]: https://github.com/dart-lang/language/issues/1073
### Libraries
@@ -71,6 +71,8 @@
- Deprecated `RangeError.checkValidIndex` in favor of `IndexError.check`.
- Deprecated `IndexError` constructor in favor of `IndexError.withLength`
constructor.
+- Deprecated `NullThrownError` and `CyclicInitializationError`.
+ Neither error is thrown by null safe code.
[#49529]: https://github.com/dart-lang/sdk/issues/49529
[#24644]: https://github.com/dart-lang/sdk/issues/24644
diff --git a/sdk/lib/core/errors.dart b/sdk/lib/core/errors.dart
index b9641ad..ca269b7 100644
--- a/sdk/lib/core/errors.dart
+++ b/sdk/lib/core/errors.dart
@@ -13,11 +13,11 @@
/// or even with the wrong number of arguments,
/// or calling it at a time when it is not allowed.
///
-/// These are not errors that a caller should expect or catch -
+/// These are not errors that a caller should expect or catch —
/// if they occur, the program is erroneous,
/// and terminating the program may be the safest response.
///
-/// When deciding that a function throws an error,
+/// When deciding that a function should throw an error,
/// the conditions where it happens should be clearly described,
/// and they should be detectable and predictable,
/// so the programmer using the function can avoid triggering the error.
@@ -40,13 +40,14 @@
/// It may still throw,
/// but the caller will have to catch the thrown value,
/// effectively making it an alternative result rather than an error.
+/// If so, we consider the thrown object an *exception* rather than an error.
/// The thrown object can choose to implement [Exception]
/// to document that it represents an exceptional, but not erroneous,
/// occurrence, but being an [Exception] has no other effect
/// than documentation.
///
/// All non-`null` values can be thrown in Dart.
-/// Objects extending `Error` are handled specially:
+/// Objects *extending* the `Error` class are handled specially:
/// The first time they are thrown,
/// the stack trace at the throw point is recorded
/// and stored in the error object.
@@ -55,7 +56,8 @@
/// will not store the stack trace automatically.
///
/// Error objects are also used for system wide failures
-/// like stack overflow or an out-of-memory situation.
+/// like stack overflow or an out-of-memory situation,
+/// which the user is also not expected to catch or handle.
///
/// Since errors are not created to be caught,
/// there is no need for subclasses to distinguish the errors.
@@ -64,6 +66,8 @@
/// For example, the [String.contains] method will use a [RangeError]
/// if its `startIndex` isn't in the range `0..length`,
/// which is easily created by `RangeError.range(startIndex, 0, length)`.
+/// Catching specific subclasses of [Error] is not intended,
+/// and shouldn't happen outside of testing your own code.
@pragma('flutter:keep-to-string-in-subtypes')
class Error {
Error(); // Prevent use as mixin.
@@ -136,23 +140,39 @@
}
/// Error thrown by the runtime system when a dynamic type error happens.
-class TypeError extends Error {}
+abstract class TypeError extends Error {}
/// Error thrown by the runtime system when a cast operation fails.
@Deprecated("Use TypeError instead")
-class CastError extends Error {}
+abstract class CastError extends Error {}
/// Error thrown when attempting to throw `null`.
///
/// In null safe code, you are statically disallowed from throwing `null`,
/// so this error will go away when non-null safe code stops being supported.
-class NullThrownError extends Error {
+@Deprecated("Use TypeError instead")
+class NullThrownError extends Error implements TypeError {
@pragma("vm:entry-point")
NullThrownError();
String toString() => "Throw of null.";
}
/// Error thrown when a function is passed an unacceptable argument.
+///
+/// The method should document restrictions on the arguments it accepts,
+/// for example if an integer argument must be non-nullable,
+/// a string argument must be non-empty,
+/// or a `dynamic`-typed argument must actually have one of a few accepted
+/// types.
+///
+/// The user should be able to predict which arguments will cause an
+/// error to be throw, and avoid calling with those.
+///
+/// It's almost always a good idea to provide the unacceptable value
+/// as part of the error, to help the user figure out what vent wrong,
+/// so the [ArgumentError.value] constructor is the preferred constructor.
+/// Use [ArgumentError.new] only when the value cannot be provided for some
+/// reason.
class ArgumentError extends Error {
/// Whether value was provided.
final bool _hasValue;
@@ -173,9 +193,9 @@
/// of a message.
///
/// If [name] is provided, it should be the name of the parameter
- /// which was invalid.
+ /// which received an invalid argument.
///
- /// Consider using [ArgumentError.value] instead to retain and document the
+ /// Prefer using [ArgumentError.value] instead to retain and document the
/// invalid value as well.
@pragma("vm:entry-point")
ArgumentError([this.message, @Since("2.14") this.name])
@@ -211,10 +231,8 @@
///
/// Returns the [argument] if it is not null.
@Since("2.1")
- static T checkNotNull<@Since("2.8") T>(T? argument, [String? name]) {
- if (argument == null) throw ArgumentError.notNull(name);
- return argument;
- }
+ static T checkNotNull<@Since("2.8") T>(T? argument, [String? name]) =>
+ argument ?? (throw ArgumentError.notNull(name));
// Helper functions for toString overridden in subclasses.
String get _errorName => "Invalid argument${!_hasValue ? "(s)" : ""}";
@@ -234,7 +252,7 @@
}
}
-/// Error thrown due to a value being outside a valid range.
+/// Error thrown due to an argument value being outside an accepted range.
class RangeError extends ArgumentError {
/// The minimum value that [value] is allowed to assume.
final num? start;
@@ -242,6 +260,8 @@
/// The maximum value that [value] is allowed to assume.
final num? end;
+ num? get invalidValue => super.invalidValue;
+
// TODO(lrn): This constructor should be called only with string values.
// It currently isn't in all cases.
/// Create a new [RangeError] with the given [message].
@@ -411,11 +431,16 @@
/// and the invalid index itself.
class IndexError extends ArgumentError implements RangeError {
/// The indexable object that [invalidValue] was not a valid index into.
+ ///
+ /// Can be, for example, a [List] or [String],
+ /// which both have index based operations..
final Object? indexable;
/// The length of [indexable] at the time of the error.
final int length;
+ int get invalidValue => super.invalidValue;
+
/// Creates a new [IndexError] stating that [invalidValue] is not a valid index
/// into [indexable].
///
@@ -496,7 +521,7 @@
/// control reached the end of a switch case (except the last case
/// of a switch) without meeting a `break` or other control flow operators.
/// That kind of fall-through was made a compile-time error Dart 2.0,
-/// so this error no longer thrown.
+/// so this error is no longer thrown.
@Deprecated("No longer relevant in Dart 2.0")
class FallThroughError extends Error {
FallThroughError();
@@ -518,7 +543,15 @@
external String toString();
}
-/// Error thrown by the default implementation of `noSuchMethod` on [Object].
+/// Error thrown when a particular method invocation is not possible.
+///
+/// This error is thrown by the default implementation of `noSuchMethod`
+/// on [Object], which is the default behavior of a failed dynamic
+/// invocation.
+///
+/// The error is also thrown in other cases where an object
+/// does not support a requested operation, but where the failed operation
+/// does not trigger a call to [Object.noSuchMethod].
class NoSuchMethodError extends Error {
/// Creates a [NoSuchMethodError] corresponding to a failed method call.
///
@@ -562,6 +595,8 @@
///
/// This [Error] is thrown when an instance cannot implement one of the methods
/// in its signature.
+/// For example, it's used by unmodifiable versions of collections,
+/// when someone calls a modifying method.
@pragma("vm:entry-point")
class UnsupportedError extends Error {
final String? message;
@@ -593,11 +628,12 @@
///
/// Should be used when this particular object is currently in a state
/// which doesn't support the requested operation, but other similar
-/// objects might, or the object might change its state to one which
-/// supports the operation.
+/// objects might, or the object itself can later change its state
+/// to one which supports the operation.
+///
/// Example: Asking for `list.first` on a currently empty list.
-/// If the operation is never supported, consider using
-/// [UnsupportedError] instead.
+/// If the operation is never supported by this object or class,
+/// consider using [UnsupportedError] instead.
///
/// This is a generic error used for a variety of different erroneous
/// actions. The message should be descriptive.
@@ -647,9 +683,12 @@
/// Error thrown when a lazily initialized variable cannot be initialized.
///
-/// This is no longer used in null safe Dart code and is replaced by late
-/// variables and `LateInitializationError`.
-// TODO: Deprecate?
+/// Cyclic dependencies are no longer detected at runtime in null safe code.
+/// Such code will fail in other ways instead,
+/// possibly with a [StackOverflowError].
+///
+/// Will be removed when support for non-null-safe code is discontinued.
+@Deprecated("Use Error instead")
class CyclicInitializationError extends Error {
final String? variableName;
@pragma("vm:entry-point")
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Lasse Nielsen (Gerrit)
Attention is currently required from: Michael Thomsen.
CBuild (Gerrit)
Attention is currently required from: Lasse Nielsen, Michael Thomsen.
go/dart-cbuild result: FAILURE (REGRESSIONS DETECTED)
Details: https://goto.google.com/dart-cbuild/find/7e02a5dcb5c1e233a60e0429d6e00f7886607f07
Bugs: go/dart-cbuild-bug/7e02a5dcb5c1e233a60e0429d6e00f7886607f07
CBuild (Gerrit)
Attention is currently required from: Lasse Nielsen, Michael Thomsen.
go/dart-cbuild result: SUCCESS
Details: https://goto.google.com/dart-cbuild/find/fa7824e6b21f1a814d3c963fe5ef1213113da337
Michael Thomsen (Gerrit)
Attention is currently required from: Lasse Nielsen.
1 comment:
File sdk/lib/core/errors.dart:
Patch Set #3, Line 436:
/// which both have index based operations..Double period
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Lasse Nielsen (Gerrit)
Attention is currently required from: Michael Thomsen.
1 comment:
File sdk/lib/core/errors.dart:
Patch Set #3, Line 436:
/// which both have index based operations..Double period
Done
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Lasse Nielsen (Gerrit)
Attention is currently required from: Michael Thomsen.
Patch set 4:Auto-Submit +1Commit-Queue +1
Michael Thomsen (Gerrit)
Attention is currently required from: Lasse Nielsen.
Patch set 4:Code-Review +1Commit-Queue +2
CBuild (Gerrit)
Attention is currently required from: Lasse Nielsen.
go/dart-cbuild result: SUCCESS
Details: https://goto.google.com/dart-cbuild/find/9ef0f6ec849d72d00c458280930167d5a7064cf1
Commit Queue (Gerrit)
Commit Queue submitted this change.
Deprecate NullThrownError and CyclicInitializetionError.
Both exceptions are used only in pre-null-safe code.
They can safely be removed when all code has been
migrated to null safety, and non-null-safe code is
no longer supported.
Change-Id: I13624d0da369c2241b8f6d66da01ea91bc0b45f4
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/271920
Reviewed-by: Michael Thomsen <m...@google.com>
Commit-Queue: Lasse Nielsen <l...@google.com>
Auto-Submit: Lasse Nielsen <l...@google.com>
Commit-Queue: Michael Thomsen <m...@google.com>
---
M CHANGELOG.md
M sdk/lib/core/errors.dart
2 files changed, 82 insertions(+), 22 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3e2b17a..f93a123 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -50,7 +50,7 @@
library-level documentation comments, and with this new feature, you don't
have to provide a unique name for each library directive. Instead, a name can
simply be omitted (see [#1073][]).
-
+
[#1073]: https://github.com/dart-lang/language/issues/1073
### Libraries
@@ -71,6 +71,8 @@
- Deprecated `RangeError.checkValidIndex` in favor of `IndexError.check`.
- Deprecated `IndexError` constructor in favor of `IndexError.withLength`
constructor.
+- Deprecated `NullThrownError` and `CyclicInitializationError`.
+ Neither error is thrown by null safe code.
[#49529]: https://github.com/dart-lang/sdk/issues/49529
[#24644]: https://github.com/dart-lang/sdk/issues/24644
diff --git a/sdk/lib/core/errors.dart b/sdk/lib/core/errors.dart
index b9641ad..1cf9494 100644@@ -146,13 +150,29 @@+ /// which both have index based operations.To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
CBuild (Gerrit)
go/dart-cbuild result: SUCCESS
Details: https://goto.google.com/dart-cbuild/find/b7b45eb42189470c30d729528f9564a30baf5175
Siva Annamalai (Gerrit)
1 comment:
Patchset:
This CL apprears to have broken the flutter/flutter builds, see https://logs.chromium.org/logs/flutter/buildbucket/cr-buildbucket/8796236498075545489/+/u/Analyze/analyze/test_stdout
I am going to revert this CL, we need to forward migrate the flutter/flutter code so that it doesn't use NullThrownError before landing this CL.
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Lasse Nielsen (Gerrit)
1 comment:
Patchset:
This CL apprears to have broken the flutter/flutter builds, see https://logs.chromium. […]
We *really* need to stop deprecation warnings from breaking builds.
Deprecating something should be a no-op, informing people that they yet have time to migrate their code. Making it an immediate error is precisely the opposite of the intention of deprecation. If deprecating is as breaking as removing the feature, we lose the benefit of having deprecation to begin with.But for now, I'll look into migrating flutter off `NullThrownError`.
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Siva Annamalai (Gerrit)
Lasse Nielsen has uploaded this change for review.
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.
Siva Annamalai (Gerrit)
1 comment:
Patchset:
We *really* need to stop deprecation warnings from breaking builds. […]
I think Flutter seems to have this policy, maybe @ia...@google.com could elaborate on why.
Flutter seems to annotate individually when they need to work around build breakages
e.g: // ignore: deprecated_member_use should be added back to resolve this.
I think a forward workaround has been submitted for this here https://github.com/flutter/flutter/pull/116135
so we are probably good for now.
To view, visit change 271920. To unsubscribe, or for help writing mail filters, visit settings.