From 9849e58cd5498702738268f731d0d43c3857da90 Mon Sep 17 00:00:00 2001 From: Parker Lougheed Date: Thu, 28 Dec 2023 14:18:38 -0600 Subject: [PATCH] Accuracy adjustment of non-null assertion operator (#5437) We haven't come to a conclusion yet, and I'd like to leave that conversation on hold, but we should at least improve the from status quo which is currently more inaccurate and inconsistent with the [null assert pattern type](https://dart.dev/language/pattern-types#null-assert). --- src/codelabs/null-safety.md | 9 ++++++--- src/effective-dart/usage.md | 2 +- src/guides/whats-new.md | 2 +- src/language/operators.md | 2 +- src/null-safety/understanding-null-safety.md | 5 +++-- 5 files changed, 12 insertions(+), 8 deletions(-) diff --git a/src/codelabs/null-safety.md b/src/codelabs/null-safety.md index 519394f435..fc67d1f6b4 100644 --- a/src/codelabs/null-safety.md +++ b/src/codelabs/null-safety.md @@ -89,10 +89,11 @@ void main() { } ``` -## The null assertion operator (!) + +## The non-null assertion operator (!) If you're sure an expression with a nullable type doesn't equal `null`, -you can use the [null assertion operator](/null-safety/understanding-null-safety#null-assertion-operator) +you can use the [non-null assertion operator][] (`!`) to make Dart treat it as non-nullable. By adding `!` after the expression, you assert two conditions to Dart about the expression: @@ -106,6 +107,8 @@ you assert two conditions to Dart about the expression: Don't use it unless you have no doubt the expression can't equal `null`. {{site.alert.end}} +[non-null assertion operator]: /null-safety/understanding-null-safety#non-null-assertion-operator + ### Exercise: Null assertion In the following code, try adding exclamation points to correct the @@ -139,7 +142,7 @@ You can also use null-aware operators to handle nullable values. Sometimes the flow of the program tells you that the value of an expression cannot be `null`. To force Dart to treat that expression as non-nullable, -add the [null assertion operator](#the-null-assertion-operator-) (`!`). +add the [non-null assertion operator](#the-non-null-assertion-operator-) (`!`). If the value does equal `null`, using this operator throws an exception. To handle potential `null` values, use the conditional property access diff --git a/src/effective-dart/usage.md b/src/effective-dart/usage.md index db2375008d..91e810b7a4 100644 --- a/src/effective-dart/usage.md +++ b/src/effective-dart/usage.md @@ -416,7 +416,7 @@ value. Sometimes it's best to simply [use `!`][] on the field. [private]: /effective-dart/design#prefer-making-declarations-private [final]: /effective-dart/design#prefer-making-fields-and-top-level-variables-final [`final`]: /effective-dart/usage#do-follow-a-consistent-rule-for-var-and-final-on-local-variables -[use `!`]: /null-safety/understanding-null-safety#null-assertion-operator +[use `!`]: /null-safety/understanding-null-safety#non-null-assertion-operator ## Strings diff --git a/src/guides/whats-new.md b/src/guides/whats-new.md index 1dde22b6f2..5f24f2f689 100644 --- a/src/guides/whats-new.md +++ b/src/guides/whats-new.md @@ -454,7 +454,7 @@ we made the following changes to this site: as the underlying compilers of tools like [`dart compile js`][] and [`webdev`][]. * Increased documentation coverage of null safety: - * Documented the null assertion operator (`!`) as part of + * Documented the non-null assertion operator (`!`) as part of the [Other operators][] section of the language tour. * Migrated the [Low-level HTML tutorials][] to support null safety and discuss how to interact with web APIs while using it. diff --git a/src/language/operators.md b/src/language/operators.md index 3b7996f854..b6ab052758 100644 --- a/src/language/operators.md +++ b/src/language/operators.md @@ -509,7 +509,7 @@ You've seen most of the remaining operators in other examples: | `?[]` | Conditional subscript access | Like `[]`, but the leftmost operand can be null; example: `fooList?[1]` passes the int `1` to `fooList` to access the element at index `1` unless `fooList` is null (in which case the expression evaluates to null) | `.` | Member access | Refers to a property of an expression; example: `foo.bar` selects property `bar` from expression `foo` | `?.` | Conditional member access | Like `.`, but the leftmost operand can be null; example: `foo?.bar` selects property `bar` from expression `foo` unless `foo` is null (in which case the value of `foo?.bar` is null) -| `!` | Null assertion operator | Casts an expression to its underlying non-nullable type, throwing a runtime exception if the cast fails; example: `foo!.bar` asserts `foo` is non-null and selects the property `bar`, unless `foo` is null in which case a runtime exception is thrown +| `!` | Non-null assertion operator | Casts an expression to its underlying non-nullable type, throwing a runtime exception if the cast fails; example: `foo!.bar` asserts `foo` is non-null and selects the property `bar`, unless `foo` is null in which case a runtime exception is thrown {:.table .table-striped} For more information about the `.`, `?.`, and `..` operators, see diff --git a/src/null-safety/understanding-null-safety.md b/src/null-safety/understanding-null-safety.md index 2754313bb2..eb844dcad8 100644 --- a/src/null-safety/understanding-null-safety.md +++ b/src/null-safety/understanding-null-safety.md @@ -692,7 +692,7 @@ String makeCommand(String executable, [List? arguments]) { The language is also smarter about what kinds of expressions cause promotion. An explicit `== null` or `!= null` of course works. But explicit casts using `as`, or assignments, or the postfix `!` operator -(which we'll cover [later on](#null-assertion-operator)) also cause +(which we'll cover [later on](#non-null-assertion-operator)) also cause promotion. The general goal is that if the code is dynamically correct and it's reasonable to figure that out statically, the analysis should be clever enough to do so. @@ -873,7 +873,8 @@ There isn't a null-aware function call operator, but you can write: function?.call(arg1, arg2); ``` -### Null assertion operator + +### Non-null assertion operator The great thing about using flow analysis to move a nullable variable to the non-nullable side of the world is that doing so is provably safe. You get to