[Dart 3.10] Document dot shorthands

examples/language/lib/shorthands/chain.dart

@@ -0,0 +1,10 @@
+void printLowerH() {
+  // #docregion chain
+  // .fromCharCode(72) resolves to the String "H",
+  // then the instance method .toLowerCase() is called on that String.
+  String lowerH = .fromCharCode(72).toLowerCase();
+  // Instead of String.fromCharCode(72).toLowerCase()
+
+  print(lowerH); // Output: h
+  // #enddocregion chain
+}

examples/language/lib/shorthands/constructors.dart

@@ -0,0 +1,19 @@
+class Point {
+  final double x, y;
+  const Point(this.x, this.y);
+  const Point.origin() : x = 0, y = 0; // Named constructor
+
+  // Factory constructor
+  factory Point.fromList(List<double> list) {
+    return Point(list[0], list[1]);
+  }
+}
+
+// Use dot shorthand syntax on a named constructor:
+Point origin = .origin(); // Instead of Point.origin()
+
+// Use dot shorthand syntax on a factory constructor:
+Point p1 = .fromList([1.0, 2.0]); // Instead of Point.fromList([1.0, 2.0])
+
+// Use dot shorthand syntax on a generic class constructor:
+List<int> intList = .filled(5, 0); // Instead of List.filled(5, 0)

examples/language/lib/shorthands/consts.dart

@@ -0,0 +1,17 @@
+enum Status { none, running, stopped, paused }
+
+class Point {
+  final double x, y;
+  const Point(this.x, this.y);
+  const Point.origin() : x = 0.0, y = 0.0;
+}
+
+// Use dot shorthand syntax for enum value:
+const Status defaultStatus = .running; // Instead of Status.running
+
+// Use dot shorthand syntax to invoke a const named constructor:
+const Point myOrigin = .origin(); // Instead of Point.origin()
+
+// Use dot shorthand syntax in a const collection literal:
+const List<Point> keyPoints = [.origin(), .new(1.0, 1.0)];
+// Instead of [Point.origin(), Point(1.0, 1.0)]

examples/language/lib/shorthands/enums.dart

@@ -0,0 +1,15 @@
+enum LogLevel { debug, info, warning, error }
+
+/// Returns the color code to use for the specified log [level].
+String colorCode(LogLevel level) {
+  // Use dot shorthand syntax for enum values in switch cases:
+  return switch (level) {
+    .debug => 'gray', // Instead of LogLevel.debug
+    .info => 'blue', // Instead of LogLevel.info
+    .warning => 'orange', // Instead of LogLevel.warning
+    .error => 'red', // Instead of LogLevel.error
+  };
+}
+
+// Example usage:
+String warnColor = colorCode(.warning); // Returns 'orange'

examples/language/lib/shorthands/equality.dart

@@ -0,0 +1,23 @@
+// ignore_for_file: dead_code
+enum Color { red, green, blue }
+
+// Use dot shorthand syntax for equality expressions:
+void allowedExamples() {
+  Color myColor = Color.red;
+  bool condition = true;
+
+  // OK: `myColor` is a `Color`, so `.green` is inferred as `Color.green`.
+  if (myColor == .green) {
+    print('The color is green.');
+  }
+
+  // OK: Works with `!=` as well.
+  if (myColor != .blue) {
+    print('The color is not blue.');
+  }
+
+  // OK: The context for the ternary is the variable `inferredColor`
+  // being assigned to, which has a type of `Color`.
+  Color inferredColor = condition ? .green : .blue;
+  print('Inferred color is $inferredColor');
+}

examples/language/lib/shorthands/equality_with_errors.dart

