add null-aware operators to the language tour

src/site/docs/dart-up-and-running/ch02.markdown

 ---
 layout: book
 title: "A Tour of the Dart Language"
 subsite: "Dart Up and Running"
 description: "Read Chapter 2, A Tour of the Dart Language of Dart (from Dart: Up and Running, published by O'Reilly)."
 prev-chapter: ch01.html
 prev-chapter-title: "Quick Start"
 next-chapter: ch03.html
 next-chapter-title: "Library Tour"
 ---
@@ skipping 719 matching lines @@
 {% endprettify %}
 
 The <code>=> <em>expr</em>;</code> syntax is a shorthand for
 <code>{ return <em>expr</em>;}</code>. In the `printNumber()` function, the expression is the
 call to the top-level `print()` function.
 
 <aside class="alert alert-info" markdown="1">
 **Note:**
 Only an *expression*—not a *statement*—can appear between the arrow
 (=\>) and the semicolon (;). For example, you can’t put an [if
-statement](#if-and-else) there, but you can use a [conditional (`?:`)
-expression](#other-operators).
+statement](#if-and-else) there, but you can use a [conditional
+expression](#conditional-expressions).
 </aside>
 
 Here’s an example of calling a function:
 
 <!-- ch02/function_calling.dart -->
 {% prettify dart %}
 printNumber(123);
 {% endprettify %}
 
 A function can have two types of parameters: required and optional. The
@@ skipping 293 matching lines @@
 
 ## Operators {#operators}
 
 Dart defines the operators shown in the following table.
 You can override many of these operators, as described in
 [Overridable operators](#overridable-operators).
 
 |--------------------------+------------------------------------------------|
 |Description               | Operator                                       |
 |--------------------------|------------------------------------------------|
-| unary postfix            | <code><em>expr</em>++</code>    <code><em>expr</em>--</code>    `()`    `[]`    `.`             |
+| unary postfix            | <code><em>expr</em>++</code>    <code><em>expr</em>--</code>    `()`    `[]`    `.`    `?.` |
 | unary prefix             | <code>-<em>expr</em></code>    <code>!<em>expr</em></code>    <code>~<em>expr</em></code>    <code>++<em>expr</em></code>    <code>--<em>expr</em></code>   |
 | multiplicative           | `*`    `/`    `%`    `~/`                      |
 | additive                 | `+`    `-`                                     |
 | shift                    | `<<`    `>>`                                   |
 | bitwise AND              | `&`                                            |
 | bitwise XOR              | `^`                                            |
 | bitwise OR               | `|`                                            |
-| relational&nbsp;and&nbsp;type&nbsp;test | `>=`    `>`    `<=`    `<`    `as`    `is`    `is!`      |
+| relational&nbsp;and&nbsp;type&nbsp;test | `>=`    `>`    `<=`    `<`    `as`    `is`    `is!` |
 | equality                 | `==`    `!=`                                   |
 | logical AND              | `&&`                                           |
 | logical OR               | `||`                                           |
-| conditional              | <code><em>expr1</em> ? <em>expr2</em> : <em>expr3</em></code>        |
+| if null                  | `??`                                           |
+| conditional              | <code><em>expr1</em> ? <em>expr2</em> : <em>expr3</em></code> |
 | cascade                  | `..`                                           |
-| assignment               | `=`    `*=`    `/=`    `~/=`    `%=`    `+=`    `-=`    `<<=`    `>>=`    `&=`    `^=`    `|=`                 |
+| assignment               | `=`    `*=`    `/=`    `~/=`    `%=`    `+=`    `-=`    `<<=`    `>>=`    `&=`    `^=`    `|=`    `??=` |
 {:.table .table-striped}
 
 When you use operators, you create expressions. Here are some examples
 of operator expressions:
 
 <!-- TODO: write test for this -->
 {% prettify dart %}
 a++
 a + b
 a = b
 a == b
 a ? b: c
 a is T
 {% endprettify %}
 
-In the preceding operator table,
+In the [operator table](#operators),
 each operator has higher precedence than the operators in the rows
 that follow it. For example, the multiplicative operator `%` has higher
 precedence than (and thus executes before) the equality operator `==`,
 which has higher precedence than the logical AND operator `&&`. That
 precedence means that the following two lines of code execute the same
 way:
 
 <!-- ch02/precedence.dart -->
 {% prettify dart %}
 // 1: Parens improve readability.
@@ skipping 165 matching lines @@
 **Note:**
 The code isn’t equivalent. If `emp` is null or not a Person, the
 first example (with `is`) does nothing; the second (with `as`) throws
 an exception.
 </aside>
 
 
 ### Assignment operators {#assignment-operators}
 {:.no_toc}
 
-As you’ve already seen, you assign values using the `=` operator. You
-can also use compound assignment operators such as `+=`, which combine
+As you’ve already seen, you can assign values using the `=` operator.
+To assign only if the assigned-to variable is null,
+use the `??=` operator.
+
+{% prettify dart %}
+a = value;   // Assign value to a
+b ??= value; // If b is null, assign value to b;
+             // otherwise, b stays the same
+{% endprettify %}
+
+{% include null-aware-1-12.html %}
+
+{% comment %}
+<!-- embed a dartpad when we can hide code -->
+https://gist.github.com/9de887c4daf76d39e524
+https://dartpad.dartlang.org/9de887c4daf76d39e524
+{% endcomment %}
+
+Compound assignment operators such as `+=` combine
 an operation with an assignment.
 
 | `=`  | `–=` | `/=`  | `%=`  | `>>=` | `^=`
 | `+=` | `*=` | `~/=` | `<<=` | `&=`  | `|=`
 {:.table}
 
 Here’s how compound assignment operators work:
 
 |-----------+----------------------+-----------------------|
 |           | Compound assignment  | Equivalent expression |
 |-----------+----------------------+-----------------------|
 |**For an operator <em>op</em>:** | <code>a <em>op</em>= b</code> | <code>a = a <em>op</em> b</code>
 |**Example:**                     |`a += b`                       | `a = a + b`
 {:.table}
 
-The following example uses both assignment and compound assignment
+The following example uses assignment and compound assignment
 operators:
 
 <!-- ch02/op_assign.dart -->
 {% prettify dart %}
 var a = 2;           // Assign using =
 a *= 3;              // Assign and multiply: a = a * 3
 assert(a == 6);
 {% endprettify %}
 
 
@@ skipping 47 matching lines @@
 
 assert((value & bitmask)  == 0x02);  // AND
 assert((value & ~bitmask) == 0x20);  // AND NOT
 assert((value | bitmask)  == 0x2f);  // OR
 assert((value ^ bitmask)  == 0x2d);  // XOR
 assert((value << 4)       == 0x220); // Shift left
 assert((value >> 4)       == 0x02);  // Shift right
 {% endprettify %}
 
 
+### Conditional expressions {#conditional-expressions}
+{:.no_toc}
+
+Dart has two operators that let you concisely evaluate expressions
+that might otherwise require [if-else](#if-and-else) statements:
+
+<code><em>condition</em> ? <em>expr1</em> : <em>expr2</em>
+: If _condition_ is true, evaluates _expr1_ (and returns its value);
+  otherwise, evaluates and returns the value of _expr2_.
+
+<code><em>expr1</em> ?? <em>expr2</em></code>
+: If _expr1_ is non-null, returns its value;
+  otherwise, evaluates and returns the value of _expr2_.
+
+{% include null-aware-1-12.html %}
+
+When you need to assign a value
+based on a boolean expression,
+consider using `?:`.
+
+<!-- ch03/mirrors.dart -->
+{% prettify dart %}
+var finalStatus = m.isFinal ? 'final' : 'not final';
+{% endprettify %}
+
+If the boolean expression tests for null,
+consider using `??`.
+
+{% prettify dart %}
+String toString() => msg ?? super.toString();
+{% endprettify %}
+
+The previous example could have been written at least two other ways,
+but not as succinctly:
+
+{% comment %}
+https://dartpad.dartlang.org/f2c8d82ce5d0dd533fe2
+https://gist.github.com/f2c8d82ce5d0dd533fe2
+{% endcomment %}
+
+{% prettify dart %}
+// Slightly longer version uses ?: operator.
+String toString() => msg == null ? super.toString() : msg;
+
+// Very long version uses if-else statement.
+String toString() {
+  if (msg == null) {
+    return super.toString();
+  } else {
+    return msg;
+  }
+}
+{% endprettify %}
+
 ### Other operators {#other-operators}
 {:.no_toc}
 
-A few operators remain, most of which you’ve already seen in other
-examples.
+You've seen most of the remaining operators in other examples:
 
 |----------+-------------------------------------------|
-| Operator | Name              |              Meaning                                   |
-|-----------+-------------------------------------------|
+| Operator | Name                 |          Meaning   |
+|-----------+------------------------------------------|
 | `()`     | Function application | Represents a function call
 | `[]`     | List access          | Refers to the value at the specified index in the list
-| <code><em>expr1</em> ? <em>expr2</em> : <em>expr3</em> | Conditional | If _expr1_ is true, executes _expr2_; otherwise, executes _expr3_
 | `.`      | 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)
 | `..`     | Cascade              | Allows you to perform multiple operations on the members of a single object; described in [Classes](#classes)
 {:.table .table-striped}
 
+For more information about the `.`, `?.`, and `..` operators, see
+[Classes](#classes).
+
 
 ## Control flow statements {#control-flow-statements}
 
 You can control the flow of your Dart code using any of the following:
 
 -   `if` and `else`
 
 -   `for` loops
 
 -   `while` and `do`-`while` loops
 
 -   `break` and `continue`
 
 -   `switch` and `case`
 
 -   `assert`
 
 You can also affect the control flow using `try-catch` and `throw`, as
 explained in [Exceptions](#exceptions).
 
 
 ### If and else {#if-and-else}
 {:.no_toc}
 
 Dart supports `if` statements with optional `else` statements, as the
-next sample shows. Also see conditional expressions (?:), which are
-covered in [Other operators](#other-operators).
+next sample shows. Also see [conditional expressions](#conditional-expressions).
 
 <!-- ch02/flow_if_else.dart -->
 {% prettify dart %}
 if (isRaining()) {
   you.bringRainCoat();
 } else if (isSnowing()) {
   you.wearJacket();
 } else {
   car.putTopDown();
 }
@@ skipping 388 matching lines @@
 
 // Create a Point using Point.fromJson().
 var p2 = new Point.fromJson(jsonData);
 {% endprettify %}
 
 Objects have *members* consisting of functions and data (*methods* and
 *instance variables*, respectively). When you call a method, you *invoke*
 it on an object: the method has access to that object’s functions and
 data.
 
-Use a dot (.) to refer to an instance variable or method:
+Use a dot (`.`) to refer to an instance variable or method:
 
 <!-- ch02/object_classes.dart -->
 {% prettify dart %}
 var p = new Point(2, 2);
 
 // Set the value of the instance variable y.
 p.y = 3;
 
 // Get the value of y.
 assert(p.y == 3);
 
 // Invoke distanceTo() on p.
 num distance = p.distanceTo(new Point(4, 4));
 {% endprettify %}
 
+Use `?.` instead of `.` to avoid an exception
+when the leftmost operand is null:
+
+{% comment %}
+https://dartpad.dartlang.org/0cb25997742ed5382e4a
+https://gist.github.com/0cb25997742ed5382e4a
+{% endcomment %}
+
+{% prettify dart %}
+// If p is non-null, set its y value to 4.
+p?.y = 4;
+{% endprettify %}
+
+{% include null-aware-1-12.html %}
+
 Use the cascade operator (..) when you want to perform a series of
 operations on the members of a single object:
 
 <!-- ch02/cascade_operator/web/web_app.dart -->
 {% prettify dart %}
 querySelector('#button') // Get an object.
-    ..text = 'Confirm'   // Use its members.
-    ..classes.add('important')
-    ..onClick.listen((e) => window.alert('Confirmed!'));
+  ..text = 'Confirm'   // Use its members.
+  ..classes.add('important')
+  ..onClick.listen((e) => window.alert('Confirmed!'));
 {% endprettify %}
 
 Some classes provide constant constructors. To create a compile-time
 constant using a constant constructor, use `const` instead of `new`:
 
 <!-- ch02/object_classes.dart -->
 {% prettify dart %}
 var p = const ImmutablePoint(2, 2);
 {% endprettify %}
 
@@ skipping 1695 matching lines @@
 This chapter summarized the commonly used features in the Dart language.
 More features are being implemented, but we expect that they won’t break
 existing code. For more information, see the [Dart Language
 Specification](/docs/spec/) and
 [articles](/articles/) such as [Idiomatic
 Dart.](/articles/idiomatic-dart/)
 
 
 <hr>
 {% include book-nav.html %}