@@ -0,0 +1,28 @@
+// ignore_for_file: dead_code
+enum Color { red, green, blue }
+
+void notAllowedExamples() {
+  Color myColor = Color.red;
+  bool condition = true;
+
+  // ERROR: The shorthand must be on the right side of `==`.
+  // Dart's `==` operator is not symmetric for this feature.
+  // ignore: dot_shorthand_missing_context
+  if (.red == myColor) {
+    print('This will not compile.');
+  }
+
+  // ERROR: The right-hand side is a complex expression (a conditional expression),
+  // which is not a valid target for shorthand in a comparison.
+  // ignore: dot_shorthand_missing_context
+  if (myColor == (condition ? .green : .blue)) {
+    print('This will not compile.');
+  }
+
+  // ERROR: The type context is lost by casting `myColor` to `Object`.
+  // The compiler no longer knows that `.green` should refer to `Color.green`.
+  // ignore: dot_shorthand_undefined_member
+  if ((myColor as Object) == .green) {
+    print('This will not compile.');
+  }
+}

examples/language/lib/shorthands/expression_with_errors.dart

@@ -0,0 +1,13 @@
+class Logger {
+  static void log(String message) {
+    print(message);
+  }
+}
+
+void main() {
+  // ERROR: An expression statement can't begin with `.`.
+  // The compiler has no type context (like a variable assignment)
+  // to infer that `.log` should refer to `Logger.log`.
+  // ignore: dot_shorthand_undefined_member
+  .log('Hello');
+}

examples/language/lib/shorthands/intro.dart

@@ -0,0 +1,16 @@
+// Use dot shorthand syntax on enums:
+enum Status { none, running, stopped, paused }
+
+Status currentStatus = .running; // Instead of Status.running
+
+// Use dot shorthand syntax on a static method:
+int port = .parse('8080'); // Instead of int.parse('8080')
+
+// Uses dot shorthand syntax on a constructor:
+class Point {
+  final int x, y;
+  Point(this.x, this.y);
+  Point.origin() : x = 0, y = 0;
+}
+
+Point origin = .origin(); // Instead of Point.origin()

examples/language/lib/shorthands/static_members.dart

@@ -0,0 +1,5 @@
+// Use dot shorthand syntax to invoke a static method:
+int httpPort = .parse('80'); // Instead of int.parse('80')
+
+// Use dot shorthand syntax to access a static field or getter:
+BigInt bigIntZero = .zero; // Instead of BigInt.zero

examples/language/lib/shorthands/unnamed_constructors.dart

@@ -0,0 +1,43 @@
+// ignore_for_file: unused_field, unused_element
+
+// #docregion unnamed-before
+class _PageState extends State<Page> {
+  late final AnimationController _animationController = AnimationController(
+    vsync: this,
+  );
+  final ScrollController _scrollController = ScrollController();
+
+  final GlobalKey<ScaffoldMessengerState> scaffoldKey =
+      GlobalKey<ScaffoldMessengerState>();
+
+  Map<String, Map<String, bool>> properties = <String, Map<String, bool>>{};
+  // ...
+}
+// #enddocregion unnamed-before
+
+// #docregion unnamed-after
+// Use dot shorthand syntax for calling unnamed constructors:
+class _PageStateAfter extends State<Page> {
+  late final AnimationController _animationController = .new(vsync: this);
+  final ScrollController _scrollController = .new();
+  final GlobalKey<ScaffoldMessengerState> scaffoldKey = .new();
+  Map<String, Map<String, bool>> properties = .new();
+  // ...
+}
+// #enddocregion unnamed-after
+
+// Supporting classes for example.
+
+class State<T> {}
+
+class ScaffoldMessengerState {}
+
+class GlobalKey<T> {}
+
+class ScrollController {}
+
+class AnimationController {
+  AnimationController({State<Object>? vsync});
+}
+
+class Page {}

examples/language/pubspec.yaml

@@ -3,7 +3,7 @@ description: dart.dev example code.
 
 resolution: workspace
 environment:
-  sdk: ^3.9.0
+  sdk: ^3.10.0-0
 
 dependencies:
   charcode: ^1.4.0