Version 2.12.0-218.0.dev
Merge commit 'fe7efd5606e3fd93c10e7fc6f0536b0e331364b7' into 'dev'
diff --git a/pkg/front_end/testcases/extensions/annotations.dart.strong.expect b/pkg/front_end/testcases/extensions/annotations.dart.strong.expect
index 0ff4213..ac0bdc2 100644
--- a/pkg/front_end/testcases/extensions/annotations.dart.strong.expect
+++ b/pkg/front_end/testcases/extensions/annotations.dart.strong.expect
@@ -45,4 +45,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotations.dart:
-- pragma._ (from org-dartlang-sdk:///sdk/lib/core/annotations.dart:193:9)
+- pragma._ (from org-dartlang-sdk:///sdk/lib/core/annotations.dart:188:9)
diff --git a/pkg/front_end/testcases/extensions/annotations.dart.strong.transformed.expect b/pkg/front_end/testcases/extensions/annotations.dart.strong.transformed.expect
index 0ff4213..ac0bdc2 100644
--- a/pkg/front_end/testcases/extensions/annotations.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/extensions/annotations.dart.strong.transformed.expect
@@ -45,4 +45,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotations.dart:
-- pragma._ (from org-dartlang-sdk:///sdk/lib/core/annotations.dart:193:9)
+- pragma._ (from org-dartlang-sdk:///sdk/lib/core/annotations.dart:188:9)
diff --git a/pkg/front_end/testcases/general/DeltaBlue.dart.strong.expect b/pkg/front_end/testcases/general/DeltaBlue.dart.strong.expect
index e101f55..9e26317 100644
--- a/pkg/front_end/testcases/general/DeltaBlue.dart.strong.expect
+++ b/pkg/front_end/testcases/general/DeltaBlue.dart.strong.expect
@@ -538,4 +538,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///DeltaBlue.dart:
- Strength. (from org-dartlang-testcase:///DeltaBlue.dart:59:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/DeltaBlue.dart.strong.transformed.expect b/pkg/front_end/testcases/general/DeltaBlue.dart.strong.transformed.expect
index d6e2870..a21d5791 100644
--- a/pkg/front_end/testcases/general/DeltaBlue.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/DeltaBlue.dart.strong.transformed.expect
@@ -538,4 +538,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///DeltaBlue.dart:
- Strength. (from org-dartlang-testcase:///DeltaBlue.dart:59:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.expect b/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.expect
index 0ca7e54..e27f5c8 100644
--- a/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.expect
+++ b/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.expect
@@ -64,5 +64,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_on_enum_values.dart:
- Foo. (from org-dartlang-testcase:///annotation_on_enum_values.dart:15:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Fisk.fisk (from org-dartlang-testcase:///annotation_on_enum_values.dart:12:9)
diff --git a/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.transformed.expect b/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.transformed.expect
index 0ca7e54..e27f5c8 100644
--- a/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/annotation_on_enum_values.dart.strong.transformed.expect
@@ -64,5 +64,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_on_enum_values.dart:
- Foo. (from org-dartlang-testcase:///annotation_on_enum_values.dart:15:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Fisk.fisk (from org-dartlang-testcase:///annotation_on_enum_values.dart:12:9)
diff --git a/pkg/front_end/testcases/general/annotation_top.dart.strong.expect b/pkg/front_end/testcases/general/annotation_top.dart.strong.expect
index 30c7443..b8fa4b8 100644
--- a/pkg/front_end/testcases/general/annotation_top.dart.strong.expect
+++ b/pkg/front_end/testcases/general/annotation_top.dart.strong.expect
@@ -61,5 +61,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_top.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- A. (from org-dartlang-testcase:///annotation_top.dart:12:9)
diff --git a/pkg/front_end/testcases/general/annotation_top.dart.strong.transformed.expect b/pkg/front_end/testcases/general/annotation_top.dart.strong.transformed.expect
index 30c7443..b8fa4b8 100644
--- a/pkg/front_end/testcases/general/annotation_top.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/annotation_top.dart.strong.transformed.expect
@@ -61,5 +61,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_top.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- A. (from org-dartlang-testcase:///annotation_top.dart:12:9)
diff --git a/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.expect b/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.expect
index 3b25c96..de080e6 100644
--- a/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.expect
+++ b/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.expect
@@ -65,5 +65,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_variable_declaration.dart:
- Bar. (from org-dartlang-testcase:///annotation_variable_declaration.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named (from org-dartlang-testcase:///annotation_variable_declaration.dart:9:9)
diff --git a/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.transformed.expect b/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.transformed.expect
index 3b25c96..de080e6 100644
--- a/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/annotation_variable_declaration.dart.strong.transformed.expect
@@ -65,5 +65,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_variable_declaration.dart:
- Bar. (from org-dartlang-testcase:///annotation_variable_declaration.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named (from org-dartlang-testcase:///annotation_variable_declaration.dart:9:9)
diff --git a/pkg/front_end/testcases/general/bug33099.dart.strong.expect b/pkg/front_end/testcases/general/bug33099.dart.strong.expect
index 4366e5c..2f8e660 100644
--- a/pkg/front_end/testcases/general/bug33099.dart.strong.expect
+++ b/pkg/front_end/testcases/general/bug33099.dart.strong.expect
@@ -89,4 +89,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///bug33099.dart:
- _FailingTest. (from org-dartlang-testcase:///bug33099.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/bug33099.dart.strong.transformed.expect b/pkg/front_end/testcases/general/bug33099.dart.strong.transformed.expect
index 9b8d3f4..6f4fe0e 100644
--- a/pkg/front_end/testcases/general/bug33099.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/bug33099.dart.strong.transformed.expect
@@ -93,4 +93,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///bug33099.dart:
- _FailingTest. (from org-dartlang-testcase:///bug33099.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/constants/circularity.dart.strong.expect b/pkg/front_end/testcases/general/constants/circularity.dart.strong.expect
index 32e7493..adecbb6 100644
--- a/pkg/front_end/testcases/general/constants/circularity.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/circularity.dart.strong.expect
@@ -137,7 +137,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///circularity.dart:
- Class1. (from org-dartlang-testcase:///circularity.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class2. (from org-dartlang-testcase:///circularity.dart:21:9)
- Class3. (from org-dartlang-testcase:///circularity.dart:29:9)
- Class4. (from org-dartlang-testcase:///circularity.dart:37:9)
diff --git a/pkg/front_end/testcases/general/constants/circularity.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/circularity.dart.strong.transformed.expect
index 32e7493..adecbb6 100644
--- a/pkg/front_end/testcases/general/constants/circularity.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/circularity.dart.strong.transformed.expect
@@ -137,7 +137,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///circularity.dart:
- Class1. (from org-dartlang-testcase:///circularity.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class2. (from org-dartlang-testcase:///circularity.dart:21:9)
- Class3. (from org-dartlang-testcase:///circularity.dart:29:9)
- Class4. (from org-dartlang-testcase:///circularity.dart:37:9)
diff --git a/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.expect b/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.expect
index c7388b3..fdc09aa 100644
--- a/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.expect
@@ -209,7 +209,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_asserts.dart:
- Foo. (from org-dartlang-testcase:///const_asserts.dart:7:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.withMessage (from org-dartlang-testcase:///const_asserts.dart:14:9)
- Foo.withInvalidMessage (from org-dartlang-testcase:///const_asserts.dart:16:9)
- Foo.withInvalidCondition (from org-dartlang-testcase:///const_asserts.dart:17:9)
diff --git a/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.transformed.expect
index 4038990..dd0f5c5 100644
--- a/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/const_asserts.dart.strong.transformed.expect
@@ -216,7 +216,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_asserts.dart:
- Foo. (from org-dartlang-testcase:///const_asserts.dart:7:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.withMessage (from org-dartlang-testcase:///const_asserts.dart:14:9)
- Foo.withInvalidMessage (from org-dartlang-testcase:///const_asserts.dart:16:9)
- Foo.withInvalidCondition (from org-dartlang-testcase:///const_asserts.dart:17:9)
diff --git a/pkg/front_end/testcases/general/constants/const_collections.dart.strong.expect b/pkg/front_end/testcases/general/constants/const_collections.dart.strong.expect
index 6bfdeba..58d0c68 100644
--- a/pkg/front_end/testcases/general/constants/const_collections.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/const_collections.dart.strong.expect
@@ -520,5 +520,5 @@
- CustomIterable. (from org-dartlang-testcase:///const_collections.dart:79:9)
- IterableBase. (from org-dartlang-sdk:///sdk/lib/collection/iterable.dart:218:9)
- WithEquals. (from org-dartlang-testcase:///const_collections.dart:72:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- CustomMap. (from org-dartlang-testcase:///const_collections.dart:84:9)
diff --git a/pkg/front_end/testcases/general/constants/const_collections.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/const_collections.dart.strong.transformed.expect
index f26bf33..f26aca0 100644
--- a/pkg/front_end/testcases/general/constants/const_collections.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/const_collections.dart.strong.transformed.expect
@@ -520,5 +520,5 @@
- CustomIterable. (from org-dartlang-testcase:///const_collections.dart:79:9)
- IterableBase. (from org-dartlang-sdk:///sdk/lib/collection/iterable.dart:218:9)
- WithEquals. (from org-dartlang-testcase:///const_collections.dart:72:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- CustomMap. (from org-dartlang-testcase:///const_collections.dart:84:9)
diff --git a/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.expect b/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.expect
index fe088f9..6ea8c4e 100644
--- a/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.expect
@@ -139,7 +139,7 @@
org-dartlang-testcase:///const_constructor_coverage_lib1.dart:
- Bar. (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:17:15)
- Baz. (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:9:15)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named1 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:18:15)
- Baz.named1 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:10:15)
- Baz.named5 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:14:15)
@@ -147,7 +147,7 @@
- Foo.named3 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:12:15)
org-dartlang-testcase:///const_constructor_coverage_lib2.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named3 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:20:15)
- Baz.named4 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:13:15)
- Foo.named2 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:11:15)
diff --git a/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.transformed.expect
index fe088f9..6ea8c4e 100644
--- a/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/const_constructor_coverage.dart.strong.transformed.expect
@@ -139,7 +139,7 @@
org-dartlang-testcase:///const_constructor_coverage_lib1.dart:
- Bar. (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:17:15)
- Baz. (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:9:15)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named1 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:18:15)
- Baz.named1 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:10:15)
- Baz.named5 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:14:15)
@@ -147,7 +147,7 @@
- Foo.named3 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:12:15)
org-dartlang-testcase:///const_constructor_coverage_lib2.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named3 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:20:15)
- Baz.named4 (from org-dartlang-testcase:///const_constructor_coverage_lib2.dart:13:15)
- Foo.named2 (from org-dartlang-testcase:///const_constructor_coverage_lib1.dart:11:15)
diff --git a/pkg/front_end/testcases/general/constants/various.dart.strong.expect b/pkg/front_end/testcases/general/constants/various.dart.strong.expect
index 6caacbe..6d3d9c5 100644
--- a/pkg/front_end/testcases/general/constants/various.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/various.dart.strong.expect
@@ -630,7 +630,7 @@
org-dartlang-testcase:///various.dart:
- ExtendsFoo2. (from org-dartlang-testcase:///various.dart:121:9)
- Foo. (from org-dartlang-testcase:///various.dart:109:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ConstClassWithFailingAssertWithEmptyMessage. (from org-dartlang-testcase:///various.dart:144:9)
- ClassWithTypeArguments. (from org-dartlang-testcase:///various.dart:151:9)
- ConstClassWithFinalFields2. (from org-dartlang-testcase:///various.dart:177:9)
diff --git a/pkg/front_end/testcases/general/constants/various.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/various.dart.strong.transformed.expect
index d432ab2..9b064ee 100644
--- a/pkg/front_end/testcases/general/constants/various.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/various.dart.strong.transformed.expect
@@ -634,7 +634,7 @@
org-dartlang-testcase:///various.dart:
- ExtendsFoo2. (from org-dartlang-testcase:///various.dart:121:9)
- Foo. (from org-dartlang-testcase:///various.dart:109:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ConstClassWithFailingAssertWithEmptyMessage. (from org-dartlang-testcase:///various.dart:144:9)
- ClassWithTypeArguments. (from org-dartlang-testcase:///various.dart:151:9)
- ConstClassWithFinalFields2. (from org-dartlang-testcase:///various.dart:177:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.expect
index 07c4e9d..c8fbdb9 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.expect
@@ -129,7 +129,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_asserts.dart:
- Foo. (from org-dartlang-testcase:///const_asserts.dart:7:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.withMessage (from org-dartlang-testcase:///const_asserts.dart:13:9)
- Foo.withInvalidMessage (from org-dartlang-testcase:///const_asserts.dart:15:9)
- Foo.withInvalidCondition (from org-dartlang-testcase:///const_asserts.dart:16:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.transformed.expect
index 5db03b0..0224dd0 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/const_asserts.dart.strong.transformed.expect
@@ -143,7 +143,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_asserts.dart:
- Foo. (from org-dartlang-testcase:///const_asserts.dart:7:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.withMessage (from org-dartlang-testcase:///const_asserts.dart:13:9)
- Foo.withInvalidMessage (from org-dartlang-testcase:///const_asserts.dart:15:9)
- Foo.withInvalidCondition (from org-dartlang-testcase:///const_asserts.dart:16:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.expect
index 3c0c3ba..666cda7 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.expect
@@ -253,7 +253,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///various.dart:
- C. (from org-dartlang-testcase:///various.dart:92:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.redirect (from org-dartlang-testcase:///various.dart:99:9)
- Class. (from org-dartlang-testcase:///various.dart:98:9)
- A. (from org-dartlang-testcase:///various.dart:80:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.transformed.expect
index b0c66e2..cae94a4 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various.dart.strong.transformed.expect
@@ -287,7 +287,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///various.dart:
- C. (from org-dartlang-testcase:///various.dart:92:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.redirect (from org-dartlang-testcase:///various.dart:99:9)
- Class. (from org-dartlang-testcase:///various.dart:98:9)
- A. (from org-dartlang-testcase:///various.dart:80:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.expect
index 1201f30..c554f17 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.expect
@@ -133,5 +133,5 @@
- Class. (from org-dartlang-testcase:///various_2_lib.dart:8:9)
org-dartlang-testcase:///various_2_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///various_2_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.transformed.expect
index 413fa9e..79894cf 100644
--- a/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constants/with_unevaluated_agnostic/various_2.dart.strong.transformed.expect
@@ -142,5 +142,5 @@
- Class. (from org-dartlang-testcase:///various_2_lib.dart:8:9)
org-dartlang-testcase:///various_2_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///various_2_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.expect b/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.expect
index 7b3fd67..a95f0d2 100644
--- a/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.expect
+++ b/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.expect
@@ -53,4 +53,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructor_const_inference.dart:
- _Y. (from org-dartlang-testcase:///constructor_const_inference.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.transformed.expect b/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.transformed.expect
index 7b3fd67..a95f0d2 100644
--- a/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/constructor_const_inference.dart.strong.transformed.expect
@@ -53,4 +53,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructor_const_inference.dart:
- _Y. (from org-dartlang-testcase:///constructor_const_inference.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/duplicated_declarations.dart.strong.expect b/pkg/front_end/testcases/general/duplicated_declarations.dart.strong.expect
index 7149868..2e4c25a 100644
--- a/pkg/front_end/testcases/general/duplicated_declarations.dart.strong.expect
+++ b/pkg/front_end/testcases/general/duplicated_declarations.dart.strong.expect
@@ -681,6 +681,6 @@
Constructor coverage from constants:
org-dartlang-testcase:///duplicated_declarations.dart:
- Enum#1. (from org-dartlang-testcase:///duplicated_declarations.dart:81:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Enum. (from org-dartlang-testcase:///duplicated_declarations.dart:74:6)
- AnotherEnum. (from org-dartlang-testcase:///duplicated_declarations.dart:87:6)
diff --git a/pkg/front_end/testcases/general/expressions.dart.strong.expect b/pkg/front_end/testcases/general/expressions.dart.strong.expect
index cf0b310..1fcb0bc 100644
--- a/pkg/front_end/testcases/general/expressions.dart.strong.expect
+++ b/pkg/front_end/testcases/general/expressions.dart.strong.expect
@@ -97,4 +97,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///expressions.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/expressions.dart.strong.transformed.expect b/pkg/front_end/testcases/general/expressions.dart.strong.transformed.expect
index 325ef6d..d23becc 100644
--- a/pkg/front_end/testcases/general/expressions.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/expressions.dart.strong.transformed.expect
@@ -106,4 +106,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///expressions.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/issue31767.dart.strong.expect b/pkg/front_end/testcases/general/issue31767.dart.strong.expect
index 1d880e0..8e1ff2d 100644
--- a/pkg/front_end/testcases/general/issue31767.dart.strong.expect
+++ b/pkg/front_end/testcases/general/issue31767.dart.strong.expect
@@ -130,5 +130,5 @@
- _A. (from org-dartlang-testcase:///issue31767_lib.dart:20:9)
org-dartlang-testcase:///issue31767_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- _A. (from org-dartlang-testcase:///issue31767_lib.dart:20:9)
diff --git a/pkg/front_end/testcases/general/issue31767.dart.strong.transformed.expect b/pkg/front_end/testcases/general/issue31767.dart.strong.transformed.expect
index 2a77e8c..1692006 100644
--- a/pkg/front_end/testcases/general/issue31767.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/issue31767.dart.strong.transformed.expect
@@ -130,5 +130,5 @@
- _A. (from org-dartlang-testcase:///issue31767_lib.dart:20:9)
org-dartlang-testcase:///issue31767_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- _A. (from org-dartlang-testcase:///issue31767_lib.dart:20:9)
diff --git a/pkg/front_end/testcases/general/issue41070.dart.strong.expect b/pkg/front_end/testcases/general/issue41070.dart.strong.expect
index d096b3a..71da7fe 100644
--- a/pkg/front_end/testcases/general/issue41070.dart.strong.expect
+++ b/pkg/front_end/testcases/general/issue41070.dart.strong.expect
@@ -56,4 +56,4 @@
org-dartlang-testcase:///issue41070.dart:
- Application. (from org-dartlang-testcase:///issue41070.dart:12:7)
- Base. (from org-dartlang-testcase:///issue41070.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/issue41070.dart.strong.transformed.expect b/pkg/front_end/testcases/general/issue41070.dart.strong.transformed.expect
index 2b92125..30b4c02 100644
--- a/pkg/front_end/testcases/general/issue41070.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/issue41070.dart.strong.transformed.expect
@@ -66,4 +66,4 @@
org-dartlang-testcase:///issue41070.dart:
- Application. (from org-dartlang-testcase:///issue41070.dart:12:7)
- Base. (from org-dartlang-testcase:///issue41070.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/magic_const.dart.strong.expect b/pkg/front_end/testcases/general/magic_const.dart.strong.expect
index e9b6273..191ed7b 100644
--- a/pkg/front_end/testcases/general/magic_const.dart.strong.expect
+++ b/pkg/front_end/testcases/general/magic_const.dart.strong.expect
@@ -74,4 +74,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///magic_const.dart:
- Constant. (from org-dartlang-testcase:///magic_const.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/magic_const.dart.strong.transformed.expect b/pkg/front_end/testcases/general/magic_const.dart.strong.transformed.expect
index 01a97f5..7e7a8a4 100644
--- a/pkg/front_end/testcases/general/magic_const.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/magic_const.dart.strong.transformed.expect
@@ -78,4 +78,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///magic_const.dart:
- Constant. (from org-dartlang-testcase:///magic_const.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/metadata_enum.dart.strong.expect b/pkg/front_end/testcases/general/metadata_enum.dart.strong.expect
index 7f56692..0b8666f 100644
--- a/pkg/front_end/testcases/general/metadata_enum.dart.strong.expect
+++ b/pkg/front_end/testcases/general/metadata_enum.dart.strong.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///metadata_enum.dart:
- E. (from org-dartlang-testcase:///metadata_enum.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/metadata_enum.dart.strong.transformed.expect b/pkg/front_end/testcases/general/metadata_enum.dart.strong.transformed.expect
index 7f56692..0b8666f 100644
--- a/pkg/front_end/testcases/general/metadata_enum.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/metadata_enum.dart.strong.transformed.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///metadata_enum.dart:
- E. (from org-dartlang-testcase:///metadata_enum.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.expect b/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.expect
index 9c109d5..85d39b62 100644
--- a/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.expect
+++ b/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.expect
@@ -68,4 +68,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///redirecting_factory_const_inference.dart:
- _Y. (from org-dartlang-testcase:///redirecting_factory_const_inference.dart:14:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.transformed.expect b/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.transformed.expect
index bea6536..17665de 100644
--- a/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/redirecting_factory_const_inference.dart.strong.transformed.expect
@@ -68,4 +68,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///redirecting_factory_const_inference.dart:
- _Y. (from org-dartlang-testcase:///redirecting_factory_const_inference.dart:14:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.expect b/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.expect
index fdc3e04..ed8ef82 100644
--- a/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.expect
+++ b/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.expect
@@ -43,4 +43,4 @@
org-dartlang-testcase:///redirection_type_arguments.dart:
- B. (from org-dartlang-testcase:///redirection_type_arguments.dart:16:9)
- A.empty (from org-dartlang-testcase:///redirection_type_arguments.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.transformed.expect b/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.transformed.expect
index 7550d4d..88a256a 100644
--- a/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/redirection_type_arguments.dart.strong.transformed.expect
@@ -43,4 +43,4 @@
org-dartlang-testcase:///redirection_type_arguments.dart:
- B. (from org-dartlang-testcase:///redirection_type_arguments.dart:16:9)
- A.empty (from org-dartlang-testcase:///redirection_type_arguments.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/sdk_diagnostic.dart.outline.expect b/pkg/front_end/testcases/general/sdk_diagnostic.dart.outline.expect
index fef85bb..4c683ea 100644
--- a/pkg/front_end/testcases/general/sdk_diagnostic.dart.outline.expect
+++ b/pkg/front_end/testcases/general/sdk_diagnostic.dart.outline.expect
@@ -12,7 +12,7 @@
//
// class C extends Iterable<Object> {
// ^
-// sdk/lib/core/iterable.dart:158:19: Context: 'Iterable.iterator' is defined here.
+// sdk/lib/core/iterable.dart:148:19: Context: 'Iterable.iterator' is defined here.
// Iterator<E> get iterator;
// ^^^^^^^^
//
diff --git a/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.expect b/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.expect
index 9c9017f..ae6ded4 100644
--- a/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.expect
+++ b/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.expect
@@ -12,7 +12,7 @@
//
// class C extends Iterable<Object> {
// ^
-// sdk/lib/core/iterable.dart:158:19: Context: 'Iterable.iterator' is defined here.
+// sdk/lib/core/iterable.dart:148:19: Context: 'Iterable.iterator' is defined here.
// Iterator<E> get iterator;
// ^^^^^^^^
//
diff --git a/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.transformed.expect b/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.transformed.expect
index 9c9017f..ae6ded4 100644
--- a/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/sdk_diagnostic.dart.strong.transformed.expect
@@ -12,7 +12,7 @@
//
// class C extends Iterable<Object> {
// ^
-// sdk/lib/core/iterable.dart:158:19: Context: 'Iterable.iterator' is defined here.
+// sdk/lib/core/iterable.dart:148:19: Context: 'Iterable.iterator' is defined here.
// Iterator<E> get iterator;
// ^^^^^^^^
//
diff --git a/pkg/front_end/testcases/general/type_variable_uses.dart.strong.expect b/pkg/front_end/testcases/general/type_variable_uses.dart.strong.expect
index 9174c05..97634b7 100644
--- a/pkg/front_end/testcases/general/type_variable_uses.dart.strong.expect
+++ b/pkg/front_end/testcases/general/type_variable_uses.dart.strong.expect
@@ -117,4 +117,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///type_variable_uses.dart:
- C. (from org-dartlang-testcase:///type_variable_uses.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/type_variable_uses.dart.strong.transformed.expect b/pkg/front_end/testcases/general/type_variable_uses.dart.strong.transformed.expect
index c51d8c4..e2cf292 100644
--- a/pkg/front_end/testcases/general/type_variable_uses.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/type_variable_uses.dart.strong.transformed.expect
@@ -121,4 +121,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///type_variable_uses.dart:
- C. (from org-dartlang-testcase:///type_variable_uses.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.expect b/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.expect
index 42872b5..99bdeb7 100644
--- a/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.expect
+++ b/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.expect
@@ -63,7 +63,7 @@
org-dartlang-testcase:///const_lib.dart:
- _B&A&M. (from org-dartlang-testcase:///const_lib.dart:15:7)
- A. (from org-dartlang-testcase:///const_lib.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
org-dartlang-testcase:///main.dart:
- B. (from org-dartlang-testcase:///const_lib.dart:16:9)
diff --git a/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.transformed.expect b/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.transformed.expect
index 42872b5..99bdeb7 100644
--- a/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/general/with_dependencies/issue43538/main.dart.strong.transformed.expect
@@ -63,7 +63,7 @@
org-dartlang-testcase:///const_lib.dart:
- _B&A&M. (from org-dartlang-testcase:///const_lib.dart:15:7)
- A. (from org-dartlang-testcase:///const_lib.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
org-dartlang-testcase:///main.dart:
- B. (from org-dartlang-testcase:///const_lib.dart:16:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.expect
index b7481a0..2f3b038 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.expect
@@ -538,4 +538,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///DeltaBlue.dart:
- Strength. (from org-dartlang-testcase:///DeltaBlue.dart:61:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.transformed.expect
index 2e51431..20311a0 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/DeltaBlue.dart.weak.transformed.expect
@@ -538,4 +538,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///DeltaBlue.dart:
- Strength. (from org-dartlang-testcase:///DeltaBlue.dart:61:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.expect
index a99c562..fb849d9 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.expect
@@ -64,5 +64,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_on_enum_values.dart:
- Foo. (from org-dartlang-testcase:///annotation_on_enum_values.dart:17:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Fisk.fisk (from org-dartlang-testcase:///annotation_on_enum_values.dart:14:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.transformed.expect
index a99c562..fb849d9 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_on_enum_values.dart.weak.transformed.expect
@@ -64,5 +64,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_on_enum_values.dart:
- Foo. (from org-dartlang-testcase:///annotation_on_enum_values.dart:17:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Fisk.fisk (from org-dartlang-testcase:///annotation_on_enum_values.dart:14:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.expect
index c2cc64e..41693bf 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.expect
@@ -61,5 +61,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_top.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- A. (from org-dartlang-testcase:///annotation_top.dart:14:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.transformed.expect
index c2cc64e..41693bf 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_top.dart.weak.transformed.expect
@@ -61,5 +61,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_top.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- A. (from org-dartlang-testcase:///annotation_top.dart:14:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.expect
index edbab10..a3070a4 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.expect
@@ -65,5 +65,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_variable_declaration.dart:
- Bar. (from org-dartlang-testcase:///annotation_variable_declaration.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named (from org-dartlang-testcase:///annotation_variable_declaration.dart:11:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.transformed.expect
index edbab10..a3070a4 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/annotation_variable_declaration.dart.weak.transformed.expect
@@ -65,5 +65,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///annotation_variable_declaration.dart:
- Bar. (from org-dartlang-testcase:///annotation_variable_declaration.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Bar.named (from org-dartlang-testcase:///annotation_variable_declaration.dart:11:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.expect
index 2f79c22..491a29a 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.expect
@@ -89,4 +89,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///bug33099.dart:
- _FailingTest. (from org-dartlang-testcase:///bug33099.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.transformed.expect
index b0e0947..a381949 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/bug33099.dart.weak.transformed.expect
@@ -93,4 +93,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///bug33099.dart:
- _FailingTest. (from org-dartlang-testcase:///bug33099.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.expect
index 351fe69..e2fb0a4 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.expect
@@ -53,4 +53,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructor_const_inference.dart:
- _Y. (from org-dartlang-testcase:///constructor_const_inference.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.transformed.expect
index 351fe69..e2fb0a4 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/constructor_const_inference.dart.weak.transformed.expect
@@ -53,4 +53,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructor_const_inference.dart:
- _Y. (from org-dartlang-testcase:///constructor_const_inference.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/duplicated_declarations.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/duplicated_declarations.dart.weak.expect
index 5c1f0c4..43846a2 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/duplicated_declarations.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/duplicated_declarations.dart.weak.expect
@@ -681,6 +681,6 @@
Constructor coverage from constants:
org-dartlang-testcase:///duplicated_declarations.dart:
- Enum#1. (from org-dartlang-testcase:///duplicated_declarations.dart:83:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Enum. (from org-dartlang-testcase:///duplicated_declarations.dart:76:6)
- AnotherEnum. (from org-dartlang-testcase:///duplicated_declarations.dart:89:6)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.expect
index 7bbd1c85..d29fb1b 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.expect
@@ -97,4 +97,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///expressions.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.transformed.expect
index f51040a..75e91c9 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/expressions.dart.weak.transformed.expect
@@ -106,4 +106,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///expressions.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.expect
index 8429173..6d8e8308 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.expect
@@ -74,4 +74,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///magic_const.dart:
- Constant. (from org-dartlang-testcase:///magic_const.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.transformed.expect
index 77abba8..160e248 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/magic_const.dart.weak.transformed.expect
@@ -78,4 +78,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///magic_const.dart:
- Constant. (from org-dartlang-testcase:///magic_const.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.expect
index 1dd7cb7..f409662 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///metadata_enum.dart:
- E. (from org-dartlang-testcase:///metadata_enum.dart:10:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.transformed.expect
index 1dd7cb7..f409662 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/metadata_enum.dart.weak.transformed.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///metadata_enum.dart:
- E. (from org-dartlang-testcase:///metadata_enum.dart:10:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.expect
index 046d379..86194ea 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.expect
@@ -68,4 +68,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///redirecting_factory_const_inference.dart:
- _Y. (from org-dartlang-testcase:///redirecting_factory_const_inference.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.transformed.expect
index 7c20f05..2027839 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/redirecting_factory_const_inference.dart.weak.transformed.expect
@@ -68,4 +68,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///redirecting_factory_const_inference.dart:
- _Y. (from org-dartlang-testcase:///redirecting_factory_const_inference.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.expect
index 7f62ccc..d6c5a68 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.expect
@@ -43,4 +43,4 @@
org-dartlang-testcase:///redirection_type_arguments.dart:
- B. (from org-dartlang-testcase:///redirection_type_arguments.dart:18:9)
- A.empty (from org-dartlang-testcase:///redirection_type_arguments.dart:14:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.transformed.expect
index 58e796a..7119399 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/redirection_type_arguments.dart.weak.transformed.expect
@@ -43,4 +43,4 @@
org-dartlang-testcase:///redirection_type_arguments.dart:
- B. (from org-dartlang-testcase:///redirection_type_arguments.dart:18:9)
- A.empty (from org-dartlang-testcase:///redirection_type_arguments.dart:14:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.expect
index 73f42bd..e603673 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.expect
@@ -12,7 +12,7 @@
//
// class C extends Iterable<Object> {
// ^
-// sdk/lib/core/iterable.dart:158:19: Context: 'Iterable.iterator' is defined here.
+// sdk/lib/core/iterable.dart:148:19: Context: 'Iterable.iterator' is defined here.
// Iterator<E> get iterator;
// ^^^^^^^^
//
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.transformed.expect
index 73f42bd..e603673 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/sdk_diagnostic.dart.weak.transformed.expect
@@ -12,7 +12,7 @@
//
// class C extends Iterable<Object> {
// ^
-// sdk/lib/core/iterable.dart:158:19: Context: 'Iterable.iterator' is defined here.
+// sdk/lib/core/iterable.dart:148:19: Context: 'Iterable.iterator' is defined here.
// Iterator<E> get iterator;
// ^^^^^^^^
//
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.expect b/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.expect
index 1eabb1d..32194a2 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.expect
@@ -117,4 +117,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///type_variable_uses.dart:
- C. (from org-dartlang-testcase:///type_variable_uses.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.transformed.expect b/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.transformed.expect
index b6e513e..e162040 100644
--- a/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/general_nnbd_opt_out/type_variable_uses.dart.weak.transformed.expect
@@ -121,4 +121,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///type_variable_uses.dart:
- C. (from org-dartlang-testcase:///type_variable_uses.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.expect b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.expect
index 1aabce1..5cf994f 100644
--- a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructors_infer_from_arguments_const.dart:
- C. (from org-dartlang-testcase:///constructors_infer_from_arguments_const.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.transformed.expect
index 1aabce1..5cf994f 100644
--- a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const.dart.strong.transformed.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructors_infer_from_arguments_const.dart:
- C. (from org-dartlang-testcase:///constructors_infer_from_arguments_const.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.expect b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.expect
index 4fba179..f64a716 100644
--- a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.expect
@@ -46,5 +46,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:
- C. (from org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- D. (from org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:14:9)
diff --git a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.transformed.expect
index 4fba179..f64a716 100644
--- a/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/constructors_infer_from_arguments_const_with_upper_bound.dart.strong.transformed.expect
@@ -46,5 +46,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:
- C. (from org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:10:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- D. (from org-dartlang-testcase:///constructors_infer_from_arguments_const_with_upper_bound.dart:14:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.expect
index 406217a..5fdfe4d 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.expect
@@ -62,5 +62,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.named (from org-dartlang-testcase:///downwards_inference_annotations.dart:10:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.transformed.expect
index 406217a..5fdfe4d 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations.dart.strong.transformed.expect
@@ -62,5 +62,5 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Foo.named (from org-dartlang-testcase:///downwards_inference_annotations.dart:10:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.expect
index e236f0a..bc1bc95 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.expect
@@ -47,4 +47,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_class_members.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_class_members.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.transformed.expect
index e236f0a..bc1bc95 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_class_members.dart.strong.transformed.expect
@@ -47,4 +47,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_class_members.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_class_members.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.expect
index f299988..21d93c9 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.expect
@@ -33,4 +33,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_for_loop_variable.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_for_loop_variable.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.transformed.expect
index b6b601f..c63b4f8 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_for_loop_variable.dart.strong.transformed.expect
@@ -38,4 +38,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_for_loop_variable.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_for_loop_variable.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.expect
index 07804e7..bd79165 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.expect
@@ -32,4 +32,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_locals.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_locals.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.transformed.expect
index 07804e7..bd79165 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals.dart.strong.transformed.expect
@@ -32,4 +32,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_locals.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_locals.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.expect
index c062ee7..4f025f27 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.expect
@@ -33,4 +33,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_locals_referring_to_locals.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_locals_referring_to_locals.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.transformed.expect
index c062ee7..4f025f27 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_locals_referring_to_locals.dart.strong.transformed.expect
@@ -33,4 +33,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_locals_referring_to_locals.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_locals_referring_to_locals.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.expect
index c591108..d7a402b 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.expect
@@ -44,4 +44,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_parameter.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_parameter.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.transformed.expect
index c591108..d7a402b 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter.dart.strong.transformed.expect
@@ -44,4 +44,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_parameter.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_parameter.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.expect
index 1322c61..b72210d 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_parameter_local.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_parameter_local.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.transformed.expect
index 1322c61..b72210d 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_parameter_local.dart.strong.transformed.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_parameter_local.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_parameter_local.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.expect
index 3fd9e29..59529f1 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_type_variable_local.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_type_variable_local.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.transformed.expect
index 3fd9e29..59529f1 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_type_variable_local.dart.strong.transformed.expect
@@ -31,4 +31,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_type_variable_local.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_type_variable_local.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.expect
index 8ed30e8..17384f4 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.expect
@@ -29,4 +29,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_typedef.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_typedef.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.transformed.expect
index 8ed30e8..17384f4 100644
--- a/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/downwards_inference_annotations_typedef.dart.strong.transformed.expect
@@ -29,4 +29,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///downwards_inference_annotations_typedef.dart:
- Foo. (from org-dartlang-testcase:///downwards_inference_annotations_typedef.dart:9:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.expect b/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.expect
index f1c84c4..7fcd694 100644
--- a/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.expect
@@ -38,4 +38,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///inferred_type_is_enum.dart:
- E. (from org-dartlang-testcase:///inferred_type_is_enum.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.transformed.expect
index f1c84c4..7fcd694 100644
--- a/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/inferred_type_is_enum.dart.strong.transformed.expect
@@ -38,4 +38,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///inferred_type_is_enum.dart:
- E. (from org-dartlang-testcase:///inferred_type_is_enum.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.expect b/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.expect
index a2a3083..2c64c5a 100644
--- a/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.expect
+++ b/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.expect
@@ -38,4 +38,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///inferred_type_is_enum_values.dart:
- E. (from org-dartlang-testcase:///inferred_type_is_enum_values.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.transformed.expect b/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.transformed.expect
index a2a3083..2c64c5a 100644
--- a/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference/inferred_type_is_enum_values.dart.strong.transformed.expect
@@ -38,4 +38,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///inferred_type_is_enum_values.dart:
- E. (from org-dartlang-testcase:///inferred_type_is_enum_values.dart:8:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.expect b/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.expect
index 2efb0fc..beb0961 100644
--- a/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.expect
+++ b/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.expect
@@ -70,4 +70,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_invocation.dart:
- Bar. (from org-dartlang-testcase:///const_invocation.dart:24:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.transformed.expect b/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.transformed.expect
index 2efb0fc..beb0961 100644
--- a/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference_new/const_invocation.dart.strong.transformed.expect
@@ -70,4 +70,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///const_invocation.dart:
- Bar. (from org-dartlang-testcase:///const_invocation.dart:24:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference_new/switch.dart.strong.expect b/pkg/front_end/testcases/inference_new/switch.dart.strong.expect
index d85eb28..6e55000 100644
--- a/pkg/front_end/testcases/inference_new/switch.dart.strong.expect
+++ b/pkg/front_end/testcases/inference_new/switch.dart.strong.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch.dart:
- C. (from org-dartlang-testcase:///switch.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/inference_new/switch.dart.strong.transformed.expect b/pkg/front_end/testcases/inference_new/switch.dart.strong.transformed.expect
index d85eb28..6e55000 100644
--- a/pkg/front_end/testcases/inference_new/switch.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/inference_new/switch.dart.strong.transformed.expect
@@ -46,4 +46,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch.dart:
- C. (from org-dartlang-testcase:///switch.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.expect b/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.expect
index ed2533d..40eb00c 100644
--- a/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.expect
+++ b/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.expect
@@ -175,4 +175,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///late_annotations.dart:
- Annotation. (from org-dartlang-testcase:///late_annotations.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.transformed.expect b/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.transformed.expect
index 5956226..5f7ea3c 100644
--- a/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/late_lowering/late_annotations.dart.strong.transformed.expect
@@ -184,4 +184,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///late_annotations.dart:
- Annotation. (from org-dartlang-testcase:///late_annotations.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.expect b/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.expect
index 374a96b..053c333 100644
--- a/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.expect
+++ b/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.expect
@@ -274,4 +274,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///late_annotations.dart:
- Annotation. (from org-dartlang-testcase:///late_annotations.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.transformed.expect b/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.transformed.expect
index 374a96b..053c333 100644
--- a/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/late_lowering/late_annotations.dart.weak.transformed.expect
@@ -274,4 +274,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///late_annotations.dart:
- Annotation. (from org-dartlang-testcase:///late_annotations.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.expect b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.expect
index 36965cc..0e66be9 100644
--- a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.expect
@@ -390,4 +390,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///assignability_error_messages.dart:
- A. (from org-dartlang-testcase:///assignability_error_messages.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.transformed.expect
index c299301..bdd60d8 100644
--- a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.strong.transformed.expect
@@ -472,4 +472,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///assignability_error_messages.dart:
- A. (from org-dartlang-testcase:///assignability_error_messages.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.expect b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.expect
index 36965cc..0e66be9 100644
--- a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.expect
@@ -390,4 +390,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///assignability_error_messages.dart:
- A. (from org-dartlang-testcase:///assignability_error_messages.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.transformed.expect
index e439ef1..4ba3fa1 100644
--- a/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/assignability_error_messages.dart.weak.transformed.expect
@@ -457,4 +457,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///assignability_error_messages.dart:
- A. (from org-dartlang-testcase:///assignability_error_messages.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.expect b/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.expect
index a7da242..a1b3d15 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.expect
@@ -57,4 +57,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_check.dart:
- Class. (from org-dartlang-testcase:///constant_null_check.dart:13:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.transformed.expect
index a7da242..a1b3d15 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_check.dart.strong.transformed.expect
@@ -57,4 +57,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_check.dart:
- Class. (from org-dartlang-testcase:///constant_null_check.dart:13:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.expect b/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.expect
index a7da242..a1b3d15 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.expect
@@ -57,4 +57,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_check.dart:
- Class. (from org-dartlang-testcase:///constant_null_check.dart:13:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.transformed.expect
index a7da242..a1b3d15 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_check.dart.weak.transformed.expect
@@ -57,4 +57,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_check.dart:
- Class. (from org-dartlang-testcase:///constant_null_check.dart:13:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.expect b/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.expect
index 59d1cde..e8a8746 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.expect
@@ -96,7 +96,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:38:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.transformed.expect
index fcfad8f..08902cf 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_is.dart.strong.transformed.expect
@@ -113,7 +113,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:38:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.expect b/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.expect
index a91178d..406d358 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.expect
@@ -94,7 +94,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:38:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
diff --git a/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.transformed.expect
index c1bd54d..35d0686 100644
--- a/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constant_null_is.dart.weak.transformed.expect
@@ -111,7 +111,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:38:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
diff --git a/pkg/front_end/testcases/nnbd/constants.dart.strong.expect b/pkg/front_end/testcases/nnbd/constants.dart.strong.expect
index 7f4ce82..0e0cfb3 100644
--- a/pkg/front_end/testcases/nnbd/constants.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/constants.dart.strong.expect
@@ -113,5 +113,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/nnbd/constants.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/constants.dart.strong.transformed.expect
index 7f4ce82..0e0cfb3 100644
--- a/pkg/front_end/testcases/nnbd/constants.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constants.dart.strong.transformed.expect
@@ -113,5 +113,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/nnbd/constants.dart.weak.expect b/pkg/front_end/testcases/nnbd/constants.dart.weak.expect
index 10a3692..607aec4 100644
--- a/pkg/front_end/testcases/nnbd/constants.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/constants.dart.weak.expect
@@ -113,5 +113,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/nnbd/constants.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/constants.dart.weak.transformed.expect
index 10a3692..607aec4 100644
--- a/pkg/front_end/testcases/nnbd/constants.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/constants.dart.weak.transformed.expect
@@ -113,5 +113,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:8:9)
diff --git a/pkg/front_end/testcases/nnbd/external_fields.dart.strong.expect b/pkg/front_end/testcases/nnbd/external_fields.dart.strong.expect
index 6fb233a..660d848 100644
--- a/pkg/front_end/testcases/nnbd/external_fields.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/external_fields.dart.strong.expect
@@ -128,4 +128,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///external_fields.dart:
- Annotation. (from org-dartlang-testcase:///external_fields.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/external_fields.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/external_fields.dart.strong.transformed.expect
index 6fb233a..660d848 100644
--- a/pkg/front_end/testcases/nnbd/external_fields.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/external_fields.dart.strong.transformed.expect
@@ -128,4 +128,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///external_fields.dart:
- Annotation. (from org-dartlang-testcase:///external_fields.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/external_fields.dart.weak.expect b/pkg/front_end/testcases/nnbd/external_fields.dart.weak.expect
index 6fb233a..660d848 100644
--- a/pkg/front_end/testcases/nnbd/external_fields.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/external_fields.dart.weak.expect
@@ -128,4 +128,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///external_fields.dart:
- Annotation. (from org-dartlang-testcase:///external_fields.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/external_fields.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/external_fields.dart.weak.transformed.expect
index 6fb233a..660d848 100644
--- a/pkg/front_end/testcases/nnbd/external_fields.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/external_fields.dart.weak.transformed.expect
@@ -128,4 +128,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///external_fields.dart:
- Annotation. (from org-dartlang-testcase:///external_fields.dart:6:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.expect b/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.expect
index 464c9cb..c8e0ecb 100644
--- a/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.expect
@@ -63,4 +63,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///nullable_access.dart:
- A. (from org-dartlang-testcase:///nullable_access.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.transformed.expect
index 464c9cb..c8e0ecb 100644
--- a/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/nullable_access.dart.strong.transformed.expect
@@ -63,4 +63,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///nullable_access.dart:
- A. (from org-dartlang-testcase:///nullable_access.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.expect b/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.expect
index 464c9cb..c8e0ecb 100644
--- a/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.expect
@@ -63,4 +63,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///nullable_access.dart:
- A. (from org-dartlang-testcase:///nullable_access.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.transformed.expect
index 464c9cb..c8e0ecb 100644
--- a/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/nullable_access.dart.weak.transformed.expect
@@ -63,4 +63,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///nullable_access.dart:
- A. (from org-dartlang-testcase:///nullable_access.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.expect
index 0aec1b2..d067529 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.expect
@@ -259,7 +259,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_as.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_as.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_as.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_as.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_as.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.transformed.expect
index 0aec1b2..d067529 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.strong.transformed.expect
@@ -259,7 +259,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_as.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_as.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_as.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_as.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_as.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.expect
index 26e7b42..2f79aaf 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.expect
@@ -251,7 +251,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_as.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_as.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_as.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_as.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_as.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.transformed.expect
index 26e7b42..2f79aaf 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_as.dart.weak.transformed.expect
@@ -251,7 +251,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_as.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_as.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_as.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_as.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_as.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.expect
index 3b5e4e3..dd71e24 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.expect
@@ -118,7 +118,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_is.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_is.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_is.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_is.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_is.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.transformed.expect
index 3b5e4e3..dd71e24 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.strong.transformed.expect
@@ -118,7 +118,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_is.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_is.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_is.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_is.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_is.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.expect
index 11e676f..ca7b07c 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.expect
@@ -118,7 +118,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_is.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_is.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_is.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_is.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_is.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.transformed.expect
index 11e676f..ca7b07c 100644
--- a/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/potentially_constant_type_is.dart.weak.transformed.expect
@@ -118,7 +118,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///potentially_constant_type_is.dart:
- Class. (from org-dartlang-testcase:///potentially_constant_type_is.dart:16:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- ClassWithBound. (from org-dartlang-testcase:///potentially_constant_type_is.dart:22:9)
- ClassWithBound.withValue (from org-dartlang-testcase:///potentially_constant_type_is.dart:24:9)
- ClassWithList. (from org-dartlang-testcase:///potentially_constant_type_is.dart:30:9)
diff --git a/pkg/front_end/testcases/nnbd/return_null.dart.strong.expect b/pkg/front_end/testcases/nnbd/return_null.dart.strong.expect
index 96efba5..70d918b 100644
--- a/pkg/front_end/testcases/nnbd/return_null.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/return_null.dart.strong.expect
@@ -235,4 +235,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///return_null.dart:
- Enum. (from org-dartlang-testcase:///return_null.dart:43:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/return_null.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/return_null.dart.strong.transformed.expect
index 84c1ee6..2b1a3dc 100644
--- a/pkg/front_end/testcases/nnbd/return_null.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/return_null.dart.strong.transformed.expect
@@ -648,4 +648,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///return_null.dart:
- Enum. (from org-dartlang-testcase:///return_null.dart:43:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/return_null.dart.weak.expect b/pkg/front_end/testcases/nnbd/return_null.dart.weak.expect
index a0d272c..0513741 100644
--- a/pkg/front_end/testcases/nnbd/return_null.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/return_null.dart.weak.expect
@@ -242,4 +242,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///return_null.dart:
- Enum. (from org-dartlang-testcase:///return_null.dart:43:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/return_null.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/return_null.dart.weak.transformed.expect
index 66e2a7a..3643cf7 100644
--- a/pkg/front_end/testcases/nnbd/return_null.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/return_null.dart.weak.transformed.expect
@@ -640,4 +640,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///return_null.dart:
- Enum. (from org-dartlang-testcase:///return_null.dart:43:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.expect b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.expect
index 936628a..7857870 100644
--- a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.expect
@@ -115,4 +115,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch_nullable_enum.dart:
- Enum. (from org-dartlang-testcase:///switch_nullable_enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.transformed.expect
index 936628a..7857870 100644
--- a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.strong.transformed.expect
@@ -115,4 +115,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch_nullable_enum.dart:
- Enum. (from org-dartlang-testcase:///switch_nullable_enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.expect b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.expect
index 5a45b37..e1e6175 100644
--- a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.expect
@@ -119,4 +119,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch_nullable_enum.dart:
- Enum. (from org-dartlang-testcase:///switch_nullable_enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.transformed.expect
index 5a45b37..e1e6175 100644
--- a/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/switch_nullable_enum.dart.weak.transformed.expect
@@ -119,4 +119,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///switch_nullable_enum.dart:
- Enum. (from org-dartlang-testcase:///switch_nullable_enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.expect b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.expect
index 1108882..0d7d320 100644
--- a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.expect
+++ b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.expect
@@ -106,5 +106,5 @@
- D. (from org-dartlang-testcase:///switch_redesign_types.dart:23:9)
- B. (from org-dartlang-testcase:///switch_redesign_types.dart:15:9)
- A. (from org-dartlang-testcase:///switch_redesign_types.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- C. (from org-dartlang-testcase:///switch_redesign_types.dart:19:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.transformed.expect b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.transformed.expect
index 1108882..0d7d320 100644
--- a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.strong.transformed.expect
@@ -106,5 +106,5 @@
- D. (from org-dartlang-testcase:///switch_redesign_types.dart:23:9)
- B. (from org-dartlang-testcase:///switch_redesign_types.dart:15:9)
- A. (from org-dartlang-testcase:///switch_redesign_types.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- C. (from org-dartlang-testcase:///switch_redesign_types.dart:19:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.expect b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.expect
index 1108882..0d7d320 100644
--- a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.expect
@@ -106,5 +106,5 @@
- D. (from org-dartlang-testcase:///switch_redesign_types.dart:23:9)
- B. (from org-dartlang-testcase:///switch_redesign_types.dart:15:9)
- A. (from org-dartlang-testcase:///switch_redesign_types.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- C. (from org-dartlang-testcase:///switch_redesign_types.dart:19:9)
diff --git a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.transformed.expect
index 1108882..0d7d320 100644
--- a/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd/switch_redesign_types.dart.weak.transformed.expect
@@ -106,5 +106,5 @@
- D. (from org-dartlang-testcase:///switch_redesign_types.dart:23:9)
- B. (from org-dartlang-testcase:///switch_redesign_types.dart:15:9)
- A. (from org-dartlang-testcase:///switch_redesign_types.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- C. (from org-dartlang-testcase:///switch_redesign_types.dart:19:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.expect
index 86644a3..420216c 100644
--- a/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.expect
@@ -128,7 +128,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:42:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.transformed.expect
index eb05763..8761b15 100644
--- a/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/constant_null_is.dart.weak.transformed.expect
@@ -147,7 +147,7 @@
Constructor coverage from constants:
org-dartlang-testcase:///constant_null_is.dart:
- Class.constructor1 (from org-dartlang-testcase:///constant_null_is.dart:39:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class.constructor2 (from org-dartlang-testcase:///constant_null_is.dart:40:9)
- Class.constructor3 (from org-dartlang-testcase:///constant_null_is.dart:41:9)
- Class.constructor4 (from org-dartlang-testcase:///constant_null_is.dart:42:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.expect
index 8c498ea..584622a 100644
--- a/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.expect
@@ -103,5 +103,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:10:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:10:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.transformed.expect
index 8c498ea..584622a 100644
--- a/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/constants.dart.weak.transformed.expect
@@ -103,5 +103,5 @@
- Class. (from org-dartlang-testcase:///constants_lib.dart:10:9)
org-dartlang-testcase:///constants_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class. (from org-dartlang-testcase:///constants_lib.dart:10:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.expect
index f674165..113b863 100644
--- a/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.expect
@@ -43,4 +43,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///literal_from_opt_in_lib.dart:
- Const. (from org-dartlang-testcase:///literal_from_opt_in_lib.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.transformed.expect
index f674165..113b863 100644
--- a/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/literal_from_opt_in.dart.weak.transformed.expect
@@ -43,4 +43,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///literal_from_opt_in_lib.dart:
- Const. (from org-dartlang-testcase:///literal_from_opt_in_lib.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.expect
index 0b8191f..0068d5e 100644
--- a/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.expect
@@ -134,7 +134,7 @@
- Class5._ (from org-dartlang-testcase:///opt_in_lib.dart:42:9)
org-dartlang-testcase:///opt_in_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class1._ (from org-dartlang-testcase:///opt_in_lib.dart:10:9)
- Class2._ (from org-dartlang-testcase:///opt_in_lib.dart:18:9)
- Class3._ (from org-dartlang-testcase:///opt_in_lib.dart:26:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.transformed.expect
index 5e2ac0e..7bad5d6 100644
--- a/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/object_bound_factory/main.dart.weak.transformed.expect
@@ -134,7 +134,7 @@
- Class5._ (from org-dartlang-testcase:///opt_in_lib.dart:42:9)
org-dartlang-testcase:///opt_in_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- Class1._ (from org-dartlang-testcase:///opt_in_lib.dart:10:9)
- Class2._ (from org-dartlang-testcase:///opt_in_lib.dart:18:9)
- Class3._ (from org-dartlang-testcase:///opt_in_lib.dart:26:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.expect
index c6752be..f9e81d9 100644
--- a/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.expect
@@ -98,4 +98,4 @@
org-dartlang-testcase:///opt_in_lib.dart:
- P._ (from org-dartlang-testcase:///opt_in_lib.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.transformed.expect
index 8534130..a8f6383 100644
--- a/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/object_bound_redirecting_factory/main.dart.weak.transformed.expect
@@ -98,4 +98,4 @@
org-dartlang-testcase:///opt_in_lib.dart:
- P._ (from org-dartlang-testcase:///opt_in_lib.dart:8:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.expect b/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.expect
index 7e7f78f..a7fa278 100644
--- a/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.expect
@@ -624,4 +624,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///unsound_checks_lib.dart:
- E. (from org-dartlang-testcase:///unsound_checks_lib.dart:145:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.transformed.expect b/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.transformed.expect
index b6a0853..7656f90 100644
--- a/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/nnbd_mixed/unsound_checks.dart.weak.transformed.expect
@@ -645,4 +645,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///unsound_checks_lib.dart:
- E. (from org-dartlang-testcase:///unsound_checks_lib.dart:145:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/enum.dart.strong.expect b/pkg/front_end/testcases/rasta/enum.dart.strong.expect
index 697f145..0a4e983 100644
--- a/pkg/front_end/testcases/rasta/enum.dart.strong.expect
+++ b/pkg/front_end/testcases/rasta/enum.dart.strong.expect
@@ -39,4 +39,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///enum.dart:
- Foo. (from org-dartlang-testcase:///enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/enum.dart.strong.transformed.expect b/pkg/front_end/testcases/rasta/enum.dart.strong.transformed.expect
index 697f145..0a4e983 100644
--- a/pkg/front_end/testcases/rasta/enum.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/rasta/enum.dart.strong.transformed.expect
@@ -39,4 +39,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///enum.dart:
- Foo. (from org-dartlang-testcase:///enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/issue_000044.dart.strong.expect b/pkg/front_end/testcases/rasta/issue_000044.dart.strong.expect
index 946925a..24463fa 100644
--- a/pkg/front_end/testcases/rasta/issue_000044.dart.strong.expect
+++ b/pkg/front_end/testcases/rasta/issue_000044.dart.strong.expect
@@ -115,4 +115,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_000044.dart:
- C.constant (from org-dartlang-testcase:///issue_000044.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/issue_000044.dart.strong.transformed.expect b/pkg/front_end/testcases/rasta/issue_000044.dart.strong.transformed.expect
index eec7e67..1adf6a4 100644
--- a/pkg/front_end/testcases/rasta/issue_000044.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/rasta/issue_000044.dart.strong.transformed.expect
@@ -115,4 +115,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_000044.dart:
- C.constant (from org-dartlang-testcase:///issue_000044.dart:11:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/issue_000070.dart.strong.expect b/pkg/front_end/testcases/rasta/issue_000070.dart.strong.expect
index f3f37e7..fcbc6d2 100644
--- a/pkg/front_end/testcases/rasta/issue_000070.dart.strong.expect
+++ b/pkg/front_end/testcases/rasta/issue_000070.dart.strong.expect
@@ -74,4 +74,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_000070.dart:
- A.c (from org-dartlang-testcase:///issue_000070.dart:22:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/rasta/issue_000070.dart.strong.transformed.expect b/pkg/front_end/testcases/rasta/issue_000070.dart.strong.transformed.expect
index 6240e38..41a034d 100644
--- a/pkg/front_end/testcases/rasta/issue_000070.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/rasta/issue_000070.dart.strong.transformed.expect
@@ -74,4 +74,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_000070.dart:
- A.c (from org-dartlang-testcase:///issue_000070.dart:22:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/regress/issue_34403.dart.strong.expect b/pkg/front_end/testcases/regress/issue_34403.dart.strong.expect
index 13c8d12..d4c306b 100644
--- a/pkg/front_end/testcases/regress/issue_34403.dart.strong.expect
+++ b/pkg/front_end/testcases/regress/issue_34403.dart.strong.expect
@@ -192,8 +192,8 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_34403.dart:
- D.foo (from org-dartlang-testcase:///issue_34403.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- F.foo (from org-dartlang-testcase:///issue_34403_lib.dart:10:9)
org-dartlang-testcase:///issue_34403_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/regress/issue_34403.dart.strong.transformed.expect b/pkg/front_end/testcases/regress/issue_34403.dart.strong.transformed.expect
index 13c8d12..d4c306b 100644
--- a/pkg/front_end/testcases/regress/issue_34403.dart.strong.transformed.expect
+++ b/pkg/front_end/testcases/regress/issue_34403.dart.strong.transformed.expect
@@ -192,8 +192,8 @@
Constructor coverage from constants:
org-dartlang-testcase:///issue_34403.dart:
- D.foo (from org-dartlang-testcase:///issue_34403.dart:12:9)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
- F.foo (from org-dartlang-testcase:///issue_34403_lib.dart:10:9)
org-dartlang-testcase:///issue_34403_lib.dart:
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.expect b/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.expect
index cc542ab..0077a85 100644
--- a/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.expect
+++ b/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.expect
@@ -30,4 +30,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///enum.dart:
- A. (from org-dartlang-testcase:///enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.transformed.expect b/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.transformed.expect
index cc542ab..0077a85 100644
--- a/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.transformed.expect
+++ b/pkg/front_end/testcases/static_field_lowering/enum.dart.weak.transformed.expect
@@ -30,4 +30,4 @@
Constructor coverage from constants:
org-dartlang-testcase:///enum.dart:
- A. (from org-dartlang-testcase:///enum.dart:5:6)
-- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:31:9)
+- Object. (from org-dartlang-sdk:///sdk/lib/core/object.dart:25:9)
diff --git a/sdk/lib/core/annotations.dart b/sdk/lib/core/annotations.dart
index ec9c489..dcfa5e0 100644
--- a/sdk/lib/core/annotations.dart
+++ b/sdk/lib/core/annotations.dart
@@ -4,71 +4,76 @@
part of dart.core;
-/**
- * The annotation `@Deprecated('migration')` marks a feature as deprecated.
- *
- * The annotation [deprecated] is a shorthand for deprecating until
- * an unspecified "next release" without migration instructions.
- *
- * The intent of the `@Deprecated` annotation is to inform users of a feature
- * that they should change their code, even if it is currently still working
- * correctly.
- *
- * A deprecated feature is scheduled to be removed at a later time, possibly
- * specified in [message]. A deprecated feature should not be used, code using
- * it will break at some point in the future. If existing code is using the
- * feature it should be rewritten to not use the deprecated feature.
- *
- * A deprecated feature should document how the same effect can be achieved in
- * [message], so the programmer knows how to rewrite the code.
- *
- * The `@Deprecated` annotation applies to libraries, top-level declarations
- * (variables, getters, setters, functions, classes and typedefs),
- * class-level declarations (variables, getters, setters, methods, operators or
- * constructors, whether static or not), named optional arguments and
- * trailing optional positional parameters.
- *
- * Deprecation is transitive:
- *
- * - If a library is deprecated, so is every member of it.
- * - If a class is deprecated, so is every member of it.
- * - If a variable is deprecated, so are its implicit getter and setter.
- *
- *
- * A tool that processes Dart source code may report when:
- *
- * - the code imports a deprecated library.
- * - the code exports a deprecated library, or any deprecated member of
- * a non-deprecated library.
- * - the code refers statically to a deprecated declaration.
- * - the code dynamically uses a member of an object with a statically known
- * type, where the member is deprecated on the static type of the object.
- * - the code dynamically calls a method with an argument where the
- * corresponding optional parameter is deprecated on the object's static type.
- *
- *
- * If the deprecated use is inside a library, class or method which is itself
- * deprecated, the tool should not bother the user about it.
- * A deprecated feature is expected to use other deprecated features.
- */
+/// The annotation `@Deprecated('migration')` marks a feature as deprecated.
+///
+/// The annotation [deprecated] is a shorthand for deprecating until
+/// an unspecified "next release" without migration instructions.
+///
+/// A feature can be any part of an API, from a full library to a single
+/// parameter.
+///
+/// The intent of the `@Deprecated` annotation is to inform authors
+/// who are currently using the feature,
+/// that they will soon need to stop using that feature in their code,
+/// even if the feature is currently still working correctly.
+///
+/// Deprecation is an early warning that the deprecated feature
+/// is scheduled to be removed at a later time,
+/// a time possibly specified in [message].
+/// A deprecated feature should no longer be used,
+/// code using it will break at some point in the future.
+/// If existing code is using the feature,
+/// that code should be rewritten to no longer use the deprecated feature.
+///
+/// A deprecated feature should document how the same effect can be achieved in
+/// [message], so the programmer knows how to rewrite the code.
+///
+/// The `@Deprecated` annotation applies to libraries, top-level declarations
+/// (variables, getters, setters, functions, classes, mixins,
+/// extension and typedefs),
+/// class-level declarations (variables, getters, setters, methods, operators or
+/// constructors, whether static or not), named optional parameters and
+/// trailing optional positional parameters.
+///
+/// Deprecation applies transitively to parts of a deprecated feature:
+///
+/// - If a library is deprecated, so is every member of it.
+/// - If a class is deprecated, so is every member of it.
+/// - If a variable is deprecated, so are its implicit getter and setter.
+///
+/// If a feature is deprecated in a superclass, it is *not* automatically
+/// deprecated in a subclass as well. It is reasonable to remove a member
+/// from a superclass and retain it in a subclass, so it needs to be possible
+/// to deprecate the member only in the superclass.
+///
+/// A tool that processes Dart source code may report when:
+///
+/// - the code imports a deprecated library.
+/// - the code exports a deprecated library, or any deprecated member of
+/// a non-deprecated library.
+/// - the code refers statically to a deprecated declaration.
+/// - the code uses a member of an object with a statically known
+/// type, where the member is deprecated on the interface of the static type.
+/// - the code calls a method with an argument where the
+/// corresponding optional parameter is deprecated on the object's static type.
+///
+/// If the deprecated use is inside a library, class or method which is itself
+/// deprecated, the tool should not bother the user about it.
+/// A deprecated feature is expected to use other deprecated features.
class Deprecated {
- /**
- * Message provided to the user when they use the deprecated feature.
- *
- * The message should explain how to migrate away from the feature if an
- * alternative is available, and when the deprecated feature is expected to be
- * removed.
- */
+ /// Message provided to the user when they use the deprecated feature.
+ ///
+ /// The message should explain how to migrate away from the feature if an
+ /// alternative is available, and when the deprecated feature is expected to be
+ /// removed.
final String message;
- /**
- * Create a deprecation annotation which specifies the migration path and
- * expiration of the annotated feature.
- *
- * The [message] argument should be readable by programmers, and should state
- * an alternative feature (if available) as well as when an annotated feature
- * is expected to be removed.
- */
+ /// Create a deprecation annotation which specifies the migration path and
+ /// expiration of the annotated feature.
+ ///
+ /// The [message] argument should be readable by programmers, and should state
+ /// an alternative feature (if available) as well as when an annotated feature
+ /// is expected to be removed.
const Deprecated(this.message);
@Deprecated('Use `message` instead. Will be removed in Dart 3.0.0')
@@ -77,9 +82,7 @@
String toString() => "Deprecated feature: $message";
}
-/**
- * Marks a feature as [Deprecated] until the next release.
- */
+/// Marks a feature as [Deprecated] until the next release.
const Deprecated deprecated = Deprecated("next release");
class _Override {
@@ -114,22 +117,18 @@
/// can be used to enable more warnings based on `@override` annotations.
const Object override = _Override();
-/**
- * An annotation class that was used during development of Dart 2.
- *
- * Should not be used any more.
- */
+/// An annotation class that was used during development of Dart 2.
+///
+/// Should not be used any more.
@deprecated
class Provisional {
String? get message => null;
const Provisional({String? message});
}
-/**
- * An annotation that was used during development of Dart 2.
- *
- * The annotation has no effect, and will be removed.
- */
+/// An annotation that was used during development of Dart 2.
+///
+/// The annotation has no effect, and will be removed.
@deprecated
const Null provisional = null;
@@ -139,55 +138,51 @@
@deprecated
const Null proxy = null;
-/**
- * A hint to tools.
- *
- * Tools that work with Dart programs may accept hints to guide their behavior
- * as `pragma` annotations on declarations.
- * Each tool decides which hints it accepts, what they mean, and whether and
- * how they apply to sub-parts of the annotated entity.
- *
- * Tools that recognize pragma hints should pick a pragma prefix to identify
- * the tool. They should recognize any hint with a [name] starting with their
- * prefix followed by `:` as if it was intended for that tool. A hint with a
- * prefix for another tool should be ignored (unless compatibility with that
- * other tool is a goal).
- *
- * A tool may recognize unprefixed names as well, if they would recognize that
- * name with their own prefix in front.
- *
- * If the hint can be parameterized,
- * an extra [options] object can be added as well.
- *
- * For example:
- *
- * ```dart
- * @pragma('Tool:pragma-name', [param1, param2, ...])
- * class Foo { }
- *
- * @pragma('OtherTool:other-pragma')
- * void foo() { }
- * ```
- *
- * Here class `Foo` is annotated with a Tool specific pragma 'pragma-name' and
- * function `foo` is annotated with a pragma 'other-pragma'
- * specific to OtherTool.
- */
+/// A hint to tools.
+///
+/// Tools that work with Dart programs may accept hints to guide their behavior
+/// as `pragma` annotations on declarations.
+/// Each tool decides which hints it accepts, what they mean, and whether and
+/// how they apply to sub-parts of the annotated entity.
+///
+/// Tools that recognize pragma hints should pick a pragma prefix to identify
+/// the tool. They should recognize any hint with a [name] starting with their
+/// prefix followed by `:` as if it was intended for that tool. A hint with a
+/// prefix for another tool should be ignored (unless compatibility with that
+/// other tool is a goal).
+///
+/// A tool may recognize unprefixed names as well, if they would recognize that
+/// name with their own prefix in front.
+///
+/// If the hint can be parameterized,
+/// an extra [options] object can be added as well.
+///
+/// For example:
+///
+/// ```dart
+/// @pragma('Tool:pragma-name', [param1, param2, ...])
+/// class Foo { }
+///
+/// @pragma('OtherTool:other-pragma')
+/// void foo() { }
+/// ```
+///
+/// Here class `Foo` is annotated with a Tool specific pragma 'pragma-name' and
+/// function `foo` is annotated with a pragma 'other-pragma'
+/// specific to OtherTool.
@pragma('vm:entry-point')
class pragma {
- /**
- * The name of the hint.
- *
- * A string that is recognized by one or more tools, or such a string prefixed
- * by a tool identifier and a colon, which is only recognized by that
- * particular tool.
- */
+ /// The name of the hint.
+ ///
+ /// A string that is recognized by one or more tools, or such a string prefixed
+ /// by a tool identifier and a colon, which is only recognized by that
+ /// particular tool.
final String name;
- /** Optional extra data parameterizing the hint. */
+ /// Optional extra data parameterizing the hint.
final Object? options;
- /** Creates a hint named [name] with optional [options]. */
+ /// Creates a hint named [name] with optional [options].
const factory pragma(String name, [Object? options]) = pragma._;
const pragma._(this.name, [this.options]);
diff --git a/sdk/lib/core/bigint.dart b/sdk/lib/core/bigint.dart
index 94a9445..25c0476 100644
--- a/sdk/lib/core/bigint.dart
+++ b/sdk/lib/core/bigint.dart
@@ -4,64 +4,54 @@
part of dart.core;
-/**
- * An arbitrarily large integer.
- */
+/// An arbitrarily large integer.
abstract class BigInt implements Comparable<BigInt> {
external static BigInt get zero;
external static BigInt get one;
external static BigInt get two;
- /**
- * Parses [source] as a, possibly signed, integer literal and returns its
- * value.
- *
- * The [source] must be a non-empty sequence of base-[radix] digits,
- * optionally prefixed with a minus or plus sign ('-' or '+').
- *
- * The [radix] must be in the range 2..36. The digits used are
- * first the decimal digits 0..9, and then the letters 'a'..'z' with
- * values 10 through 35. Also accepts upper-case letters with the same
- * values as the lower-case ones.
- *
- * If no [radix] is given then it defaults to 10. In this case, the [source]
- * digits may also start with `0x`, in which case the number is interpreted
- * as a hexadecimal literal, which effectively means that the `0x` is ignored
- * and the radix is instead set to 16.
- *
- * For any int `n` and radix `r`, it is guaranteed that
- * `n == int.parse(n.toRadixString(r), radix: r)`.
- *
- * Throws a [FormatException] if the [source] is not a valid integer literal,
- * optionally prefixed by a sign.
- */
+ /// Parses [source] as a, possibly signed, integer literal and returns its
+ /// value.
+ ///
+ /// The [source] must be a non-empty sequence of base-[radix] digits,
+ /// optionally prefixed with a minus or plus sign ('-' or '+').
+ ///
+ /// The [radix] must be in the range 2..36. The digits used are
+ /// first the decimal digits 0..9, and then the letters 'a'..'z' with
+ /// values 10 through 35. Also accepts upper-case letters with the same
+ /// values as the lower-case ones.
+ ///
+ /// If no [radix] is given then it defaults to 10. In this case, the [source]
+ /// digits may also start with `0x`, in which case the number is interpreted
+ /// as a hexadecimal literal, which effectively means that the `0x` is ignored
+ /// and the radix is instead set to 16.
+ ///
+ /// For any int `n` and radix `r`, it is guaranteed that
+ /// `n == int.parse(n.toRadixString(r), radix: r)`.
+ ///
+ /// Throws a [FormatException] if the [source] is not a valid integer literal,
+ /// optionally prefixed by a sign.
external static BigInt parse(String source, {int? radix});
- /**
- * Parses [source] as a, possibly signed, integer literal and returns its
- * value.
- *
- * As [parse] except that this method returns `null` if the input is not
- * valid
- */
+ /// Parses [source] as a, possibly signed, integer literal and returns its
+ /// value.
+ ///
+ /// As [parse] except that this method returns `null` if the input is not
+ /// valid
external static BigInt? tryParse(String source, {int? radix});
/// Allocates a big integer from the provided [value] number.
external factory BigInt.from(num value);
- /**
- * Returns the absolute value of this integer.
- *
- * For any integer `x`, the result is the same as `x < 0 ? -x : x`.
- */
+ /// Returns the absolute value of this integer.
+ ///
+ /// For any integer `x`, the result is the same as `x < 0 ? -x : x`.
BigInt abs();
- /**
- * Return the negative value of this integer.
- *
- * The result of negating an integer always has the opposite sign, except
- * for zero, which is its own negation.
- */
+ /// Return the negative value of this integer.
+ ///
+ /// The result of negating an integer always has the opposite sign, except
+ /// for zero, which is its own negation.
BigInt operator -();
/// Addition operator.
@@ -76,171 +66,147 @@
/// Division operator.
double operator /(BigInt other);
- /**
- * Truncating division operator.
- *
- * Performs a truncating integer division, where the remainder is discarded.
- *
- * The remainder can be computed using the [remainder] method.
- *
- * Examples:
- * ```
- * var seven = new BigInt.from(7);
- * var three = new BigInt.from(3);
- * seven ~/ three; // => 2
- * (-seven) ~/ three; // => -2
- * seven ~/ -three; // => -2
- * seven.remainder(three); // => 1
- * (-seven).remainder(three); // => -1
- * seven.remainder(-three); // => 1
- * ```
- */
+ /// Truncating division operator.
+ ///
+ /// Performs a truncating integer division, where the remainder is discarded.
+ ///
+ /// The remainder can be computed using the [remainder] method.
+ ///
+ /// Examples:
+ /// ```
+ /// var seven = BigInt.from(7);
+ /// var three = BigInt.from(3);
+ /// seven ~/ three; // => 2
+ /// (-seven) ~/ three; // => -2
+ /// seven ~/ -three; // => -2
+ /// seven.remainder(three); // => 1
+ /// (-seven).remainder(three); // => -1
+ /// seven.remainder(-three); // => 1
+ /// ```
BigInt operator ~/(BigInt other);
- /**
- * Euclidean modulo operator.
- *
- * Returns the remainder of the Euclidean division. The Euclidean division of
- * two integers `a` and `b` yields two integers `q` and `r` such that
- * `a == b * q + r` and `0 <= r < b.abs()`.
- *
- * The sign of the returned value `r` is always positive.
- *
- * See [remainder] for the remainder of the truncating division.
- */
+ /// Euclidean modulo operator.
+ ///
+ /// Returns the remainder of the Euclidean division. The Euclidean division of
+ /// two integers `a` and `b` yields two integers `q` and `r` such that
+ /// `a == b * q + r` and `0 <= r < b.abs()`.
+ ///
+ /// The sign of the returned value `r` is always positive.
+ ///
+ /// See [remainder] for the remainder of the truncating division.
BigInt operator %(BigInt other);
- /**
- * Returns the remainder of the truncating division of `this` by [other].
- *
- * The result `r` of this operation satisfies:
- * `this == (this ~/ other) * other + r`.
- * As a consequence the remainder `r` has the same sign as the divider `this`.
- */
+ /// Returns the remainder of the truncating division of `this` by [other].
+ ///
+ /// The result `r` of this operation satisfies:
+ /// `this == (this ~/ other) * other + r`.
+ /// As a consequence the remainder `r` has the same sign as the divider `this`.
BigInt remainder(BigInt other);
- /**
- * Shift the bits of this integer to the left by [shiftAmount].
- *
- * Shifting to the left makes the number larger, effectively multiplying
- * the number by `pow(2, shiftIndex)`.
- *
- * There is no limit on the size of the result. It may be relevant to
- * limit intermediate values by using the "and" operator with a suitable
- * mask.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the left by [shiftAmount].
+ ///
+ /// Shifting to the left makes the number larger, effectively multiplying
+ /// the number by `pow(2, shiftIndex)`.
+ ///
+ /// There is no limit on the size of the result. It may be relevant to
+ /// limit intermediate values by using the "and" operator with a suitable
+ /// mask.
+ ///
+ /// It is an error if [shiftAmount] is negative.
BigInt operator <<(int shiftAmount);
- /**
- * Shift the bits of this integer to the right by [shiftAmount].
- *
- * Shifting to the right makes the number smaller and drops the least
- * significant bits, effectively doing an integer division by
- *`pow(2, shiftIndex)`.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the right by [shiftAmount].
+ ///
+ /// Shifting to the right makes the number smaller and drops the least
+ /// significant bits, effectively doing an integer division by
+ ///`pow(2, shiftIndex)`.
+ ///
+ /// It is an error if [shiftAmount] is negative.
BigInt operator >>(int shiftAmount);
- /**
- * Bit-wise and operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with only the bits set that are set in
- * both `this` and [other]
- *
- * Of both operands are negative, the result is negative, otherwise
- * the result is non-negative.
- */
+ /// Bit-wise and operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with only the bits set that are set in
+ /// both `this` and [other]
+ ///
+ /// Of both operands are negative, the result is negative, otherwise
+ /// the result is non-negative.
BigInt operator &(BigInt other);
- /**
- * Bit-wise or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in either
- * of `this` and [other]
- *
- * If both operands are non-negative, the result is non-negative,
- * otherwise the result us negative.
- */
+ /// Bit-wise or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in either
+ /// of `this` and [other]
+ ///
+ /// If both operands are non-negative, the result is non-negative,
+ /// otherwise the result us negative.
BigInt operator |(BigInt other);
- /**
- * Bit-wise exclusive-or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in one,
- * but not both, of `this` and [other]
- *
- * If the operands have the same sign, the result is non-negative,
- * otherwise the result is negative.
- */
+ /// Bit-wise exclusive-or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in one,
+ /// but not both, of `this` and [other]
+ ///
+ /// If the operands have the same sign, the result is non-negative,
+ /// otherwise the result is negative.
BigInt operator ^(BigInt other);
- /**
- * The bit-wise negate operator.
- *
- * Treating `this` as a sufficiently large two's component integer,
- * the result is a number with the opposite bits set.
- *
- * This maps any integer `x` to `-x - 1`.
- */
+ /// The bit-wise negate operator.
+ ///
+ /// Treating `this` as a sufficiently large two's component integer,
+ /// the result is a number with the opposite bits set.
+ ///
+ /// This maps any integer `x` to `-x - 1`.
BigInt operator ~();
- /** Relational less than operator. */
+ /// Relational less than operator.
bool operator <(BigInt other);
- /** Relational less than or equal operator. */
+ /// Relational less than or equal operator.
bool operator <=(BigInt other);
- /** Relational greater than operator. */
+ /// Relational greater than operator.
bool operator >(BigInt other);
- /** Relational greater than or equal operator. */
+ /// Relational greater than or equal operator.
bool operator >=(BigInt other);
- /**
- * Compares this to `other`.
- *
- * Returns a negative number if `this` is less than `other`, zero if they are
- * equal, and a positive number if `this` is greater than `other`.
- */
+ /// Compares this to `other`.
+ ///
+ /// Returns a negative number if `this` is less than `other`, zero if they are
+ /// equal, and a positive number if `this` is greater than `other`.
int compareTo(BigInt other);
- /**
- * Returns the minimum number of bits required to store this big integer.
- *
- * The number of bits excludes the sign bit, which gives the natural length
- * for non-negative (unsigned) values. Negative values are complemented to
- * return the bit position of the first bit that differs from the sign bit.
- *
- * To find the number of bits needed to store the value as a signed value,
- * add one, i.e. use `x.bitLength + 1`.
- *
- * ```
- * x.bitLength == (-x-1).bitLength
- *
- * new BigInt.from(3).bitLength == 2; // 00000011
- * new BigInt.from(2).bitLength == 2; // 00000010
- * new BigInt.from(1).bitLength == 1; // 00000001
- * new BigInt.from(0).bitLength == 0; // 00000000
- * new BigInt.from(-1).bitLength == 0; // 11111111
- * new BigInt.from(-2).bitLength == 1; // 11111110
- * new BigInt.from(-3).bitLength == 2; // 11111101
- * new BigInt.from(-4).bitLength == 2; // 11111100
- * ```
- */
+ /// Returns the minimum number of bits required to store this big integer.
+ ///
+ /// The number of bits excludes the sign bit, which gives the natural length
+ /// for non-negative (unsigned) values. Negative values are complemented to
+ /// return the bit position of the first bit that differs from the sign bit.
+ ///
+ /// To find the number of bits needed to store the value as a signed value,
+ /// add one, i.e. use `x.bitLength + 1`.
+ ///
+ /// ```
+ /// x.bitLength == (-x-1).bitLength
+ ///
+ /// BigInt.from(3).bitLength == 2; // 00000011
+ /// BigInt.from(2).bitLength == 2; // 00000010
+ /// BigInt.from(1).bitLength == 1; // 00000001
+ /// BigInt.from(0).bitLength == 0; // 00000000
+ /// BigInt.from(-1).bitLength == 0; // 11111111
+ /// BigInt.from(-2).bitLength == 1; // 11111110
+ /// BigInt.from(-3).bitLength == 2; // 11111101
+ /// BigInt.from(-4).bitLength == 2; // 11111100
+ /// ```
int get bitLength;
- /**
- * Returns the sign of this big integer.
- *
- * Returns 0 for zero, -1 for values less than zero and
- * +1 for values greater than zero.
- */
+ /// Returns the sign of this big integer.
+ ///
+ /// Returns 0 for zero, -1 for values less than zero and
+ /// +1 for values greater than zero.
int get sign;
/// Whether this big integer is even.
@@ -252,163 +218,141 @@
/// Whether this number is negative.
bool get isNegative;
- /**
- * Returns `this` to the power of [exponent].
- *
- * Returns [one] if the [exponent] equals 0.
- *
- * The [exponent] must otherwise be positive.
- *
- * The result is always equal to the mathematical result of this to the power
- * [exponent], only limited by the available memory.
- */
+ /// Returns `this` to the power of [exponent].
+ ///
+ /// Returns [one] if the [exponent] equals 0.
+ ///
+ /// The [exponent] must otherwise be positive.
+ ///
+ /// The result is always equal to the mathematical result of this to the power
+ /// [exponent], only limited by the available memory.
BigInt pow(int exponent);
- /**
- * Returns this integer to the power of [exponent] modulo [modulus].
- *
- * The [exponent] must be non-negative and [modulus] must be
- * positive.
- */
+ /// Returns this integer to the power of [exponent] modulo [modulus].
+ ///
+ /// The [exponent] must be non-negative and [modulus] must be
+ /// positive.
BigInt modPow(BigInt exponent, BigInt modulus);
- /**
- * Returns the modular multiplicative inverse of this big integer
- * modulo [modulus].
- *
- * The [modulus] must be positive.
- *
- * It is an error if no modular inverse exists.
- */
+ /// Returns the modular multiplicative inverse of this big integer
+ /// modulo [modulus].
+ ///
+ /// The [modulus] must be positive.
+ ///
+ /// It is an error if no modular inverse exists.
// Returns 1/this % modulus, with modulus > 0.
BigInt modInverse(BigInt modulus);
- /**
- * Returns the greatest common divisor of this big integer and [other].
- *
- * If either number is non-zero, the result is the numerically greatest
- * integer dividing both `this` and `other`.
- *
- * The greatest common divisor is independent of the order,
- * so `x.gcd(y)` is always the same as `y.gcd(x)`.
- *
- * For any integer `x`, `x.gcd(x)` is `x.abs()`.
- *
- * If both `this` and `other` is zero, the result is also zero.
- */
+ /// Returns the greatest common divisor of this big integer and [other].
+ ///
+ /// If either number is non-zero, the result is the numerically greatest
+ /// integer dividing both `this` and `other`.
+ ///
+ /// The greatest common divisor is independent of the order,
+ /// so `x.gcd(y)` is always the same as `y.gcd(x)`.
+ ///
+ /// For any integer `x`, `x.gcd(x)` is `x.abs()`.
+ ///
+ /// If both `this` and `other` is zero, the result is also zero.
BigInt gcd(BigInt other);
- /**
- * Returns the least significant [width] bits of this big integer as a
- * non-negative number (i.e. unsigned representation). The returned value has
- * zeros in all bit positions higher than [width].
- *
- * ```
- * new BigInt.from(-1).toUnsigned(5) == 31 // 11111111 -> 00011111
- * ```
- *
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit quantity:
- *
- * ```
- * q = (q + 1).toUnsigned(8);
- * ```
- *
- * `q` will count from `0` up to `255` and then wrap around to `0`.
- *
- * If the input fits in [width] bits without truncation, the result is the
- * same as the input. The minimum width needed to avoid truncation of `x` is
- * given by `x.bitLength`, i.e.
- *
- * ```
- * x == x.toUnsigned(x.bitLength);
- * ```
- */
+ /// Returns the least significant [width] bits of this big integer as a
+ /// non-negative number (i.e. unsigned representation). The returned value has
+ /// zeros in all bit positions higher than [width].
+ ///
+ /// ```
+ /// BigInt.from(-1).toUnsigned(5) == 31 // 11111111 -> 00011111
+ /// ```
+ ///
+ /// This operation can be used to simulate arithmetic from low level languages.
+ /// For example, to increment an 8 bit quantity:
+ ///
+ /// ```
+ /// q = (q + 1).toUnsigned(8);
+ /// ```
+ ///
+ /// `q` will count from `0` up to `255` and then wrap around to `0`.
+ ///
+ /// If the input fits in [width] bits without truncation, the result is the
+ /// same as the input. The minimum width needed to avoid truncation of `x` is
+ /// given by `x.bitLength`, i.e.
+ ///
+ /// ```
+ /// x == x.toUnsigned(x.bitLength);
+ /// ```
BigInt toUnsigned(int width);
- /**
- * Returns the least significant [width] bits of this integer, extending the
- * highest retained bit to the sign. This is the same as truncating the value
- * to fit in [width] bits using an signed 2-s complement representation. The
- * returned value has the same bit value in all positions higher than [width].
- *
- * ```
- * var big15 = new BigInt.from(15);
- * var big16 = new BigInt.from(16);
- * var big239 = new BigInt.from(239);
- * V--sign bit-V
- * big16.toSigned(5) == -big16 // 00010000 -> 11110000
- * big239.toSigned(5) == big15 // 11101111 -> 00001111
- * ^ ^
- * ```
- *
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit signed quantity:
- *
- * ```
- * q = (q + 1).toSigned(8);
- * ```
- *
- * `q` will count from `0` up to `127`, wrap to `-128` and count back up to
- * `127`.
- *
- * If the input value fits in [width] bits without truncation, the result is
- * the same as the input. The minimum width needed to avoid truncation of `x`
- * is `x.bitLength + 1`, i.e.
- *
- * ```
- * x == x.toSigned(x.bitLength + 1);
- * ```
- */
+ /// Returns the least significant [width] bits of this integer, extending the
+ /// highest retained bit to the sign. This is the same as truncating the value
+ /// to fit in [width] bits using an signed 2-s complement representation. The
+ /// returned value has the same bit value in all positions higher than [width].
+ ///
+ /// ```
+ /// var big15 = BigInt.from(15);
+ /// var big16 = BigInt.from(16);
+ /// var big239 = BigInt.from(239);
+ /// V--sign bit-V
+ /// big16.toSigned(5) == -big16 // 00010000 -> 11110000
+ /// big239.toSigned(5) == big15 // 11101111 -> 00001111
+ /// ^ ^
+ /// ```
+ ///
+ /// This operation can be used to simulate arithmetic from low level languages.
+ /// For example, to increment an 8 bit signed quantity:
+ ///
+ /// ```
+ /// q = (q + 1).toSigned(8);
+ /// ```
+ ///
+ /// `q` will count from `0` up to `127`, wrap to `-128` and count back up to
+ /// `127`.
+ ///
+ /// If the input value fits in [width] bits without truncation, the result is
+ /// the same as the input. The minimum width needed to avoid truncation of `x`
+ /// is `x.bitLength + 1`, i.e.
+ ///
+ /// ```
+ /// x == x.toSigned(x.bitLength + 1);
+ /// ```
BigInt toSigned(int width);
- /**
- * Whether this big integer can be represented as an `int` without losing
- * precision.
- *
- * Warning: this function may give a different result on
- * dart2js, dev compiler, and the VM, due to the differences in
- * integer precision.
- */
+ /// Whether this big integer can be represented as an `int` without losing
+ /// precision.
+ ///
+ /// Warning: this function may give a different result on
+ /// dart2js, dev compiler, and the VM, due to the differences in
+ /// integer precision.
bool get isValidInt;
- /**
- * Returns this [BigInt] as an [int].
- *
- * If the number does not fit, clamps to the max (or min)
- * integer.
- *
- * Warning: the clamping behaves differently on dart2js, dev
- * compiler, and the VM, due to the differences in integer
- * precision.
- */
+ /// Returns this [BigInt] as an [int].
+ ///
+ /// If the number does not fit, clamps to the max (or min)
+ /// integer.
+ ///
+ /// Warning: the clamping behaves differently on dart2js, dev
+ /// compiler, and the VM, due to the differences in integer
+ /// precision.
int toInt();
- /**
- * Returns this [BigInt] as a [double].
- *
- * If the number is not representable as a [double], an
- * approximation is returned. For numerically large integers, the
- * approximation may be infinite.
- */
+ /// Returns this [BigInt] as a [double].
+ ///
+ /// If the number is not representable as a [double], an
+ /// approximation is returned. For numerically large integers, the
+ /// approximation may be infinite.
double toDouble();
- /**
- * Returns a String-representation of this integer.
- *
- * The returned string is parsable by [parse].
- * For any `BigInt` `i`, it is guaranteed that
- * `i == BigInt.parse(i.toString())`.
- */
+ /// Returns a String-representation of this integer.
+ ///
+ /// The returned string is parsable by [parse].
+ /// For any `BigInt` `i`, it is guaranteed that
+ /// `i == BigInt.parse(i.toString())`.
String toString();
- /**
- * Converts [this] to a string representation in the given [radix].
- *
- * In the string representation, lower-case letters are used for digits above
- * '9', with 'a' being 10 an 'z' being 35.
- *
- * The [radix] argument must be an integer in the range 2 to 36.
- */
+ /// Converts [this] to a string representation in the given [radix].
+ ///
+ /// In the string representation, lower-case letters are used for digits above
+ /// '9', with 'a' being 10 an 'z' being 35.
+ ///
+ /// The [radix] argument must be an integer in the range 2 to 36.
String toRadixString(int radix);
}
diff --git a/sdk/lib/core/bool.dart b/sdk/lib/core/bool.dart
index 3d35d80..f365d79 100644
--- a/sdk/lib/core/bool.dart
+++ b/sdk/lib/core/bool.dart
@@ -4,42 +4,38 @@
part of dart.core;
-/**
- * The reserved words `true` and `false` denote objects that are the only two
- * instances of this class.
- *
- * It is a compile-time error for a class to attempt to extend or implement
- * bool.
- */
+/// The reserved words `true` and `false` denote objects that are the only two
+/// instances of this class.
+///
+/// It is a compile-time error for a class to attempt to extend or implement
+/// bool.
@pragma("vm:entry-point")
class bool {
- /**
- * Returns the boolean value of the environment declaration [name].
- *
- * The boolean value of the declaration is `true` if the declared value is
- * the string `"true"`, and `false` if the value is `"false"`.
- *
- * In all other cases, including when there is no declaration for `name`,
- * the result is the [defaultValue].
- *
- * The result is the same as would be returned by:
- * ```dart
- * (const String.fromEnvironment(name) == "true")
- * ? true
- * : (const String.fromEnvironment(name) == "false")
- * ? false
- * : defaultValue
- * ```
- * Example:
- * ```dart
- * const loggingFlag = const bool.fromEnvironment("logging");
- * ```
- * If you want to use a different truth-string than `"true"`, you can use the
- * [String.fromEnvironment] constructor directly:
- * ```dart
- * const isLoggingOn = (const String.fromEnvironment("logging") == "on");
- * ```
- */
+ /// Returns the boolean value of the environment declaration [name].
+ ///
+ /// The boolean value of the declaration is `true` if the declared value is
+ /// the string `"true"`, and `false` if the value is `"false"`.
+ ///
+ /// In all other cases, including when there is no declaration for `name`,
+ /// the result is the [defaultValue].
+ ///
+ /// The result is the same as would be returned by:
+ /// ```dart
+ /// (const String.fromEnvironment(name) == "true")
+ /// ? true
+ /// : (const String.fromEnvironment(name) == "false")
+ /// ? false
+ /// : defaultValue
+ /// ```
+ /// Example:
+ /// ```dart
+ /// const loggingFlag = const bool.fromEnvironment("logging");
+ /// ```
+ /// If you want to use a different truth-string than `"true"`, you can use the
+ /// [String.fromEnvironment] constructor directly:
+ /// ```dart
+ /// const isLoggingOn = (const String.fromEnvironment("logging") == "on");
+ /// ```
// The .fromEnvironment() constructors are special in that we do not want
// users to call them using "new". We prohibit that by giving them bodies
// that throw, even though const constructors are not allowed to have bodies.
@@ -60,11 +56,11 @@
/// This constructor can be used to handle an absent declaration
/// specifically, in ways that cannot be represented by providing
/// a default value to the `C.fromEnvironment` constructor where `C`
- /// is [String], [int], or [bool].
+ /// is one of [String], [int], or [bool].
///
/// Example:
/// ```dart
- /// const loggingIsDeclared = const bool.hasEnvironment("logging");
+ /// const loggingIsDeclared = bool.hasEnvironment("logging");
///
/// const String? logger = loggingIsDeclared
/// ? String.fromEnvironment("logging")
@@ -98,9 +94,7 @@
@Since("2.1")
bool operator ^(bool other) => !other == this;
- /**
- * Returns either `"true"` for `true` and `"false"` for `false`.
- */
+ /// Returns either `"true"` for `true` and `"false"` for `false`.
String toString() {
return this ? "true" : "false";
}
diff --git a/sdk/lib/core/comparable.dart b/sdk/lib/core/comparable.dart
index 835aa34..67df844 100644
--- a/sdk/lib/core/comparable.dart
+++ b/sdk/lib/core/comparable.dart
@@ -4,91 +4,86 @@
part of dart.core;
-/**
- * The signature of a generic comparison function.
- *
- * A comparison function represents an ordering on a type of objects.
- * A total ordering on a type means that for two values, either they
- * are equal or one is greater than the other (and the latter must then be
- * smaller than the former).
- *
- * A [Comparator] function represents such a total ordering by returning
- *
- * * a negative integer if [a] is smaller than [b],
- * * zero if [a] is equal to [b], and
- * * a positive integer if [a] is greater than [b].
- */
+/// The signature of a generic comparison function.
+///
+/// A comparison function represents an ordering on a type of objects.
+/// A total ordering on a type means that for two values, either they
+/// are equal or one is greater than the other (and the latter must then be
+/// smaller than the former).
+///
+/// A [Comparator] function represents such a total ordering by returning
+///
+/// * a negative integer if [a] is smaller than [b],
+/// * zero if [a] is equal to [b], and
+/// * a positive integer if [a] is greater than [b].
typedef Comparator<T> = int Function(T a, T b);
-/**
- * Interface used by types that have an intrinsic ordering.
- *
- * The [compareTo] operation defines a total ordering of objects,
- * which can be used for ordering and sorting.
- *
- * The [Comparable] interface should be used for the natural ordering of a type.
- * If a type can be ordered in more than one way,
- * and none of them is the obvious natural ordering,
- * then it might be better not to use the [Comparable] interface,
- * and to provide separate [Comparator]s instead.
- *
- * It is recommended that the order of a [Comparable] agrees
- * with its operator [operator ==] equality (`a.compareTo(b) == 0` iff `a == b`),
- * but this is not a requirement.
- * For example, [double] and [DateTime] have `compareTo` methods
- * that do not agree with operator [operator ==].
- * For doubles the [compareTo] method is more precise than the equality,
- * and for [DateTime] it is less precise.
- *
- * Examples:
- *
- * (0.0).compareTo(-0.0); // => 1
- * 0.0 == -0.0; // => true
- * var dt = new DateTime.now();
- * var dt2 = dt.toUtc();
- * dt == dt2; // => false
- * dt.compareTo(dt2); // => 0
- *
- * The [Comparable] interface does not imply the existence
- * of the comparison operators `<`, `<=`, `>` and `>=`.
- * These should only be defined
- * if the ordering is a less-than/greater-than ordering,
- * that is, an ordering where you would naturally
- * use the words "less than" about the order of two elements.
- *
- * If the equality operator and [compareTo] disagree,
- * the comparison operators should follow the equality operator,
- * and will likely also disagree with [compareTo].
- * Otherwise they should match the [compareTo] method,
- * so that `a < b` iff `a.compareTo(b) < 0`.
- *
- * The [double] class defines comparison operators
- * that are compatible with equality.
- * The operators differ from `double.compareTo` on -0.0 and NaN.
- *
- * The [DateTime] class has no comparison operators, instead it has the more
- * precisely named [DateTime.isBefore] and [DateTime.isAfter].
- */
+/// Interface used by types that have an intrinsic ordering.
+///
+/// The [compareTo] operation defines a total ordering of objects,
+/// which can be used for ordering and sorting.
+///
+/// The [Comparable] interface should be used for the natural ordering of a type.
+/// If a type can be ordered in more than one way,
+/// and none of them is the obvious natural ordering,
+/// then it might be better not to use the [Comparable] interface,
+/// and to provide separate [Comparator]s instead.
+///
+/// It is recommended that the order of a [Comparable] agrees
+/// with its operator [operator ==] equality (`a.compareTo(b) == 0` iff `a == b`),
+/// but this is not a requirement.
+/// For example, [double] and [DateTime] have `compareTo` methods
+/// that do not agree with operator [operator ==].
+/// For doubles the [compareTo] method is more precise than the equality,
+/// and for [DateTime] it is less precise.
+///
+/// Examples:
+/// ```dart
+/// (0.0).compareTo(-0.0); // => 1
+/// 0.0 == -0.0; // => true
+/// var now = DateTime.now();
+/// var utcNow = now.toUtc();
+/// now == utcNow; // => false
+/// now.compareTo(utcNow); // => 0
+/// ```
+/// The [Comparable] interface does not imply the existence
+/// of the comparison operators `<`, `<=`, `>` and `>=`.
+/// These should only be defined
+/// if the ordering is a less-than/greater-than ordering,
+/// that is, an ordering where you would naturally
+/// use the words "less than" about the order of two elements.
+///
+/// If the equality operator and [compareTo] disagree,
+/// the comparison operators should follow the equality operator,
+/// and will likely also disagree with [compareTo].
+/// Otherwise they should match the [compareTo] method,
+/// so that `a < b` iff `a.compareTo(b) < 0`.
+///
+/// The [double] class defines comparison operators
+/// that are compatible with equality.
+/// The operators differ from [double.compareTo] on -0.0 and NaN.
+///
+/// The [DateTime] class has no comparison operators, instead it has the more
+/// precisely named [DateTime.isBefore] and [DateTime.isAfter], which both
+/// agree with [DateTime.compareTo].
abstract class Comparable<T> {
- /**
- * Compares this object to another [Comparable]
- *
- * Returns a value like a [Comparator] when comparing `this` to [other].
- * That is, it returns a negative integer if `this` is ordered before [other],
- * a positive integer if `this` is ordered after [other],
- * and zero if `this` and [other] are ordered together.
- *
- * The [other] argument must be a value that is comparable to this object.
- */
+ /// Compares this object to another object.
+ ///
+ /// Returns a value like a [Comparator] when comparing `this` to [other].
+ /// That is, it returns a negative integer if `this` is ordered before [other],
+ /// a positive integer if `this` is ordered after [other],
+ /// and zero if `this` and [other] are ordered together.
+ ///
+ /// The [other] argument must be a value that is comparable to this object.
int compareTo(T other);
- /**
- * A [Comparator] that compares one comparable to another.
- *
- * It returns the result of `a.compareTo(b)`.
- *
- * This utility function is used as the default comparator
- * for ordering collections, for example in the [List] sort function.
- */
+ /// A [Comparator] that compares one comparable to another.
+ ///
+ /// It returns the result of `a.compareTo(b)`.
+ /// The call may fail at run-time
+ /// if `a` is not comparable to the type of `b`.
+ ///
+ /// This utility function is used as the default comparator
+ /// for ordering collections, for example in the [List] sort function.
static int compare(Comparable a, Comparable b) => a.compareTo(b);
}
diff --git a/sdk/lib/core/core.dart b/sdk/lib/core/core.dart
index 8997c0a..e0b0124 100644
--- a/sdk/lib/core/core.dart
+++ b/sdk/lib/core/core.dart
@@ -2,155 +2,153 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-/**
- *
- * Built-in types, collections,
- * and other core functionality for every Dart program.
- *
- * This library is automatically imported.
- *
- * Some classes in this library,
- * such as [String] and [num],
- * support Dart's built-in data types.
- * Other classes, such as [List] and [Map], provide data structures
- * for managing collections of objects.
- * And still other classes represent commonly used types of data
- * such as URIs, dates and times, and errors.
- *
- * ## Numbers and booleans
- *
- * [int] and [double] provide support for Dart's built-in numerical data types:
- * integers and double-precision floating point numbers, respectively.
- * An object of type [bool] is either true or false.
- * Variables of these types can be constructed from literals:
- *
- * int meaningOfLife = 42;
- * double valueOfPi = 3.141592;
- * bool visible = true;
- *
- * ## Strings and regular expressions
- *
- * A [String] is immutable and represents a sequence of characters.
- *
- * String shakespeareQuote = "All the world's a stage, ...";
- *
- * [StringBuffer] provides a way to construct strings efficiently.
- *
- * StringBuffer moreShakespeare = new StringBuffer();
- * moreShakespeare.write('And all the men and women ');
- * moreShakespeare.write('merely players; ...');
- *
- * The String and StringBuffer classes implement string concatenation,
- * interpolation, and other string manipulation features.
- *
- * String philosophy = 'Live on ';
- * String get palindrome => philosophy + philosophy.split('').reversed.join();
- *
- * [RegExp] implements Dart regular expressions,
- * which provide a grammar for matching patterns within text.
- * For example, here's a regular expression that matches
- * a string of one or more digits:
- *
- * var numbers = new RegExp(r'\d+');
- *
- * Dart regular expressions have the same syntax and semantics as
- * JavaScript regular expressions. See
- * <http://ecma-international.org/ecma-262/5.1/#sec-15.10>
- * for the specification of JavaScript regular expressions.
- *
- * ## Collections
- *
- * The dart:core library provides basic collections,
- * such as [List], [Map], and [Set].
- *
- * A List is an ordered collection of objects, with a length.
- * Lists are sometimes called arrays.
- * Use a List when you need to access objects by index.
- *
- * List superheroes = [ 'Batman', 'Superman', 'Harry Potter' ];
- *
- * A Set is an unordered collection of unique objects.
- * You cannot get an item by index (position).
- * Adding a duplicate item has no effect.
- *
- * Set villains = new Set();
- * villains.add('Joker');
- * villains.addAll( ['Lex Luther', 'Voldemort'] );
- *
- * A Map is an unordered collection of key-value pairs.
- * Maps are sometimes called associative arrays because
- * maps associate a key to some value for easy retrieval.
- * Keys are unique.
- * Use a Map when you need to access objects
- * by a unique identifier.
- *
- * Map sidekicks = { 'Batman': 'Robin',
- * 'Superman': 'Lois Lane',
- * 'Harry Potter': 'Ron and Hermione' };
- *
- * In addition to these classes,
- * dart:core contains [Iterable],
- * an interface that defines functionality
- * common in collections of objects.
- * Examples include the ability
- * to run a function on each element in the collection,
- * to apply a test to each element,
- * to retrieve an object, and to determine length.
- *
- * Iterable is implemented by List and Set,
- * and used by Map for its keys and values.
- *
- * For other kinds of collections, check out the
- * `dart:collection` library.
- *
- * ## Date and time
- *
- * Use [DateTime] to represent a point in time
- * and [Duration] to represent a span of time.
- *
- * You can create DateTime objects with constructors
- * or by parsing a correctly formatted string.
- *
- * DateTime now = new DateTime.now();
- * DateTime berlinWallFell = new DateTime(1989, 11, 9);
- * DateTime moonLanding = DateTime.parse("1969-07-20");
- *
- * Create a Duration object specifying the individual time units.
- *
- * Duration timeRemaining = new Duration(hours:56, minutes:14);
- *
- * In addition to DateTime and Duration,
- * dart:core contains the [Stopwatch] class for measuring elapsed time.
- *
- * ## Uri
- *
- * A [Uri] object represents a uniform resource identifier,
- * which identifies a resource on the web.
- *
- * Uri dartlang = Uri.parse('http://dartlang.org/');
- *
- * ## Errors
- *
- * The [Error] class represents the occurrence of an error
- * during runtime.
- * Subclasses of this class represent specific kinds of errors.
- *
- * ## Other documentation
- *
- * For more information about how to use the built-in types, refer to
- * [Built-in Types](https://dart.dev/guides/language/language-tour#built-in-types)
- * in
- * [A tour of the Dart language](https://dart.dev/guides/language/language-tour).
- *
- * Also, see
- * [dart:core - numbers, collections, strings, and more](https://dart.dev/guides/libraries/library-tour#dartcore---numbers-collections-strings-and-more)
- * for more coverage of types in this library.
- *
- * The [Dart Language Specification](https://dart.dev/guides/language/spec)
- * provides technical details.
- *
- * {@category Core}
- */
+///
+/// Built-in types, collections,
+/// and other core functionality for every Dart program.
+///
+/// This library is automatically imported.
+///
+/// Some classes in this library,
+/// such as [String] and [num],
+/// support Dart's built-in data types.
+/// Other classes, such as [List] and [Map], provide data structures
+/// for managing collections of objects.
+/// And still other classes represent commonly used types of data
+/// such as URIs, dates and times, and errors.
+///
+/// ## Numbers and booleans
+///
+/// [int] and [double] provide support for Dart's built-in numerical data types:
+/// integers and double-precision floating point numbers, respectively.
+/// An object of type [bool] is either true or false.
+/// Variables of these types can be constructed from literals:
+/// ```dart
+/// int meaningOfLife = 42;
+/// double valueOfPi = 3.141592;
+/// bool visible = true;
+/// ```
+/// ## Strings and regular expressions
+///
+/// A [String] is immutable and represents a sequence of characters.
+/// ```dart
+/// String shakespeareQuote = "All the world's a stage, ...";
+/// ```
+/// [StringBuffer] provides a way to construct strings efficiently.
+/// ```dart
+/// var moreShakespeare = StringBuffer();
+/// moreShakespeare.write('And all the men and women ');
+/// moreShakespeare.write('merely players; ...');
+/// ```
+/// The [String] and [StringBuffer] classes implement string splitting,
+/// concatenation, and other string manipulation features.
+/// ```dart
+/// bool isPalindrome(String text) => text == text.split('').reversed.join();
+/// ```
+/// [RegExp] implements Dart regular expressions,
+/// which provide a grammar for matching patterns within text.
+/// For example, here's a regular expression that matches
+/// a substring containing one or more digits:
+/// ```dart
+/// var numbers = RegExp(r'\d+');
+/// ```
+/// Dart regular expressions have the same syntax and semantics as
+/// JavaScript regular expressions. See
+/// <http://ecma-international.org/ecma-262/5.1/#sec-15.10>
+/// for the specification of JavaScript regular expressions.
+///
+/// ## Collections
+///
+/// The `dart:core` library provides basic collections,
+/// such as [List], [Map], and [Set].
+///
+/// A [List] is an ordered collection of objects, with a length.
+/// Lists are sometimes called arrays.
+/// Use a [List] when you need to access objects by index.
+/// ```dart
+/// var superheroes = ['Batman', 'Superman', 'Harry Potter'];
+/// ```
+/// A [Set] is an unordered collection of unique objects.
+/// You cannot get an item efficiently by index (position).
+/// Adding an element which is already in the set, has no effect.
+/// ```dart
+/// var villains = {'Joker'};
+/// print(villains.length); // 1
+/// villains.addAll(['Joker', 'Lex Luthor', 'Voldemort']);
+/// print(villains.length); // 3
+/// ```
+/// A [Map] is an unordered collection of key-value pairs,
+/// where each key can only occur once.
+/// Maps are sometimes called associative arrays because
+/// maps associate a key to some value for easy retrieval.
+/// Use a [Map] when you need to access objects
+/// by a unique identifier.
+/// ```dart
+/// var sidekicks = {'Batman': 'Robin',
+/// 'Superman': 'Lois Lane',
+/// 'Harry Potter': 'Ron and Hermione'};
+/// ```
+/// In addition to these classes,
+/// `dart:core` contains [Iterable],
+/// an interface that defines functionality
+/// common in collections of objects.
+/// Examples include the ability
+/// to run a function on each element in the collection,
+/// to apply a test to each element,
+/// to retrieve an object, and to determine the number of elements.
+///
+/// [Iterable] is implemented by [List] and [Set],
+/// and used by [Map] for its keys and values.
+///
+/// For other kinds of collections, check out the
+/// `dart:collection` library.
+///
+/// ## Date and time
+///
+/// Use [DateTime] to represent a point in time
+/// and [Duration] to represent a span of time.
+///
+/// You can create [DateTime] objects with constructors
+/// or by parsing a correctly formatted string.
+/// ```dart
+/// var now = DateTime.now();
+/// var berlinWallFell = DateTime(1989, 11, 9);
+/// var moonLanding = DateTime.parse("1969-07-20");
+/// ```
+/// Create a [Duration] object by specifying the individual time units.
+/// ```dart
+/// var timeRemaining = const Duration(hours: 56, minutes: 14);
+/// ```
+/// In addition to [DateTime] and [Duration],
+/// `dart:core` contains the [Stopwatch] class for measuring elapsed time.
+///
+/// ## Uri
+///
+/// A [Uri] object represents a uniform resource identifier,
+/// which identifies a resource, for example on the web.
+/// ```dart
+/// var dartlang = Uri.parse('http://dartlang.org/');
+/// ```
+/// ## Errors
+///
+/// The [Error] class represents the occurrence of an error
+/// during runtime.
+/// Subclasses of this class represent specific kinds of errors.
+///
+/// ## Other documentation
+///
+/// For more information about how to use the built-in types, refer to
+/// [Built-in Types](https://dart.dev/guides/language/language-tour#built-in-types)
+/// in
+/// [A tour of the Dart language](https://dart.dev/guides/language/language-tour).
+///
+/// Also, see
+/// [dart:core - numbers, collections, strings, and more](https://dart.dev/guides/libraries/library-tour#dartcore---numbers-collections-strings-and-more)
+/// for more coverage of types in this library.
+///
+/// The [Dart Language Specification](https://dart.dev/guides/language/spec)
+/// provides technical details.
+///
+/// {@category Core}
library dart.core;
import "dart:collection";
diff --git a/sdk/lib/core/date_time.dart b/sdk/lib/core/date_time.dart
index e8c9dcb..2891f8b 100644
--- a/sdk/lib/core/date_time.dart
+++ b/sdk/lib/core/date_time.dart
@@ -4,122 +4,120 @@
part of dart.core;
-/**
- * An instant in time, such as July 20, 1969, 8:18pm GMT.
- *
- * DateTimes can represent time values that are at a distance of at most
- * 100,000,000 days from epoch (1970-01-01 UTC): -271821-04-20 to 275760-09-13.
- *
- * Create a DateTime object by using one of the constructors
- * or by parsing a correctly formatted string,
- * which complies with a subset of ISO 8601.
- * Note that hours are specified between 0 and 23,
- * as in a 24-hour clock.
- * For example:
- *
- * ```
- * var now = new DateTime.now();
- * var berlinWallFell = new DateTime.utc(1989, 11, 9);
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z"); // 8:18pm
- * ```
- *
- * A DateTime object is anchored either in the UTC time zone
- * or in the local time zone of the current computer
- * when the object is created.
- *
- * Once created, neither the value nor the time zone
- * of a DateTime object may be changed.
- *
- * You can use properties to get
- * the individual units of a DateTime object.
- *
- * ```
- * assert(berlinWallFell.month == 11);
- * assert(moonLanding.hour == 20);
- * ```
- *
- * For convenience and readability,
- * the DateTime class provides a constant for each day and month
- * name - for example, [august] and [friday].
- * You can use these constants to improve code readability:
- *
- * ```
- * var berlinWallFell = new DateTime.utc(1989, DateTime.november, 9);
- * assert(berlinWallFell.weekday == DateTime.thursday);
- * ```
- *
- * Day and month values begin at 1, and the week starts on Monday.
- * That is, the constants [january] and [monday] are both 1.
- *
- * ## Working with UTC and local time
- *
- * A DateTime object is in the local time zone
- * unless explicitly created in the UTC time zone.
- *
- * ```
- * var dDay = new DateTime.utc(1944, 6, 6);
- * ```
- *
- * Use [isUtc] to determine whether a DateTime object is based in UTC.
- * Use the methods [toLocal] and [toUtc]
- * to get the equivalent date/time value specified in the other time zone.
- * Use [timeZoneName] to get an abbreviated name of the time zone
- * for the DateTime object.
- * To find the difference
- * between UTC and the time zone of a DateTime object
- * call [timeZoneOffset].
- *
- * ## Comparing DateTime objects
- *
- * The DateTime class contains several handy methods,
- * such as [isAfter], [isBefore], and [isAtSameMomentAs],
- * for comparing DateTime objects.
- *
- * ```
- * assert(berlinWallFell.isAfter(moonLanding) == true);
- * assert(berlinWallFell.isBefore(moonLanding) == false);
- * ```
- *
- * ## Using DateTime with Duration
- *
- * Use the [add] and [subtract] methods with a [Duration] object
- * to create a new DateTime object based on another.
- * For example, to find the date that is sixty days (24 * 60 hours) after today,
- * write:
- *
- * ```
- * var now = new DateTime.now();
- * var sixtyDaysFromNow = now.add(new Duration(days: 60));
- * ```
- *
- * To find out how much time is between two DateTime objects use
- * [difference], which returns a [Duration] object:
- *
- * ```
- * var difference = berlinWallFell.difference(moonLanding);
- * assert(difference.inDays == 7416);
- * ```
- *
- * The difference between two dates in different time zones
- * is just the number of nanoseconds between the two points in time.
- * It doesn't take calendar days into account.
- * That means that the difference between two midnights in local time may be
- * less than 24 hours times the number of days between them,
- * if there is a daylight saving change in between.
- * If the difference above is calculated using Australian local time, the
- * difference is 7415 days and 23 hours, which is only 7415 whole days as
- * reported by `inDays`.
- *
- * ## Other resources
- *
- * See [Duration] to represent a span of time.
- * See [Stopwatch] to measure timespans.
- *
- * The DateTime class does not provide internationalization.
- * To internationalize your code, use
- * the [intl](https://pub.dev/packages/intl) package.
- *
- */
+/// An instant in time, such as July 20, 1969, 8:18pm GMT.
+///
+/// DateTimes can represent time values that are at a distance of at most
+/// 100,000,000 days from epoch (1970-01-01 UTC): -271821-04-20 to 275760-09-13.
+///
+/// Create a DateTime object by using one of the constructors
+/// or by parsing a correctly formatted string,
+/// which complies with a subset of ISO 8601.
+/// Note that hours are specified between 0 and 23,
+/// as in a 24-hour clock.
+/// For example:
+///
+/// ```
+/// var now = DateTime.now();
+/// var berlinWallFell = DateTime.utc(1989, 11, 9);
+/// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z"); // 8:18pm
+/// ```
+///
+/// A DateTime object is anchored either in the UTC time zone
+/// or in the local time zone of the current computer
+/// when the object is created.
+///
+/// Once created, neither the value nor the time zone
+/// of a DateTime object may be changed.
+///
+/// You can use properties to get
+/// the individual units of a DateTime object.
+///
+/// ```
+/// assert(berlinWallFell.month == 11);
+/// assert(moonLanding.hour == 20);
+/// ```
+///
+/// For convenience and readability,
+/// the DateTime class provides a constant for each day and month
+/// name - for example, [august] and [friday].
+/// You can use these constants to improve code readability:
+///
+/// ```
+/// var berlinWallFell = DateTime.utc(1989, DateTime.november, 9);
+/// assert(berlinWallFell.weekday == DateTime.thursday);
+/// ```
+///
+/// Day and month values begin at 1, and the week starts on Monday.
+/// That is, the constants [january] and [monday] are both 1.
+///
+/// ## Working with UTC and local time
+///
+/// A DateTime object is in the local time zone
+/// unless explicitly created in the UTC time zone.
+///
+/// ```
+/// var dDay = DateTime.utc(1944, 6, 6);
+/// ```
+///
+/// Use [isUtc] to determine whether a DateTime object is based in UTC.
+/// Use the methods [toLocal] and [toUtc]
+/// to get the equivalent date/time value specified in the other time zone.
+/// Use [timeZoneName] to get an abbreviated name of the time zone
+/// for the DateTime object.
+/// To find the difference
+/// between UTC and the time zone of a DateTime object
+/// call [timeZoneOffset].
+///
+/// ## Comparing DateTime objects
+///
+/// The DateTime class contains several handy methods,
+/// such as [isAfter], [isBefore], and [isAtSameMomentAs],
+/// for comparing DateTime objects.
+///
+/// ```
+/// assert(berlinWallFell.isAfter(moonLanding) == true);
+/// assert(berlinWallFell.isBefore(moonLanding) == false);
+/// ```
+///
+/// ## Using DateTime with Duration
+///
+/// Use the [add] and [subtract] methods with a [Duration] object
+/// to create a DateTime object based on another.
+/// For example, to find the date that is sixty days (24 * 60 hours) after today,
+/// write:
+///
+/// ```
+/// var now = DateTime.now();
+/// var sixtyDaysFromNow = now.add(const Duration(days: 60));
+/// ```
+///
+/// To find out how much time is between two DateTime objects use
+/// [difference], which returns a [Duration] object:
+///
+/// ```
+/// var difference = berlinWallFell.difference(moonLanding);
+/// assert(difference.inDays == 7416);
+/// ```
+///
+/// The difference between two dates in different time zones
+/// is just the number of nanoseconds between the two points in time.
+/// It doesn't take calendar days into account.
+/// That means that the difference between two midnights in local time may be
+/// less than 24 hours times the number of days between them,
+/// if there is a daylight saving change in between.
+/// If the difference above is calculated using Australian local time, the
+/// difference is 7415 days and 23 hours, which is only 7415 whole days as
+/// reported by `inDays`.
+///
+/// ## Other resources
+///
+/// See [Duration] to represent a span of time.
+/// See [Stopwatch] to measure timespans.
+///
+/// The DateTime class does not provide internationalization.
+/// To internationalize your code, use
+/// the [intl](https://pub.dev/packages/intl) package.
+///
class DateTime implements Comparable<DateTime> {
// Weekday constants that are returned by [weekday] method:
static const int monday = 1;
@@ -146,37 +144,31 @@
static const int december = 12;
static const int monthsPerYear = 12;
- /**
- * The value of this DateTime.
- *
- * The content of this field is implementation dependent. On JavaScript it is
- * equal to [millisecondsSinceEpoch]. On the VM it is equal to
- * [microsecondsSinceEpoch].
- */
+ /// The value of this DateTime.
+ ///
+ /// The content of this field is implementation dependent. On JavaScript it is
+ /// equal to [millisecondsSinceEpoch]. On the VM it is equal to
+ /// [microsecondsSinceEpoch].
final int _value;
- /**
- * True if this [DateTime] is set to UTC time.
- *
- * ```
- * var dDay = new DateTime.utc(1944, 6, 6);
- * assert(dDay.isUtc);
- * ```
- *
- */
+ /// True if this [DateTime] is set to UTC time.
+ ///
+ /// ```
+ /// var dDay = DateTime.utc(1944, 6, 6);
+ /// assert(dDay.isUtc);
+ /// ```
+ ///
final bool isUtc;
- /**
- * Constructs a [DateTime] instance specified in the local time zone.
- *
- * For example,
- * to create a new DateTime object representing the 7th of September 2017,
- * 5:30pm
- *
- * ```
- * var dentistAppointment = new DateTime(2017, 9, 7, 17, 30);
- * ```
- */
+ /// Constructs a [DateTime] instance specified in the local time zone.
+ ///
+ /// For example,
+ /// to create a DateTime object representing the 7th of September 2017,
+ /// 5:30pm
+ ///
+ /// ```
+ /// var dentistAppointment = DateTime(2017, 9, 7, 17, 30);
+ /// ```
DateTime(int year,
[int month = 1,
int day = 1,
@@ -188,17 +180,15 @@
: this._internal(year, month, day, hour, minute, second, millisecond,
microsecond, false);
- /**
- * Constructs a [DateTime] instance specified in the UTC time zone.
- *
- * ```
- * var moonLanding = new DateTime.utc(1969, 7, 20, 20, 18, 04);
- * ```
- *
- * When dealing with dates or historic events prefer to use UTC DateTimes,
- * since they are unaffected by daylight-saving changes and are unaffected
- * by the local timezone.
- */
+ /// Constructs a [DateTime] instance specified in the UTC time zone.
+ ///
+ /// ```
+ /// var moonLanding = DateTime.utc(1969, 7, 20, 20, 18, 04);
+ /// ```
+ ///
+ /// When dealing with dates or historic events prefer to use UTC DateTimes,
+ /// since they are unaffected by daylight-saving changes and are unaffected
+ /// by the local timezone.
DateTime.utc(int year,
[int month = 1,
int day = 1,
@@ -210,70 +200,65 @@
: this._internal(year, month, day, hour, minute, second, millisecond,
microsecond, true);
- /**
- * Constructs a [DateTime] instance with current date and time in the
- * local time zone.
- *
- * ```
- * var thisInstant = new DateTime.now();
- * ```
- */
+ /// Constructs a [DateTime] instance with current date and time in the
+ /// local time zone.
+ ///
+ /// ```
+ /// var thisInstant = DateTime.now();
+ /// ```
DateTime.now() : this._now();
- /**
- * Constructs a new [DateTime] instance based on [formattedString].
- *
- * The [formattedString] must not be `null`.
- * Throws a [FormatException] if the input string cannot be parsed.
- *
- * The function parses a subset of ISO 8601
- * which includes the subset accepted by RFC 3339.
- *
- * The accepted inputs are currently:
- *
- * * A date: A signed four-to-six digit year, two digit month and
- * two digit day, optionally separated by `-` characters.
- * Examples: "19700101", "-0004-12-24", "81030-04-01".
- * * An optional time part, separated from the date by either `T` or a space.
- * The time part is a two digit hour,
- * then optionally a two digit minutes value,
- * then optionally a two digit seconds value, and
- * then optionally a '.' or ',' followed by at least a one digit
- * second fraction.
- * The minutes and seconds may be separated from the previous parts by a
- * ':'.
- * Examples: "12", "12:30:24.124", "12:30:24,124", "123010.50".
- * * An optional time-zone offset part,
- * possibly separated from the previous by a space.
- * The time zone is either 'z' or 'Z', or it is a signed two digit hour
- * part and an optional two digit minute part. The sign must be either
- * "+" or "-", and can not be omitted.
- * The minutes may be separated from the hours by a ':'.
- * Examples: "Z", "-10", "+01:30", "+1130".
- *
- * This includes the output of both [toString] and [toIso8601String], which
- * will be parsed back into a `DateTime` object with the same time as the
- * original.
- *
- * The result is always in either local time or UTC.
- * If a time zone offset other than UTC is specified,
- * the time is converted to the equivalent UTC time.
- *
- * Examples of accepted strings:
- *
- * * `"2012-02-27"`
- * * `"2012-02-27 13:27:00"`
- * * `"2012-02-27 13:27:00.123456789z"`
- * * `"2012-02-27 13:27:00,123456789z"`
- * * `"20120227 13:27:00"`
- * * `"20120227T132700"`
- * * `"20120227"`
- * * `"+20120227"`
- * * `"2012-02-27T14Z"`
- * * `"2012-02-27T14+00:00"`
- * * `"-123450101 00:00:00 Z"`: in the year -12345.
- * * `"2002-02-27T14:00:00-0500"`: Same as `"2002-02-27T19:00:00Z"`
- */
+ /// Constructs a new [DateTime] instance based on [formattedString].
+ ///
+ /// Throws a [FormatException] if the input string cannot be parsed.
+ ///
+ /// The function parses a subset of ISO 8601
+ /// which includes the subset accepted by RFC 3339.
+ ///
+ /// The accepted inputs are currently:
+ ///
+ /// * A date: A signed four-to-six digit year, two digit month and
+ /// two digit day, optionally separated by `-` characters.
+ /// Examples: "19700101", "-0004-12-24", "81030-04-01".
+ /// * An optional time part, separated from the date by either `T` or a space.
+ /// The time part is a two digit hour,
+ /// then optionally a two digit minutes value,
+ /// then optionally a two digit seconds value, and
+ /// then optionally a '.' or ',' followed by at least a one digit
+ /// second fraction.
+ /// The minutes and seconds may be separated from the previous parts by a
+ /// ':'.
+ /// Examples: "12", "12:30:24.124", "12:30:24,124", "123010.50".
+ /// * An optional time-zone offset part,
+ /// possibly separated from the previous by a space.
+ /// The time zone is either 'z' or 'Z', or it is a signed two digit hour
+ /// part and an optional two digit minute part. The sign must be either
+ /// "+" or "-", and can not be omitted.
+ /// The minutes may be separated from the hours by a ':'.
+ /// Examples: "Z", "-10", "+01:30", "+1130".
+ ///
+ /// This includes the output of both [toString] and [toIso8601String], which
+ /// will be parsed back into a `DateTime` object with the same time as the
+ /// original.
+ ///
+ /// The result is always in either local time or UTC.
+ /// If a time zone offset other than UTC is specified,
+ /// the time is converted to the equivalent UTC time.
+ ///
+ /// Examples of accepted strings:
+ ///
+ /// * `"2012-02-27"`
+ /// * `"2012-02-27 13:27:00"`
+ /// * `"2012-02-27 13:27:00.123456789z"`
+ /// * `"2012-02-27 13:27:00,123456789z"`
+ /// * `"20120227 13:27:00"`
+ /// * `"20120227T132700"`
+ /// * `"20120227"`
+ /// * `"+20120227"`
+ /// * `"2012-02-27T14Z"`
+ /// * `"2012-02-27T14+00:00"`
+ /// * `"-123450101 00:00:00 Z"`: in the year -12345.
+ /// * `"2002-02-27T14:00:00-0500"`: Same as `"2002-02-27T19:00:00Z"`
// TODO(lrn): restrict incorrect values like 2003-02-29T50:70:80.
// Or not, that may be a breaking change.
static DateTime parse(String formattedString) {
@@ -338,12 +323,10 @@
}
}
- /**
- * Constructs a new [DateTime] instance based on [formattedString].
- *
- * Works like [parse] except that this function returns `null`
- * where [parse] would throw a [FormatException].
- */
+ /// Constructs a new [DateTime] instance based on [formattedString].
+ ///
+ /// Works like [parse] except that this function returns `null`
+ /// where [parse] would throw a [FormatException].
static DateTime? tryParse(String formattedString) {
// TODO: Optimize to avoid throwing.
try {
@@ -355,37 +338,31 @@
static const int _maxMillisecondsSinceEpoch = 8640000000000000;
- /**
- * Constructs a new [DateTime] instance
- * with the given [millisecondsSinceEpoch].
- *
- * If [isUtc] is false then the date is in the local time zone.
- *
- * The constructed [DateTime] represents
- * 1970-01-01T00:00:00Z + [millisecondsSinceEpoch] ms in the given
- * time zone (local or UTC).
- */
+ /// Constructs a new [DateTime] instance
+ /// with the given [millisecondsSinceEpoch].
+ ///
+ /// If [isUtc] is false then the date is in the local time zone.
+ ///
+ /// The constructed [DateTime] represents
+ /// 1970-01-01T00:00:00Z + [millisecondsSinceEpoch] ms in the given
+ /// time zone (local or UTC).
external DateTime.fromMillisecondsSinceEpoch(int millisecondsSinceEpoch,
{bool isUtc = false});
- /**
- * Constructs a new [DateTime] instance
- * with the given [microsecondsSinceEpoch].
- *
- * If [isUtc] is false then the date is in the local time zone.
- *
- * The constructed [DateTime] represents
- * 1970-01-01T00:00:00Z + [microsecondsSinceEpoch] us in the given
- * time zone (local or UTC).
- */
+ /// Constructs a new [DateTime] instance
+ /// with the given [microsecondsSinceEpoch].
+ ///
+ /// If [isUtc] is false then the date is in the local time zone.
+ ///
+ /// The constructed [DateTime] represents
+ /// 1970-01-01T00:00:00Z + [microsecondsSinceEpoch] us in the given
+ /// time zone (local or UTC).
external DateTime.fromMicrosecondsSinceEpoch(int microsecondsSinceEpoch,
{bool isUtc = false});
- /**
- * Constructs a new [DateTime] instance with the given value.
- *
- * If [isUtc] is false then the date is in the local time zone.
- */
+ /// Constructs a new [DateTime] instance with the given value.
+ ///
+ /// If [isUtc] is false then the date is in the local time zone.
DateTime._withValue(this._value, {required this.isUtc}) {
if (millisecondsSinceEpoch.abs() > _maxMillisecondsSinceEpoch ||
(millisecondsSinceEpoch.abs() == _maxMillisecondsSinceEpoch &&
@@ -397,112 +374,100 @@
checkNotNullable(isUtc, "isUtc");
}
- /**
- * Returns true if [other] is a [DateTime] at the same moment and in the
- * same time zone (UTC or local).
- *
- * ```
- * var dDayUtc = new DateTime.utc(1944, 6, 6);
- * var dDayLocal = dDayUtc.toLocal();
- *
- * // These two dates are at the same moment, but are in different zones.
- * assert(dDayUtc != dDayLocal);
- * ```
- *
- * See [isAtSameMomentAs] for a comparison that compares moments in time
- * independently of their zones.
- */
+ /// Returns true if [other] is a [DateTime] at the same moment and in the
+ /// same time zone (UTC or local).
+ ///
+ /// ```
+ /// var dDayUtc = DateTime.utc(1944, 6, 6);
+ /// var dDayLocal = dDayUtc.toLocal();
+ ///
+ /// // These two dates are at the same moment, but are in different zones.
+ /// assert(dDayUtc != dDayLocal);
+ /// ```
+ ///
+ /// See [isAtSameMomentAs] for a comparison that compares moments in time
+ /// independently of their zones.
external bool operator ==(Object other);
- /**
- * Returns true if [this] occurs before [other].
- *
- * The comparison is independent
- * of whether the time is in UTC or in the local time zone.
- *
- * ```
- * var now = new DateTime.now();
- * var earlier = now.subtract(const Duration(seconds: 5));
- * assert(earlier.isBefore(now));
- * assert(!now.isBefore(now));
- *
- * // This relation stays the same, even when changing timezones.
- * assert(earlier.isBefore(now.toUtc()));
- * assert(earlier.toUtc().isBefore(now));
- *
- * assert(!now.toUtc().isBefore(now));
- * assert(!now.isBefore(now.toUtc()));
- * ```
- */
+ /// Returns true if [this] occurs before [other].
+ ///
+ /// The comparison is independent
+ /// of whether the time is in UTC or in the local time zone.
+ ///
+ /// ```
+ /// var now = DateTime.now();
+ /// var earlier = now.subtract(const Duration(seconds: 5));
+ /// assert(earlier.isBefore(now));
+ /// assert(!now.isBefore(now));
+ ///
+ /// // This relation stays the same, even when changing timezones.
+ /// assert(earlier.isBefore(now.toUtc()));
+ /// assert(earlier.toUtc().isBefore(now));
+ ///
+ /// assert(!now.toUtc().isBefore(now));
+ /// assert(!now.isBefore(now.toUtc()));
+ /// ```
external bool isBefore(DateTime other);
- /**
- * Returns true if [this] occurs after [other].
- *
- * The comparison is independent
- * of whether the time is in UTC or in the local time zone.
- *
- * ```
- * var now = new DateTime.now();
- * var later = now.add(const Duration(seconds: 5));
- * assert(later.isAfter(now));
- * assert(!now.isBefore(now));
- *
- * // This relation stays the same, even when changing timezones.
- * assert(later.isAfter(now.toUtc()));
- * assert(later.toUtc().isAfter(now));
- *
- * assert(!now.toUtc().isBefore(now));
- * assert(!now.isBefore(now.toUtc()));
- * ```
- */
+ /// Returns true if [this] occurs after [other].
+ ///
+ /// The comparison is independent
+ /// of whether the time is in UTC or in the local time zone.
+ ///
+ /// ```
+ /// var now = DateTime.now();
+ /// var later = now.add(const Duration(seconds: 5));
+ /// assert(later.isAfter(now));
+ /// assert(!now.isBefore(now));
+ ///
+ /// // This relation stays the same, even when changing timezones.
+ /// assert(later.isAfter(now.toUtc()));
+ /// assert(later.toUtc().isAfter(now));
+ ///
+ /// assert(!now.toUtc().isBefore(now));
+ /// assert(!now.isBefore(now.toUtc()));
+ /// ```
external bool isAfter(DateTime other);
- /**
- * Returns true if [this] occurs at the same moment as [other].
- *
- * The comparison is independent of whether the time is in UTC or in the local
- * time zone.
- *
- * ```
- * var now = new DateTime.now();
- * var later = now.add(const Duration(seconds: 5));
- * assert(!later.isAtSameMomentAs(now));
- * assert(now.isAtSameMomentAs(now));
- *
- * // This relation stays the same, even when changing timezones.
- * assert(!later.isAtSameMomentAs(now.toUtc()));
- * assert(!later.toUtc().isAtSameMomentAs(now));
- *
- * assert(now.toUtc().isAtSameMomentAs(now));
- * assert(now.isAtSameMomentAs(now.toUtc()));
- * ```
- */
+ /// Returns true if [this] occurs at the same moment as [other].
+ ///
+ /// The comparison is independent of whether the time is in UTC or in the local
+ /// time zone.
+ ///
+ /// ```
+ /// var now = DateTime.now();
+ /// var later = now.add(const Duration(seconds: 5));
+ /// assert(!later.isAtSameMomentAs(now));
+ /// assert(now.isAtSameMomentAs(now));
+ ///
+ /// // This relation stays the same, even when changing timezones.
+ /// assert(!later.isAtSameMomentAs(now.toUtc()));
+ /// assert(!later.toUtc().isAtSameMomentAs(now));
+ ///
+ /// assert(now.toUtc().isAtSameMomentAs(now));
+ /// assert(now.isAtSameMomentAs(now.toUtc()));
+ /// ```
external bool isAtSameMomentAs(DateTime other);
- /**
- * Compares this DateTime object to [other],
- * returning zero if the values are equal.
- *
- * Returns a negative value if this DateTime [isBefore] [other]. It returns 0
- * if it [isAtSameMomentAs] [other], and returns a positive value otherwise
- * (when this [isAfter] [other]).
- */
+ /// Compares this DateTime object to [other],
+ /// returning zero if the values are equal.
+ ///
+ /// Returns a negative value if this DateTime [isBefore] [other]. It returns 0
+ /// if it [isAtSameMomentAs] [other], and returns a positive value otherwise
+ /// (when this [isAfter] [other]).
external int compareTo(DateTime other);
int get hashCode => (_value ^ (_value >> 30)) & 0x3FFFFFFF;
- /**
- * Returns this DateTime value in the local time zone.
- *
- * Returns [this] if it is already in the local time zone.
- * Otherwise this method is equivalent to:
- *
- * ```
- * new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
- * isUtc: false)
- * ```
- */
+ /// Returns this DateTime value in the local time zone.
+ ///
+ /// Returns [this] if it is already in the local time zone.
+ /// Otherwise this method is equivalent to:
+ ///
+ /// ```
+ /// DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
+ /// isUtc: false)
+ /// ```
DateTime toLocal() {
if (isUtc) {
return DateTime._withValue(_value, isUtc: false);
@@ -510,17 +475,15 @@
return this;
}
- /**
- * Returns this DateTime value in the UTC time zone.
- *
- * Returns [this] if it is already in UTC.
- * Otherwise this method is equivalent to:
- *
- * ```
- * new DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
- * isUtc: true)
- * ```
- */
+ /// Returns this DateTime value in the UTC time zone.
+ ///
+ /// Returns [this] if it is already in UTC.
+ /// Otherwise this method is equivalent to:
+ ///
+ /// ```
+ /// DateTime.fromMicrosecondsSinceEpoch(microsecondsSinceEpoch,
+ /// isUtc: true)
+ /// ```
DateTime toUtc() {
if (isUtc) return this;
return DateTime._withValue(_value, isUtc: true);
@@ -554,17 +517,15 @@
return "0${n}";
}
- /**
- * Returns a human-readable string for this instance.
- *
- * The returned string is constructed for the time zone of this instance.
- * The `toString()` method provides a simply formatted string.
- * It does not support internationalized strings.
- * Use the [intl](https://pub.dev/packages/intl) package
- * at the pub shared packages repo.
- *
- * The resulting string can be parsed back using [parse].
- */
+ /// Returns a human-readable string for this instance.
+ ///
+ /// The returned string is constructed for the time zone of this instance.
+ /// The `toString()` method provides a simply formatted string.
+ /// It does not support internationalized strings.
+ /// Use the [intl](https://pub.dev/packages/intl) package
+ /// at the pub shared packages repo.
+ ///
+ /// The resulting string can be parsed back using [parse].
String toString() {
String y = _fourDigits(year);
String m = _twoDigits(month);
@@ -581,27 +542,25 @@
}
}
- /**
- * Returns an ISO-8601 full-precision extended format representation.
- *
- * The format is `yyyy-MM-ddTHH:mm:ss.mmmuuuZ` for UTC time, and
- * `yyyy-MM-ddTHH:mm:ss.mmmuuu` (no trailing "Z") for local/non-UTC time,
- * where:
- *
- * * `yyyy` is a, possibly negative, four digit representation of the year,
- * if the year is in the range -9999 to 9999,
- * otherwise it is a signed six digit representation of the year.
- * * `MM` is the month in the range 01 to 12,
- * * `dd` is the day of the month in the range 01 to 31,
- * * `HH` are hours in the range 00 to 23,
- * * `mm` are minutes in the range 00 to 59,
- * * `ss` are seconds in the range 00 to 59 (no leap seconds),
- * * `mmm` are milliseconds in the range 000 to 999, and
- * * `uuu` are microseconds in the range 001 to 999. If [microsecond] equals
- * 0, then this part is omitted.
- *
- * The resulting string can be parsed back using [parse].
- */
+ /// Returns an ISO-8601 full-precision extended format representation.
+ ///
+ /// The format is `yyyy-MM-ddTHH:mm:ss.mmmuuuZ` for UTC time, and
+ /// `yyyy-MM-ddTHH:mm:ss.mmmuuu` (no trailing "Z") for local/non-UTC time,
+ /// where:
+ ///
+ /// * `yyyy` is a, possibly negative, four digit representation of the year,
+ /// if the year is in the range -9999 to 9999,
+ /// otherwise it is a signed six digit representation of the year.
+ /// * `MM` is the month in the range 01 to 12,
+ /// * `dd` is the day of the month in the range 01 to 31,
+ /// * `HH` are hours in the range 00 to 23,
+ /// * `mm` are minutes in the range 00 to 59,
+ /// * `ss` are seconds in the range 00 to 59 (no leap seconds),
+ /// * `mmm` are milliseconds in the range 000 to 999, and
+ /// * `uuu` are microseconds in the range 001 to 999. If [microsecond] equals
+ /// 0, then this part is omitted.
+ ///
+ /// The resulting string can be parsed back using [parse].
String toIso8601String() {
String y =
(year >= -9999 && year <= 9999) ? _fourDigits(year) : _sixDigits(year);
@@ -619,72 +578,66 @@
}
}
- /**
- * Returns a new [DateTime] instance with [duration] added to [this].
- *
- * ```
- * var today = new DateTime.now();
- * var fiftyDaysFromNow = today.add(new Duration(days: 50));
- * ```
- *
- * Notice that the duration being added is actually 50 * 24 * 60 * 60
- * seconds. If the resulting `DateTime` has a different daylight saving offset
- * than `this`, then the result won't have the same time-of-day as `this`, and
- * may not even hit the calendar date 50 days later.
- *
- * Be careful when working with dates in local time.
- */
+ /// Returns a new [DateTime] instance with [duration] added to [this].
+ ///
+ /// ```
+ /// var today = DateTime.now();
+ /// var fiftyDaysFromNow = today.add(const Duration(days: 50));
+ /// ```
+ ///
+ /// Notice that the duration being added is actually 50 * 24 * 60 * 60
+ /// seconds. If the resulting `DateTime` has a different daylight saving offset
+ /// than `this`, then the result won't have the same time-of-day as `this`, and
+ /// may not even hit the calendar date 50 days later.
+ ///
+ /// Be careful when working with dates in local time.
external DateTime add(Duration duration);
- /**
- * Returns a new [DateTime] instance with [duration] subtracted from [this].
- *
- * ```
- * DateTime today = new DateTime.now();
- * DateTime fiftyDaysAgo = today.subtract(new Duration(days: 50));
- * ```
- *
- * Notice that the duration being subtracted is actually 50 * 24 * 60 * 60
- * seconds. If the resulting `DateTime` has a different daylight saving offset
- * than `this`, then the result won't have the same time-of-day as `this`, and
- * may not even hit the calendar date 50 days earlier.
- *
- * Be careful when working with dates in local time.
- */
+ /// Returns a new [DateTime] instance with [duration] subtracted from [this].
+ ///
+ /// ```
+ /// DateTime today = DateTime.now();
+ /// DateTime fiftyDaysAgo = today.subtract(const Duration(days: 50));
+ /// ```
+ ///
+ /// Notice that the duration being subtracted is actually 50 * 24 * 60 * 60
+ /// seconds. If the resulting `DateTime` has a different daylight saving offset
+ /// than `this`, then the result won't have the same time-of-day as `this`, and
+ /// may not even hit the calendar date 50 days earlier.
+ ///
+ /// Be careful when working with dates in local time.
external DateTime subtract(Duration duration);
- /**
- * Returns a [Duration] with the difference when subtracting [other] from
- * [this].
- *
- * The returned [Duration] will be negative if [other] occurs after [this].
- *
- * ```
- * var berlinWallFell = new DateTime.utc(1989, DateTime.november, 9);
- * var dDay = new DateTime.utc(1944, DateTime.june, 6);
- *
- * Duration difference = berlinWallFell.difference(dDay);
- * assert(difference.inDays == 16592);
- * ```
- *
- * The difference is measured in seconds and fractions of seconds.
- * The difference above counts the number of fractional seconds between
- * midnight at the beginning of those dates.
- * If the dates above had been in local time, not UTC, then the difference
- * between two midnights may not be a multiple of 24 hours due to daylight
- * saving differences.
- *
- * For example, in Australia, similar code using local time instead of UTC:
- *
- * ```
- * var berlinWallFell = new DateTime(1989, DateTime.november, 9);
- * var dDay = new DateTime(1944, DateTime.june, 6);
- * Duration difference = berlinWallFell.difference(dDay);
- * assert(difference.inDays == 16592);
- * ```
- * will fail because the difference is actually 16591 days and 23 hours, and
- * [Duration.inDays] only returns the number of whole days.
- */
+ /// Returns a [Duration] with the difference when subtracting [other] from
+ /// [this].
+ ///
+ /// The returned [Duration] will be negative if [other] occurs after [this].
+ ///
+ /// ```
+ /// var berlinWallFell = DateTime.utc(1989, DateTime.november, 9);
+ /// var dDay = DateTime.utc(1944, DateTime.june, 6);
+ ///
+ /// Duration difference = berlinWallFell.difference(dDay);
+ /// assert(difference.inDays == 16592);
+ /// ```
+ ///
+ /// The difference is measured in seconds and fractions of seconds.
+ /// The difference above counts the number of fractional seconds between
+ /// midnight at the beginning of those dates.
+ /// If the dates above had been in local time, not UTC, then the difference
+ /// between two midnights may not be a multiple of 24 hours due to daylight
+ /// saving differences.
+ ///
+ /// For example, in Australia, similar code using local time instead of UTC:
+ ///
+ /// ```
+ /// var berlinWallFell = DateTime(1989, DateTime.november, 9);
+ /// var dDay = DateTime(1944, DateTime.june, 6);
+ /// Duration difference = berlinWallFell.difference(dDay);
+ /// assert(difference.inDays == 16592);
+ /// ```
+ /// will fail because the difference is actually 16591 days and 23 hours, and
+ /// [Duration.inDays] only returns the number of whole days.
external Duration difference(DateTime other);
external DateTime._internal(int year, int month, int day, int hour,
@@ -705,150 +658,124 @@
int microsecond,
bool isUtc);
- /**
- * The number of milliseconds since
- * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
- *
- * This value is independent of the time zone.
- *
- * This value is at most
- * 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch.
- * In other words: `millisecondsSinceEpoch.abs() <= 8640000000000000`.
- */
+ /// The number of milliseconds since
+ /// the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+ ///
+ /// This value is independent of the time zone.
+ ///
+ /// This value is at most
+ /// 8,640,000,000,000,000ms (100,000,000 days) from the Unix epoch.
+ /// In other words: `millisecondsSinceEpoch.abs() <= 8640000000000000`.
external int get millisecondsSinceEpoch;
- /**
- * The number of microseconds since
- * the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
- *
- * This value is independent of the time zone.
- *
- * This value is at most
- * 8,640,000,000,000,000,000us (100,000,000 days) from the Unix epoch.
- * In other words: `microsecondsSinceEpoch.abs() <= 8640000000000000000`.
- *
- * Note that this value does not fit into 53 bits (the size of a IEEE double).
- * A JavaScript number is not able to hold this value.
- */
+ /// The number of microseconds since
+ /// the "Unix epoch" 1970-01-01T00:00:00Z (UTC).
+ ///
+ /// This value is independent of the time zone.
+ ///
+ /// This value is at most
+ /// 8,640,000,000,000,000,000us (100,000,000 days) from the Unix epoch.
+ /// In other words: `microsecondsSinceEpoch.abs() <= 8640000000000000000`.
+ ///
+ /// Note that this value does not fit into 53 bits (the size of a IEEE double).
+ /// A JavaScript number is not able to hold this value.
external int get microsecondsSinceEpoch;
- /**
- * The time zone name.
- *
- * This value is provided by the operating system and may be an
- * abbreviation or a full name.
- *
- * In the browser or on Unix-like systems commonly returns abbreviations,
- * such as "CET" or "CEST". On Windows returns the full name, for example
- * "Pacific Standard Time".
- */
+ /// The time zone name.
+ ///
+ /// This value is provided by the operating system and may be an
+ /// abbreviation or a full name.
+ ///
+ /// In the browser or on Unix-like systems commonly returns abbreviations,
+ /// such as "CET" or "CEST". On Windows returns the full name, for example
+ /// "Pacific Standard Time".
external String get timeZoneName;
- /**
- * The time zone offset, which
- * is the difference between local time and UTC.
- *
- * The offset is positive for time zones east of UTC.
- *
- * Note, that JavaScript, Python and C return the difference between UTC and
- * local time. Java, C# and Ruby return the difference between local time and
- * UTC.
- */
+ /// The time zone offset, which
+ /// is the difference between local time and UTC.
+ ///
+ /// The offset is positive for time zones east of UTC.
+ ///
+ /// Note, that JavaScript, Python and C return the difference between UTC and
+ /// local time. Java, C# and Ruby return the difference between local time and
+ /// UTC.
external Duration get timeZoneOffset;
- /**
- * The year.
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.year == 1969);
- * ```
- */
+ /// The year.
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.year == 1969);
+ /// ```
external int get year;
- /**
- * The month [1..12].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.month == 7);
- * assert(moonLanding.month == DateTime.july);
- * ```
- */
+ /// The month [1..12].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.month == 7);
+ /// assert(moonLanding.month == DateTime.july);
+ /// ```
external int get month;
- /**
- * The day of the month [1..31].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.day == 20);
- * ```
- */
+ /// The day of the month [1..31].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.day == 20);
+ /// ```
external int get day;
- /**
- * The hour of the day, expressed as in a 24-hour clock [0..23].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.hour == 20);
- * ```
- */
+ /// The hour of the day, expressed as in a 24-hour clock [0..23].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.hour == 20);
+ /// ```
external int get hour;
- /**
- * The minute [0...59].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.minute == 18);
- * ```
- */
+ /// The minute [0...59].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.minute == 18);
+ /// ```
external int get minute;
- /**
- * The second [0...59].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.second == 4);
- * ```
- */
+ /// The second [0...59].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.second == 4);
+ /// ```
external int get second;
- /**
- * The millisecond [0...999].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.millisecond == 0);
- * ```
- */
+ /// The millisecond [0...999].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.millisecond == 0);
+ /// ```
external int get millisecond;
- /**
- * The microsecond [0...999].
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.microsecond == 0);
- * ```
- */
+ /// The microsecond [0...999].
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.microsecond == 0);
+ /// ```
external int get microsecond;
- /**
- * The day of the week [monday]..[sunday].
- *
- * In accordance with ISO 8601
- * a week starts with Monday, which has the value 1.
- *
- * ```
- * var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
- * assert(moonLanding.weekday == 7);
- * assert(moonLanding.weekday == DateTime.sunday);
- * ```
- */
+ /// The day of the week [monday]..[sunday].
+ ///
+ /// In accordance with ISO 8601
+ /// a week starts with Monday, which has the value 1.
+ ///
+ /// ```
+ /// var moonLanding = DateTime.parse("1969-07-20 20:18:04Z");
+ /// assert(moonLanding.weekday == 7);
+ /// assert(moonLanding.weekday == DateTime.sunday);
+ /// ```
external int get weekday;
/*
diff --git a/sdk/lib/core/double.dart b/sdk/lib/core/double.dart
index 42ff566..337d5f9 100644
--- a/sdk/lib/core/double.dart
+++ b/sdk/lib/core/double.dart
@@ -4,24 +4,18 @@
part of dart.core;
-// TODO: Convert this abstract class into a concrete class double
-// that uses the patch class functionality to account for the
-// different platform implementations.
-
-/**
- * A double-precision floating point number.
- *
- * Representation of Dart doubles containing double specific constants
- * and operations and specializations of operations inherited from
- * [num]. Dart doubles are 64-bit floating-point numbers as specified in the
- * IEEE 754 standard.
- *
- * The [double] type is contagious. Operations on [double]s return
- * [double] results.
- *
- * It is a compile-time error for a class to attempt to extend or implement
- * double.
- */
+/// A double-precision floating point number.
+///
+/// Representation of Dart doubles containing double specific constants
+/// and operations and specializations of operations inherited from
+/// [num]. Dart doubles are 64-bit floating-point numbers as specified in the
+/// IEEE 754 standard.
+///
+/// The [double] type is contagious. Operations on [double]s return
+/// [double] results.
+///
+/// It is a compile-time error for a class to attempt to extend or implement
+/// double.
abstract class double extends num {
static const double nan = 0.0 / 0.0;
static const double infinity = 1.0 / 0.0;
@@ -31,188 +25,160 @@
double remainder(num other);
- /** Addition operator. */
double operator +(num other);
- /** Subtraction operator. */
double operator -(num other);
- /** Multiplication operator. */
double operator *(num other);
double operator %(num other);
- /** Division operator. */
double operator /(num other);
- /**
- * Truncating division operator.
- *
- * The result of the truncating division `a ~/ b` is equivalent to
- * `(a / b).truncate()`.
- */
int operator ~/(num other);
- /** Negate operator. */
double operator -();
- /** Returns the absolute value of this [double]. */
double abs();
- /**
- * Returns the sign of the double's numerical value.
- *
- * Returns -1.0 if the value is less than zero,
- * +1.0 if the value is greater than zero,
- * and the value itself if it is -0.0, 0.0 or NaN.
- */
+ /// Returns the sign of the double's numerical value.
+ ///
+ /// Returns -1.0 if the value is less than zero,
+ /// +1.0 if the value is greater than zero,
+ /// and the value itself if it is -0.0, 0.0 or NaN.
double get sign;
- /**
- * Returns the integer closest to `this`.
- *
- * Rounds away from zero when there is no closest integer:
- * `(3.5).round() == 4` and `(-3.5).round() == -4`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// Returns the integer closest to this number.
+ ///
+ /// Rounds away from zero when there is no closest integer:
+ /// `(3.5).round() == 4` and `(-3.5).round() == -4`.
+ ///
+ /// Throws an [UnsupportedError] if this number is not finite
+ /// (NaN or an infinity), .
int round();
- /**
- * Returns the greatest integer no greater than `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// Returns the greatest integer no greater than this number.
+ ///
+ /// Rounds the number towards negative infinity.
+ ///
+ /// Throws an [UnsupportedError] if this number is not finite
+ /// (NaN or infinity), .
int floor();
- /**
- * Returns the least integer no smaller than `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// Returns the least integer which is not smaller than this number.
+ ///
+ /// Rounds the number towards infinity.
+ ///
+ /// Throws an [UnsupportedError] if this number is not finite
+ /// (NaN or an infinity), .
int ceil();
- /**
- * Returns the integer obtained by discarding any fractional
- * digits from `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// Returns the integer obtained by discarding any fractional
+ /// part of this number.
+ ///
+ /// Rounds the number towards zero.
+ ///
+ /// Throws an [UnsupportedError] if this number is not finite
+ /// (NaN or an infinity), .
int truncate();
- /**
- * Returns the integer double value closest to `this`.
- *
- * Rounds away from zero when there is no closest integer:
- * `(3.5).roundToDouble() == 4` and `(-3.5).roundToDouble() == -4`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is not
- * a finite value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`,
- * and `-0.0` is therefore considered closer to negative numbers than `0.0`.
- * This means that for a value, `d` in the range `-0.5 < d < 0.0`,
- * the result is `-0.0`.
- */
+ /// Returns the integer double value closest to `this`.
+ ///
+ /// Rounds away from zero when there is no closest integer:
+ /// `(3.5).roundToDouble() == 4` and `(-3.5).roundToDouble() == -4`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is not
+ /// a finite value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`,
+ /// and `-0.0` is therefore considered closer to negative numbers than `0.0`.
+ /// This means that for a value, `d` in the range `-0.5 < d < 0.0`,
+ /// the result is `-0.0`.
double roundToDouble();
- /**
- * Returns the greatest integer double value no greater than `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is not
- * a finite value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `0.0 < d < 1.0` will return `0.0`.
- */
+ /// Returns the greatest integer double value no greater than `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is not
+ /// a finite value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `0.0 < d < 1.0` will return `0.0`.
double floorToDouble();
- /**
- * Returns the least integer double value no smaller than `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is not
- * a finite value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`.
- */
+ /// Returns the least integer double value no smaller than `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is not
+ /// a finite value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`.
double ceilToDouble();
- /**
- * Returns the integer double value obtained by discarding any fractional
- * digits from `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is not
- * a finite value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`, and
- * in the range `0.0 < d < 1.0` it will return 0.0.
- */
+ /// Returns the integer double value obtained by discarding any fractional
+ /// digits from `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is not
+ /// a finite value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`, and
+ /// in the range `0.0 < d < 1.0` it will return 0.0.
double truncateToDouble();
- /**
- * Provide a representation of this [double] value.
- *
- * The representation is a number literal such that the closest double value
- * to the representation's mathematical value is this [double].
- *
- * Returns "NaN" for the Not-a-Number value.
- * Returns "Infinity" and "-Infinity" for positive and negative Infinity.
- * Returns "-0.0" for negative zero.
- *
- * For all doubles, `d`, converting to a string and parsing the string back
- * gives the same value again: `d == double.parse(d.toString())` (except when
- * `d` is NaN).
- */
+ /// Provide a representation of this [double] value.
+ ///
+ /// The representation is a number literal such that the closest double value
+ /// to the representation's mathematical value is this [double].
+ ///
+ /// Returns "NaN" for the Not-a-Number value.
+ /// Returns "Infinity" and "-Infinity" for positive and negative Infinity.
+ /// Returns "-0.0" for negative zero.
+ ///
+ /// For all doubles, `d`, converting to a string and parsing the string back
+ /// gives the same value again: `d == double.parse(d.toString())` (except when
+ /// `d` is NaN).
String toString();
- /**
- * Parse [source] as an double literal and return its value.
- *
- * Accepts an optional sign (`+` or `-`) followed by either the characters
- * "Infinity", the characters "NaN" or a floating-point representation.
- * A floating-point representation is composed of a mantissa and an optional
- * exponent part. The mantissa is either a decimal point (`.`) followed by a
- * sequence of (decimal) digits, or a sequence of digits
- * optionally followed by a decimal point and optionally more digits. The
- * (optional) exponent part consists of the character "e" or "E", an optional
- * sign, and one or more digits.
- * The [source] must not be `null`.
- *
- * Leading and trailing whitespace is ignored.
- *
- * If the [source] string is not a valid double literal, the [onError]
- * is called with the [source] as argument, and its return value is
- * used instead. If no `onError` is provided, a [FormatException]
- * is thrown instead.
- *
- * The [onError] function is only invoked if [source] is a [String] with an
- * invalid format. It is not invoked if [source] is `null`.
- *
- * Examples of accepted strings:
- *
- * "3.14"
- * " 3.14 \xA0"
- * "0."
- * ".0"
- * "-1.e3"
- * "1234E+7"
- * "+.12e-9"
- * "-NaN"
- *
- * The [onError] parameter is deprecated and will be removed.
- * Instead of `double.parse(string, (string) { ... })`,
- * you should use `double.tryParse(string) ?? (...)`.
- */
+ /// Parse [source] as an double literal and return its value.
+ ///
+ /// Accepts an optional sign (`+` or `-`) followed by either the characters
+ /// "Infinity", the characters "NaN" or a floating-point representation.
+ /// A floating-point representation is composed of a mantissa and an optional
+ /// exponent part. The mantissa is either a decimal point (`.`) followed by a
+ /// sequence of (decimal) digits, or a sequence of digits
+ /// optionally followed by a decimal point and optionally more digits. The
+ /// (optional) exponent part consists of the character "e" or "E", an optional
+ /// sign, and one or more digits.
+ /// The [source] must not be `null`.
+ ///
+ /// Leading and trailing whitespace is ignored.
+ ///
+ /// If the [source] string is not a valid double literal, the [onError]
+ /// is called with the [source] as argument, and its return value is
+ /// used instead.
+ /// Throws a [FormatException] if the [source] string is not valid
+ /// and no `onError` is provided.
+ ///
+ /// Examples of accepted strings:
+ /// ```dart
+ /// "3.14"
+ /// " 3.14 \xA0"
+ /// "0."
+ /// ".0"
+ /// "-1.e3"
+ /// "1234E+7"
+ /// "+.12e-9"
+ /// "-NaN"
+ /// ```
+ /// The [onError] parameter is deprecated and will be removed.
+ /// Instead of `double.parse(string, (string) { ... })`,
+ /// you should use `double.tryParse(string) ?? (...)`.
external static double parse(String source,
[@deprecated double onError(String source)?]);
- /**
- * Parse [source] as an double literal and return its value.
- *
- * Like [parse] except that this function returns `null` for invalid inputs
- * instead of throwing, and the [source] must still not be `null`.
- */
+ /// Parse [source] as an double literal and return its value.
+ ///
+ /// Like [parse] except that this function returns `null` for invalid inputs
+ /// instead of throwing.
external static double? tryParse(String source);
}
diff --git a/sdk/lib/core/duration.dart b/sdk/lib/core/duration.dart
index c4c6846..facbcdf 100644
--- a/sdk/lib/core/duration.dart
+++ b/sdk/lib/core/duration.dart
@@ -4,92 +4,117 @@
part of dart.core;
-/**
- * A span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.
- *
- * A `Duration` represents a difference from one point in time to another. The
- * duration may be "negative" if the difference is from a later time to an
- * earlier.
- *
- * Durations are context independent. For example, a duration of 2 days is
- * always 48 hours, even when it is added to a `DateTime` just when the
- * time zone is about to do a daylight-savings switch. (See [DateTime.add]).
- *
- * Despite the same name, a `Duration` object does not implement "Durations"
- * as specified by ISO 8601. In particular, a duration object does not keep
- * track of the individually provided members (such as "days" or "hours"), but
- * only uses these arguments to compute the length of the corresponding time
- * interval.
- *
- * To create a new Duration object, use this class's single constructor
- * giving the appropriate arguments:
- * ```dart
- * Duration fastestMarathon = new Duration(hours:2, minutes:3, seconds:2);
- * ```
- * The [Duration] is the sum of all individual parts.
- * This means that individual parts can be larger than the next-bigger unit.
- * For example, [inMinutes] can be greater than 59.
- * ```dart
- * assert(fastestMarathon.inMinutes == 123);
- * ```
- * All individual parts are allowed to be negative.
- *
- * Use one of the properties, such as [inDays],
- * to retrieve the integer value of the Duration in the specified time unit.
- * Note that the returned value is rounded down.
- * For example,
- * ```dart
- * Duration aLongWeekend = new Duration(hours:88);
- * assert(aLongWeekend.inDays == 3);
- * ```
- * This class provides a collection of arithmetic
- * and comparison operators,
- * plus a set of constants useful for converting time units.
- *
- * See [DateTime] to represent a point in time.
- * See [Stopwatch] to measure time-spans.
- */
+/// A span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.
+///
+/// A `Duration` represents a difference from one point in time to another. The
+/// duration may be "negative" if the difference is from a later time to an
+/// earlier.
+///
+/// Durations are context independent. For example, a duration of 2 days is
+/// always 48 hours, even when it is added to a `DateTime` just when the
+/// time zone is about to do a daylight-savings switch. (See [DateTime.add]).
+///
+/// Despite the same name, a `Duration` object does not implement "Durations"
+/// as specified by ISO 8601. In particular, a duration object does not keep
+/// track of the individually provided members (such as "days" or "hours"), but
+/// only uses these arguments to compute the length of the corresponding time
+/// interval.
+///
+/// To create a new Duration object, use this class's single constructor
+/// giving the appropriate arguments:
+/// ```dart
+/// var fastestMarathon = const Duration(hours: 2, minutes: 3, seconds: 2);
+/// ```
+/// The [Duration] is the sum of all individual parts.
+/// This means that individual parts can be larger than the next-bigger unit.
+/// For example, [inMinutes] can be greater than 59.
+/// ```dart
+/// assert(fastestMarathon.inMinutes == 123);
+/// ```
+/// All individual parts are allowed to be negative.
+///
+/// Use one of the properties, such as [inDays],
+/// to retrieve the integer value of the Duration in the specified time unit.
+/// Note that the returned value is rounded down.
+/// For example,
+/// ```dart
+/// var aLongWeekend = const Duration(hours: 88);
+/// assert(aLongWeekend.inDays == 3);
+/// ```
+/// This class provides a collection of arithmetic
+/// and comparison operators,
+/// plus a set of constants useful for converting time units.
+///
+/// See [DateTime] to represent a point in time.
+/// See [Stopwatch] to measure time-spans.
class Duration implements Comparable<Duration> {
+ /// The number of microseconds per millisecond.
static const int microsecondsPerMillisecond = 1000;
+
+ /// The number of milliseconds per second.
static const int millisecondsPerSecond = 1000;
+
+ /// The number of seconds per minute.
static const int secondsPerMinute = 60;
+
+ /// The number of minutes per hour.
static const int minutesPerHour = 60;
+
+ /// The number of hours per day.
static const int hoursPerDay = 24;
+ /// The number of microseconds per second.
static const int microsecondsPerSecond =
microsecondsPerMillisecond * millisecondsPerSecond;
+
+ /// The number of microseconds per minute.
static const int microsecondsPerMinute =
microsecondsPerSecond * secondsPerMinute;
+
+ /// The number of microseconds per hour.
static const int microsecondsPerHour = microsecondsPerMinute * minutesPerHour;
+
+ /// The number of microseconds per day.
static const int microsecondsPerDay = microsecondsPerHour * hoursPerDay;
+ /// The number of milliseconds per minute.
static const int millisecondsPerMinute =
millisecondsPerSecond * secondsPerMinute;
+
+ /// The number of milliseconds per hour.
static const int millisecondsPerHour = millisecondsPerMinute * minutesPerHour;
+
+ /// The number of milliseconds per day.
static const int millisecondsPerDay = millisecondsPerHour * hoursPerDay;
+ /// The number of seconds per hour.
static const int secondsPerHour = secondsPerMinute * minutesPerHour;
+
+ /// The number of seconds per day.
static const int secondsPerDay = secondsPerHour * hoursPerDay;
+ /// The number of minutes per day.
static const int minutesPerDay = minutesPerHour * hoursPerDay;
+ /// An empty duration, representing zero time.
static const Duration zero = Duration(seconds: 0);
- /*
- * The value of this Duration object in microseconds.
- */
+ /// The total microseconds of this [Duration] object.
final int _duration;
- /**
- * Creates a new Duration object whose value
- * is the sum of all individual parts.
- *
- * Individual parts can be larger than the next-bigger unit.
- * For example, [hours] can be greater than 23.
- *
- * All individual parts are allowed to be negative.
- * All arguments are 0 by default.
- */
+ /// Creates a new [Duration] object whose value
+ /// is the sum of all individual parts.
+ ///
+ /// Individual parts can be larger than the number of those
+ /// parts in the next larger unit.
+ /// For example, [hours] can be greater than 23.
+ /// If this happens, the value overflows into the next larger
+ /// unit, so 26 [hours] is the same as 2 [hours] and
+ /// one more [days].
+ /// Likewise, values can be negative, in which case they
+ /// underflow and subtract from the next larger unit.
+ ///
+ /// All arguments are 0 by default.
const Duration(
{int days = 0,
int hours = 0,
@@ -108,39 +133,31 @@
// [_microseconds] recomputation.
const Duration._microseconds(this._duration);
- /**
- * Adds this Duration and [other] and
- * returns the sum as a new Duration object.
- */
+ /// Adds this Duration and [other] and
+ /// returns the sum as a new Duration object.
Duration operator +(Duration other) {
return Duration._microseconds(_duration + other._duration);
}
- /**
- * Subtracts [other] from this Duration and
- * returns the difference as a new Duration object.
- */
+ /// Subtracts [other] from this Duration and
+ /// returns the difference as a new Duration object.
Duration operator -(Duration other) {
return Duration._microseconds(_duration - other._duration);
}
- /**
- * Multiplies this Duration by the given [factor] and returns the result
- * as a new Duration object.
- *
- * Note that when [factor] is a double, and the duration is greater than
- * 53 bits, precision is lost because of double-precision arithmetic.
- */
+ /// Multiplies this Duration by the given [factor] and returns the result
+ /// as a new Duration object.
+ ///
+ /// Note that when [factor] is a double, and the duration is greater than
+ /// 53 bits, precision is lost because of double-precision arithmetic.
Duration operator *(num factor) {
return Duration._microseconds((_duration * factor).round());
}
- /**
- * Divides this Duration by the given [quotient] and returns the truncated
- * result as a new Duration object.
- *
- * Throws an [IntegerDivisionByZeroException] if [quotient] is `0`.
- */
+ /// Divides this Duration by the given [quotient] and returns the truncated
+ /// result as a new Duration object.
+ ///
+ /// Throws an [IntegerDivisionByZeroException] if [quotient] is `0`.
Duration operator ~/(int quotient) {
// By doing the check here instead of relying on "~/" below we get the
// exception even with dart2js.
@@ -148,101 +165,87 @@
return Duration._microseconds(_duration ~/ quotient);
}
- /**
- * Returns `true` if the value of this Duration
- * is less than the value of [other].
- */
+ /// Whether this [Duration] is shorter than [other].
bool operator <(Duration other) => this._duration < other._duration;
- /**
- * Returns `true` if the value of this Duration
- * is greater than the value of [other].
- */
+ /// Whether this [Duration] is longer than [other].
bool operator >(Duration other) => this._duration > other._duration;
- /**
- * Returns `true` if the value of this Duration
- * is less than or equal to the value of [other].
- */
+ /// Whether this [Duration] is shorter than or equal to [other].
bool operator <=(Duration other) => this._duration <= other._duration;
- /**
- * Returns `true` if the value of this Duration
- * is greater than or equal to the value of [other].
- */
+ /// Whether this [Duration] is longer than or equal to [other].
bool operator >=(Duration other) => this._duration >= other._duration;
- /**
- * Returns the number of whole days spanned by this Duration.
- */
+ /// The number of entire days spanned by this [Duration].
int get inDays => _duration ~/ Duration.microsecondsPerDay;
- /**
- * Returns the number of whole hours spanned by this Duration.
- *
- * The returned value can be greater than 23.
- */
+ /// The number of entire hours spanned by this [Duration].
+ ///
+ /// The returned value can be greater than 23.
+ /// For example a duration of four days and three hours
+ /// has 99 entire hours.
int get inHours => _duration ~/ Duration.microsecondsPerHour;
- /**
- * Returns the number of whole minutes spanned by this Duration.
- *
- * The returned value can be greater than 59.
- */
+ /// The number of whole minutes spanned by this [Duration].
+ ///
+ /// The returned value can be greater than 59.
+ /// For example a duration of three hours and 12 minutes
+ /// has 192 minutes.
int get inMinutes => _duration ~/ Duration.microsecondsPerMinute;
- /**
- * Returns the number of whole seconds spanned by this Duration.
- *
- * The returned value can be greater than 59.
- */
+ /// The number of whole seconds spanned by this [Duration].
+ ///
+ /// The returned value can be greater than 59.
+ /// For example a duration of three minutes and 12 seconds
+ /// has 192 seconds.
int get inSeconds => _duration ~/ Duration.microsecondsPerSecond;
- /**
- * Returns number of whole milliseconds spanned by this Duration.
- *
- * The returned value can be greater than 999.
- */
+ /// The number of whole milliseconds spanned by this [Duration].
+ ///
+ /// The returned value can be greater than 999.
+ /// For example a duration of three seconds and 125 milliseconds
+ /// has 3125 milliseconds.
int get inMilliseconds => _duration ~/ Duration.microsecondsPerMillisecond;
- /**
- * Returns number of whole microseconds spanned by this Duration.
- */
+ /// The number of whole microseconds spanned by this [Duration].
+ ///
+ /// The returned value can be greater than 999999.
+ /// For example a duration of three seconds, 125 milliseconds and
+ /// 369 microseconds has 3125369 microseconds.
int get inMicroseconds => _duration;
- /**
- * Returns `true` if this [Duration] has the same value as [other].
- */
+ /// Whether this [Duration] has the same length as [other].
+ ///
+ /// Durations have the same length if they have the same number
+ /// of microseconds, as reported by [inMicroseconds].
bool operator ==(Object other) =>
other is Duration && _duration == other.inMicroseconds;
int get hashCode => _duration.hashCode;
- /**
- * Compares this [Duration] to [other], returning zero if the values are equal.
- *
- * Returns a negative integer if this `Duration` is shorter than
- * [other], or a positive integer if it is longer.
- *
- * A negative `Duration` is always considered shorter than a positive one.
- *
- * It is always the case that `duration1.compareTo(duration2) < 0` iff
- * `(someDate + duration1).compareTo(someDate + duration2) < 0`.
- */
+ /// Compares this [Duration] to [other], returning zero if the values are equal.
+ ///
+ /// Returns a negative integer if this [Duration] is shorter than
+ /// [other], or a positive integer if it is longer.
+ ///
+ /// A negative [Duration] is always considered shorter than a positive one.
+ ///
+ /// It is always the case that `duration1.compareTo(duration2) < 0` iff
+ /// `(someDate + duration1).compareTo(someDate + duration2) < 0`.
int compareTo(Duration other) => _duration.compareTo(other._duration);
- /**
- * Returns a string representation of this `Duration`.
- *
- * Returns a string with hours, minutes, seconds, and microseconds, in the
- * following format: `H:MM:SS.mmmmmm`. For example,
- *
- * var d = Duration(days: 1, hours: 1, minutes: 33, microseconds: 500);
- * d.toString(); // "25:33:00.000500"
- *
- * d = Duration(days: 0, hours: 1, minutes: 10, microseconds: 500);
- * d.toString(); // "1:10:00.000500"
- */
+ /// Returns a string representation of this [Duration].
+ ///
+ /// Returns a string with hours, minutes, seconds, and microseconds, in the
+ /// following format: `H:MM:SS.mmmmmm`. For example,
+ /// ```dart
+ /// var d = Duration(days: 1, hours: 1, minutes: 33, microseconds: 500);
+ /// d.toString(); // "25:33:00.000500"
+ ///
+ /// d = Duration(days: 0, hours: 1, minutes: 10, microseconds: 500);
+ /// d.toString(); // "1:10:00.000500"
+ /// ```
String toString() {
String sixDigits(int n) {
if (n >= 100000) return "$n";
@@ -270,29 +273,23 @@
return "$inHours:$twoDigitMinutes:$twoDigitSeconds.$sixDigitUs";
}
- /**
- * Returns whether this `Duration` is negative.
- *
- * A negative `Duration` represents the difference from a later time to an
- * earlier time.
- */
+ /// Whether this [Duration] is negative.
+ ///
+ /// A negative [Duration] represents the difference from a later time to an
+ /// earlier time.
bool get isNegative => _duration < 0;
- /**
- * Returns a new `Duration` representing the absolute value of this
- * `Duration`.
- *
- * The returned `Duration` has the same length as this one, but is always
- * positive.
- */
+ /// Creates a new [Duration] representing the absolute length of this
+ /// [Duration].
+ ///
+ /// The returned [Duration] has the same length as this one, but is always
+ /// positive.
Duration abs() => Duration._microseconds(_duration.abs());
- /**
- * Returns a new `Duration` representing this `Duration` negated.
- *
- * The returned `Duration` has the same length as this one, but will have the
- * opposite sign of this one.
- */
+ /// Creates a new [Duration] with the opposite direction of this [Duration].
+ ///
+ /// The returned [Duration] has the same length as this one, but will have the
+ /// opposite sign (as reported by [isNegative]) as this one.
// Using subtraction helps dart2js avoid negative zeros.
Duration operator -() => Duration._microseconds(0 - _duration);
}
diff --git a/sdk/lib/core/errors.dart b/sdk/lib/core/errors.dart
index a84c6ee..d30b436 100644
--- a/sdk/lib/core/errors.dart
+++ b/sdk/lib/core/errors.dart
@@ -4,76 +4,73 @@
part of dart.core;
-/**
- * Error objects thrown in the case of a program failure.
- *
- * An `Error` object represents a program failure that the programmer
- * should have avoided.
- *
- * Examples include calling a function with invalid arguments,
- * 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 -
- * if they occur, the program is erroneous,
- * and terminating the program may be the safest response.
- *
- * When deciding that a function throws 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.
- *
- * Such descriptions often uses words like
- * "must" or "must not" to describe the condition,
- * and if you see words like that in a function's documentation,
- * then not satisfying the requirement
- * is very likely to cause an error to be thrown.
- *
- * Example (from [String.contains]):
- *
- * `startIndex` must not be negative or greater than `length`.
- *
- * In this case, an error will be thrown if `startIndex` is negative
- * or too large.
- *
- * If the conditions are not detectable before calling a function,
- * the called function should not throw an `Error`.
- * It may still throw a value,
- * but the caller will have to catch the thrown value,
- * effectively making it an alternative result rather than an error.
- * The thrown object can choose to implement [Exception]
- * to document that it represents an exceptional, but not erroneous, occurrence,
- * but it has no other effect than documentation.
- *
- * All non-`null` values can be thrown in Dart.
- * Objects extending `Error` are handled specially:
- * The first time they are thrown,
- * the stack trace at the throw point is recorded
- * and stored in the error object.
- * It can be retrieved using the [stackTrace] getter.
- * An error object that merely implements `Error`, and doesn't extend it,
- * 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.
- *
- * Since errors are not created to be caught,
- * there is no need for subclasses to distinguish the errors.
- * Instead subclasses have been created in order to make groups
- * of related errors easy to create with consistent error messages.
- * 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 `new RangeError.range(startIndex, 0, length)`.
- */
+/// Error objects thrown in the case of a program failure.
+///
+/// An `Error` object represents a program failure that the programmer
+/// should have avoided.
+///
+/// Examples include calling a function with invalid arguments,
+/// 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 -
+/// if they occur, the program is erroneous,
+/// and terminating the program may be the safest response.
+///
+/// When deciding that a function throws 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.
+///
+/// Such descriptions often uses words like
+/// "must" or "must not" to describe the condition,
+/// and if you see words like that in a function's documentation,
+/// then not satisfying the requirement
+/// is very likely to cause an error to be thrown.
+///
+/// Example (from [String.contains]):
+/// ```
+/// `startIndex` must not be negative or greater than `length`.
+/// ```
+/// In this case, an error will be thrown if `startIndex` is negative
+/// or too large.
+///
+/// If the conditions are not detectable before calling a function,
+/// the called function should not throw an `Error`.
+/// It may still throw,
+/// but the caller will have to catch the thrown value,
+/// effectively making it an alternative result 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 [Excpetion] has no other effect
+/// than documentation.
+///
+/// All non-`null` values can be thrown in Dart.
+/// Objects extending `Error` are handled specially:
+/// The first time they are thrown,
+/// the stack trace at the throw point is recorded
+/// and stored in the error object.
+/// It can be retrieved using the [stackTrace] getter.
+/// An error object that merely implements `Error`, and doesn't extend it,
+/// 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.
+///
+/// Since errors are not created to be caught,
+/// there is no need for subclasses to distinguish the errors.
+/// Instead subclasses have been created in order to make groups
+/// of related errors easy to create with consistent error messages.
+/// 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)`.
class Error {
Error(); // Prevent use as mixin.
- /**
- * Safely convert a value to a [String] description.
- *
- * The conversion is guaranteed to not throw, so it won't use the object's
- * toString method.
- */
+ /// Safely convert a value to a [String] description.
+ ///
+ /// The conversion is guaranteed to not throw, so it won't use the object's
+ /// toString method except for specific known and trusted types.
static String safeToString(Object? object) {
if (object is num || object is bool || null == object) {
return object.toString();
@@ -84,21 +81,25 @@
return _objectToString(object);
}
- /** Convert string to a valid string literal with no control characters. */
+ /// Convert string to a valid string literal with no control characters.
external static String _stringToSafeString(String string);
external static String _objectToString(Object object);
+ /// The stack trace at the point where this error was first thrown.
+ ///
+ /// Classes which *extend* `Error` will automatically have a stack
+ /// trace filled in the first time they are thrown by a `throw`
+ /// expression.
external StackTrace? get stackTrace;
}
-/**
- * Error thrown by the runtime system when an assert statement fails.
- */
+/// Error thrown by the runtime system when an assert statement fails.
class AssertionError extends Error {
- /** Message describing the assertion error. */
+ /// Message describing the assertion error.
final Object? message;
+ /// Creates an assertion error with the provided [message].
AssertionError([this.message]);
String toString() {
@@ -109,86 +110,73 @@
}
}
-/**
- * Error thrown by the runtime system when a dynamic type error happens.
- */
+/// Error thrown by the runtime system when a dynamic type error happens.
class TypeError extends Error {}
-/**
- * Error thrown by the runtime system when a cast operation fails.
- */
+/// Error thrown by the runtime system when a cast operation fails.
@Deprecated("Use TypeError instead")
class CastError extends Error {}
-/**
- * Error thrown when attempting to throw `null`.
- */
+/// Error thrown when attempting to throw `null`.
class NullThrownError extends Error {
@pragma("vm:entry-point")
NullThrownError();
String toString() => "Throw of null.";
}
-/**
- * Error thrown when a function is passed an unacceptable argument.
- */
+/// Error thrown when a function is passed an unacceptable argument.
class ArgumentError extends Error {
- /** Whether value was provided. */
+ /// Whether value was provided.
final bool _hasValue;
- /** The invalid value. */
+
+ /// The invalid value.
final dynamic invalidValue;
- /** Name of the invalid argument, if available. */
+
+ /// Name of the invalid argument, if available.
final String? name;
- /** Message describing the problem. */
+
+ /// Message describing the problem.
final dynamic message;
- /**
- * The [message] describes the erroneous argument.
- *
- * Existing code may be using `message` to hold the invalid value.
- * If the `message` is not a [String], it is assumed to be a value instead
- * of a message.
- */
+ /// Creates an error with [message] describing the problem with an argument.
+ ///
+ /// Existing code may be using `message` to hold the invalid value.
+ /// If the `message` is not a [String], it is assumed to be a value instead
+ /// of a message.
@pragma("vm:entry-point")
ArgumentError([this.message])
: invalidValue = null,
_hasValue = false,
name = null;
- /**
- * Creates error containing the invalid [value].
- *
- * A message is built by suffixing the [message] argument with
- * the [name] argument (if provided) and the value. Example
- *
- * "Invalid argument (foo): null"
- *
- * The `name` should match the argument name of the function, but if
- * the function is a method implementing an interface, and its argument
- * names differ from the interface, it might be more useful to use the
- * interface method's argument name (or just rename arguments to match).
- */
+ /// Creates error containing the invalid [value].
+ ///
+ /// A message is built by suffixing the [message] argument with
+ /// the [name] argument (if provided) and the value. Example:
+ /// ```
+ /// "Invalid argument (foo): null"
+ /// ```
+ /// The `name` should match the argument name of the function, but if
+ /// the function is a method implementing an interface, and its argument
+ /// names differ from the interface, it might be more useful to use the
+ /// interface method's argument name (or just rename arguments to match).
@pragma("vm:entry-point")
ArgumentError.value(value, [this.name, this.message])
: invalidValue = value,
_hasValue = true;
- /**
- * Create an argument error for a `null` argument that must not be `null`.
- */
+ /// Creates an argument error for a `null` argument that must not be `null`.
ArgumentError.notNull([this.name])
: _hasValue = false,
message = "Must not be null",
invalidValue = null;
- /**
- * Throws if [argument] is `null`.
- *
- * If [name] is supplied, it is used as the parameter name
- * in the error message.
- *
- * Returns the [argument] if it is not null.
- */
+ /// Throws if [argument] is `null`.
+ ///
+ /// If [name] is supplied, it is used as the parameter name
+ /// in the error message.
+ ///
+ /// 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);
@@ -213,52 +201,45 @@
}
}
-/**
- * Error thrown due to an index being outside a valid range.
- */
+/// Error thrown due to a value being outside a valid range.
class RangeError extends ArgumentError {
- /** The minimum value that [value] is allowed to assume. */
+ /// The minimum value that [value] is allowed to assume.
final num? start;
- /** The maximum value that [value] is allowed to assume. */
+
+ /// The maximum value that [value] is allowed to assume.
final num? end;
// 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].
- */
+ /// Create a new [RangeError] with the given [message].
@pragma("vm:entry-point")
RangeError(var message)
: start = null,
end = null,
super(message);
- /**
- * Create a new [RangeError] with a message for the given [value].
- *
- * An optional [name] can specify the argument name that has the
- * invalid value, and the [message] can override the default error
- * description.
- */
+ /// Create a new [RangeError] with a message for the given [value].
+ ///
+ /// An optional [name] can specify the argument name that has the
+ /// invalid value, and the [message] can override the default error
+ /// description.
RangeError.value(num value, [String? name, String? message])
: start = null,
end = null,
super.value(value, name, message ?? "Value not in range");
- /**
- * Create a new [RangeError] for a value being outside the valid range.
- *
- * The allowed range is from [minValue] to [maxValue], inclusive.
- * If `minValue` or `maxValue` are `null`, the range is infinite in
- * that direction.
- *
- * For a range from 0 to the length of something, end exclusive, use
- * [RangeError.index].
- *
- * An optional [name] can specify the argument name that has the
- * invalid value, and the [message] can override the default error
- * description.
- */
+ /// Create a new [RangeError] for a value being outside the valid range.
+ ///
+ /// The allowed range is from [minValue] to [maxValue], inclusive.
+ /// If `minValue` or `maxValue` are `null`, the range is infinite in
+ /// that direction.
+ ///
+ /// For a range from 0 to the length of something, end exclusive, use
+ /// [RangeError.index].
+ ///
+ /// An optional [name] can specify the argument name that has the
+ /// invalid value, and the [message] can override the default error
+ /// description.
@pragma("vm:entry-point")
RangeError.range(num invalidValue, int? minValue, int? maxValue,
[String? name, String? message])
@@ -266,31 +247,27 @@
end = maxValue,
super.value(invalidValue, name, message ?? "Invalid value");
- /**
- * Creates a new [RangeError] stating that [index] is not a valid index
- * into [indexable].
- *
- * An optional [name] can specify the argument name that has the
- * invalid value, and the [message] can override the default error
- * description.
- *
- * The [length] is the length of [indexable] at the time of the error.
- * If `length` is omitted, it defaults to `indexable.length`.
- */
+ /// Creates a new [RangeError] stating that [index] is not a valid index
+ /// into [indexable].
+ ///
+ /// An optional [name] can specify the argument name that has the
+ /// invalid value, and the [message] can override the default error
+ /// description.
+ ///
+ /// The [length] is the length of [indexable] at the time of the error.
+ /// If `length` is omitted, it defaults to `indexable.length`.
factory RangeError.index(int index, dynamic indexable,
[String? name, String? message, int? length]) = IndexError;
- /**
- * Check that an integer [value] lies in a specific interval.
- *
- * Throws if [value] is not in the interval.
- * The interval is from [minValue] to [maxValue], both inclusive.
- *
- * If [name] or [message] are provided, they are used as the parameter
- * name and message text of the thrown error.
- *
- * Returns [value] if it is in the interval.
- */
+ /// Check that an integer [value] lies in a specific interval.
+ ///
+ /// Throws if [value] is not in the interval.
+ /// The interval is from [minValue] to [maxValue], both inclusive.
+ ///
+ /// If [name] or [message] are provided, they are used as the parameter
+ /// name and message text of the thrown error.
+ ///
+ /// Returns [value] if it is in the interval.
static int checkValueInInterval(int value, int minValue, int maxValue,
[String? name, String? message]) {
if (value < minValue || value > maxValue) {
@@ -299,23 +276,21 @@
return value;
}
- /**
- * Check that [index] is a valid index into an indexable object.
- *
- * Throws if [index] is not a valid index into [indexable].
- *
- * An indexable object is one that has a `length` and a and index-operator
- * `[]` that accepts an index if `0 <= index < length`.
- *
- * If [name] or [message] are provided, they are used as the parameter
- * name and message text of the thrown error. If [name] is omitted, it
- * defaults to `"index"`.
- *
- * If [length] is provided, it is used as the length of the indexable object,
- * otherwise the length is found as `indexable.length`.
- *
- * Returns [index] if it is a valid index.
- */
+ /// Check that [index] is a valid index into an indexable object.
+ ///
+ /// Throws if [index] is not a valid index into [indexable].
+ ///
+ /// An indexable object is one that has a `length` and a and index-operator
+ /// `[]` that accepts an index if `0 <= index < length`.
+ ///
+ /// If [name] or [message] are provided, they are used as the parameter
+ /// name and message text of the thrown error. If [name] is omitted, it
+ /// defaults to `"index"`.
+ ///
+ /// If [length] is provided, it is used as the length of the indexable object,
+ /// otherwise the length is found as `indexable.length`.
+ ///
+ /// Returns [index] if it is a valid index.
static int checkValidIndex(int index, dynamic indexable,
[String? name, int? length, String? message]) {
length ??= (indexable.length as int);
@@ -327,22 +302,20 @@
return index;
}
- /**
- * Check that a range represents a slice of an indexable object.
- *
- * Throws if the range is not valid for an indexable object with
- * the given [length].
- * A range is valid for an indexable object with a given [length]
- *
- * if `0 <= [start] <= [end] <= [length]`.
- * An `end` of `null` is considered equivalent to `length`.
- *
- * The [startName] and [endName] defaults to `"start"` and `"end"`,
- * respectively.
- *
- * Returns the actual `end` value, which is `length` if `end` is `null`,
- * and `end` otherwise.
- */
+ /// Check that a range represents a slice of an indexable object.
+ ///
+ /// Throws if the range is not valid for an indexable object with
+ /// the given [length].
+ /// A range is valid for an indexable object with a given [length]
+ ///
+ /// if `0 <= [start] <= [end] <= [length]`.
+ /// An `end` of `null` is considered equivalent to `length`.
+ ///
+ /// The [startName] and [endName] defaults to `"start"` and `"end"`,
+ /// respectively.
+ ///
+ /// Returns the actual `end` value, which is `length` if `end` is `null`,
+ /// and `end` otherwise.
static int checkValidRange(int start, int? end, int length,
[String? startName, String? endName, String? message]) {
// Comparing with `0` as receiver produces better dart2js type inference.
@@ -361,19 +334,19 @@
return length;
}
- /**
- * Check that an integer value is non-negative.
- *
- * Throws if the value is negative.
- *
- * If [name] or [message] are provided, they are used as the parameter
- * name and message text of the thrown error. If [name] is omitted, it
- * defaults to `index`.
- *
- * Returns [value] if it is not negative.
- */
+ /// Check that an integer value is non-negative.
+ ///
+ /// Throws if the value is negative.
+ ///
+ /// If [name] or [message] are provided, they are used as the parameter
+ /// name and message text of the thrown error. If [name] is omitted, it
+ /// defaults to `index`.
+ ///
+ /// Returns [value] if it is not negative.
static int checkNotNegative(int value, [String? name, String? message]) {
- if (value < 0) throw RangeError.range(value, 0, null, name, message);
+ if (value < 0) {
+ throw RangeError.range(value, 0, null, name ?? "index", message);
+ }
return value;
}
@@ -402,28 +375,25 @@
}
}
-/**
- * A specialized [RangeError] used when an index is not in the range
- * `0..indexable.length-1`.
- *
- * Also contains the indexable object, its length at the time of the error,
- * and the invalid index itself.
- */
+/// A specialized [RangeError] used when an index is not in the range
+/// `0..indexable.length-1`.
+///
+/// Also contains the indexable object, its length at the time of the error,
+/// and the invalid index itself.
class IndexError extends ArgumentError implements RangeError {
- /** The indexable object that [invalidValue] was not a valid index into. */
+ /// The indexable object that [invalidValue] was not a valid index into.
final indexable;
- /** The length of [indexable] at the time of the error. */
+
+ /// The length of [indexable] at the time of the error.
final int length;
- /**
- * Creates a new [IndexError] stating that [invalidValue] is not a valid index
- * into [indexable].
- *
- * The [length] is the length of [indexable] at the time of the error.
- * If `length` is omitted, it defaults to `indexable.length`.
- *
- * The message is used as part of the string representation of the error.
- */
+ /// Creates a new [IndexError] stating that [invalidValue] is not a valid index
+ /// into [indexable].
+ ///
+ /// The [length] is the length of [indexable] at the time of the error.
+ /// If `length` is omitted, it defaults to `indexable.length`.
+ ///
+ /// The message is used as part of the string representation of the error.
IndexError(int invalidValue, dynamic indexable,
[String? name, String? message, int? length])
: this.indexable = indexable,
@@ -448,14 +418,12 @@
}
}
-/**
- * Error thrown when control reaches the end of a switch case.
- *
- * The Dart specification requires this error to be thrown when
- * control reaches the end of a switch case (except the last case
- * of a switch) without meeting a break or similar end of the control
- * flow.
- */
+/// Error thrown when control reaches the end of a switch case.
+///
+/// The Dart specification requires this error to be thrown when
+/// control reaches the end of a switch case (except the last case
+/// of a switch) without meeting a break or similar end of the control
+/// flow.
class FallThroughError extends Error {
FallThroughError();
@pragma("vm:entry-point")
@@ -464,9 +432,10 @@
external String toString();
}
-/**
- * Error thrown when trying to instantiate an abstract class.
- */
+/// Error thrown when trying to instantiate an abstract class.
+///
+/// No longer used in Dart 2 where it has become a compile-time error
+/// to call the constructor of an abstract class.
class AbstractClassInstantiationError extends Error {
final String _className;
AbstractClassInstantiationError(String className) : _className = className;
@@ -474,46 +443,39 @@
external String toString();
}
-/**
- * Error thrown by the default implementation of [:noSuchMethod:] on [Object].
- */
+/// Error thrown by the default implementation of `noSuchMethod` on [Object].
class NoSuchMethodError extends Error {
- /**
- * Create a [NoSuchMethodError] corresponding to a failed method call.
- *
- * The [receiver] is the receiver of the method call.
- * That is, the object on which the method was attempted called.
- *
- * The [invocation] represents the method call that failed. It
- * should not be `null`.
- */
+ /// Create a [NoSuchMethodError] corresponding to a failed method call.
+ ///
+ /// The [receiver] is the receiver of the method call.
+ /// That is, the object on which the method was attempted called.
+ ///
+ /// The [invocation] represents the method call that failed.
external NoSuchMethodError.withInvocation(
Object? receiver, Invocation invocation);
// Deprecated constructor to be removed after dart2js updates to the above.
- /**
- * Create a [NoSuchMethodError] corresponding to a failed method call.
- *
- * The [receiver] is the receiver of the method call.
- * That is, the object on which the method was attempted called.
- * If the receiver is `null`, it is interpreted as a call to a top-level
- * function of a library.
- *
- * The [memberName] is a [Symbol] representing the name of the called method
- * or accessor. It should not be `null`.
- *
- * The [positionalArguments] is a list of the positional arguments that the
- * method was called with. If `null`, it is considered equivalent to the
- * empty list.
- *
- * The [namedArguments] is a map from [Symbol]s to the values of named
- * arguments that the method was called with. If null, it is considered
- * equivalent to the empty map.
- *
- * This constructor does not handle type arguments.
- * To include type variables, create an [Invocation] and use
- * [NoSuchMethodError.withInvocation].
- */
+ /// Create a [NoSuchMethodError] corresponding to a failed method call.
+ ///
+ /// The [receiver] is the receiver of the method call.
+ /// That is, the object on which the method was attempted called.
+ /// If the receiver is `null`, it is interpreted as a call to a top-level
+ /// function of a library.
+ ///
+ /// The [memberName] is a [Symbol] representing the name of the called method
+ /// or accessor.
+ ///
+ /// The [positionalArguments] is a list of the positional arguments that the
+ /// method was called with. If `null`, it is considered equivalent to the
+ /// empty list.
+ ///
+ /// The [namedArguments] is a map from [Symbol]s to the values of named
+ /// arguments that the method was called with. If `null`, it is considered
+ /// equivalent to the empty map.
+ ///
+ /// This constructor does not handle type arguments.
+ /// To include type variables, create an [Invocation] and use
+ /// [NoSuchMethodError.withInvocation].
@Deprecated("Use NoSuchMethod.withInvocation instead")
external NoSuchMethodError(Object? receiver, Symbol memberName,
List? positionalArguments, Map<Symbol, dynamic>? namedArguments);
@@ -521,12 +483,10 @@
external String toString();
}
-/**
- * The operation was not allowed by the object.
- *
- * This [Error] is thrown when an instance cannot implement one of the methods
- * in its signature.
- */
+/// The operation was not allowed by the object.
+///
+/// This [Error] is thrown when an instance cannot implement one of the methods
+/// in its signature.
@pragma("vm:entry-point")
class UnsupportedError extends Error {
final String? message;
@@ -535,16 +495,14 @@
String toString() => "Unsupported operation: $message";
}
-/**
- * Thrown by operations that have not been implemented yet.
- *
- * This [Error] is thrown by unfinished code that hasn't yet implemented
- * all the features it needs.
- *
- * If a class is not intending to implement the feature, it should throw
- * an [UnsupportedError] instead. This error is only intended for
- * use during development.
- */
+/// Thrown by operations that have not been implemented yet.
+///
+/// This [Error] is thrown by unfinished code that hasn't yet implemented
+/// all the features it needs.
+///
+/// If the class does not intend to implement the feature, it should throw
+/// an [UnsupportedError] instead. This error is only intended for
+/// use during development.
class UnimplementedError extends Error implements UnsupportedError {
final String? message;
UnimplementedError([this.message]);
@@ -556,27 +514,31 @@
}
}
-/**
- * The operation was not allowed by the current state of the object.
- *
- * This is a generic error used for a variety of different erroneous
- * actions. The message should be descriptive.
- */
+/// The operation was not allowed by the current state of the object.
+///
+/// Should be used when this particular object is currenty 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.
+/// Example: Asking for `list.first` on a currently empty list.
+/// If the operation is never supported, consider using
+/// [UnsupportedError] instead.
+///
+/// This is a generic error used for a variety of different erroneous
+/// actions. The message should be descriptive.
class StateError extends Error {
final String message;
StateError(this.message);
String toString() => "Bad state: $message";
}
-/**
- * Error occurring when a collection is modified during iteration.
- *
- * Some modifications may be allowed for some collections, so each collection
- * ([Iterable] or similar collection of values) should declare which operations
- * are allowed during an iteration.
- */
+/// Error occurring when a collection is modified during iteration.
+///
+/// Some modifications may be allowed for some collections, so each collection
+/// ([Iterable] or similar collection of values) should declare which operations
+/// are allowed during an iteration.
class ConcurrentModificationError extends Error {
- /** The object that was modified in an incompatible way. */
+ /// The object that was modified in an incompatible way.
final Object? modifiedObject;
ConcurrentModificationError([this.modifiedObject]);
@@ -590,6 +552,7 @@
}
}
+/// Error that the platform can use in case of memory shortage.
class OutOfMemoryError implements Error {
@pragma("vm:entry-point")
const OutOfMemoryError();
@@ -598,6 +561,7 @@
StackTrace? get stackTrace => null;
}
+/// Error that the platform can use in case of stack overflow.
class StackOverflowError implements Error {
@pragma("vm:entry-point")
const StackOverflowError();
@@ -606,13 +570,11 @@
StackTrace? get stackTrace => null;
}
-/**
- * Error thrown when a lazily initialized variable cannot be initialized.
- *
- * A static/library variable with an initializer expression is initialized
- * the first time it is read. If evaluating the initializer expression causes
- * another read of the variable, this error is thrown.
- */
+/// Error thrown when a lazily initialized variable cannot be initialized.
+///
+/// No longer used in null safe Dart code,
+/// replaced by late variables and [LateInitializationError].
+// TODO: Deprecate?
class CyclicInitializationError extends Error {
final String? variableName;
@pragma("vm:entry-point")
@@ -625,19 +587,17 @@
}
}
-/**
- * Error thrown when a late variable is accessed in an invalid manner.
- *
- * A late variable must be initialized before it's read.
- * If a late variable has no initializer expression and has not
- * been written to, then reading it will throw a
- * late initialization error.
- *
- * A late final variable with no initializer expression may only
- * be written to once.
- * If it is written to again, the writing will throw a
- * late initialization error.
- */
+/// Error thrown when a late variable is accessed in an invalid manner.
+///
+/// A late variable must be initialized before it's read.
+/// If a late variable has no initializer expression and has not
+/// been written to, then reading it will throw a
+/// late initialization error.
+///
+/// A late final variable with no initializer expression may only
+/// be written to once.
+/// If it is written to again, the writing will throw a
+/// late initialization error.
abstract class LateInitializationError extends Error {
factory LateInitializationError._() => throw UnsupportedError("");
}
diff --git a/sdk/lib/core/exceptions.dart b/sdk/lib/core/exceptions.dart
index 7d76a66..5904ec5 100644
--- a/sdk/lib/core/exceptions.dart
+++ b/sdk/lib/core/exceptions.dart
@@ -6,23 +6,21 @@
// Exceptions are thrown either by the VM or from Dart code.
-/**
- * A marker interface implemented by all core library exceptions.
- *
- * An [Exception] is intended to convey information to the user about a failure,
- * so that the error can be addressed programmatically. It is intended to be
- * caught, and it should contain useful data fields.
- *
- * Creating instances of [Exception] directly with `Exception("message")`
- * is discouraged in library code since it doesn't give users a precise
- * type they can catch. It may be reasonable to use instances of this
- * class in tests or during development.
- */
+/// A marker interface implemented by all core library exceptions.
+///
+/// An [Exception] is intended to convey information to the user about a failure,
+/// so that the error can be addressed programmatically. It is intended to be
+/// caught, and it should contain useful data fields.
+///
+/// Creating instances of [Exception] directly with `Exception("message")`
+/// is discouraged in library code since it doesn't give users a precise
+/// type they can catch. It may be reasonable to use instances of this
+/// class in tests or during development.
abstract class Exception {
factory Exception([var message]) => _Exception(message);
}
-/** Default implementation of [Exception] which carries a message. */
+/// Default implementation of [Exception] which carries a message.
class _Exception implements Exception {
final dynamic message;
@@ -35,65 +33,53 @@
}
}
-/**
- * Exception thrown when a string or some other data does not have an expected
- * format and cannot be parsed or processed.
- */
+/// Exception thrown when a string or some other data does not have an expected
+/// format and cannot be parsed or processed.
class FormatException implements Exception {
- /**
- * A message describing the format error.
- */
+ /// A message describing the format error.
final String message;
- /**
- * The actual source input which caused the error.
- *
- * This is usually a [String], but can be other types too.
- * If it is a string, parts of it may be included in the [toString] message.
- *
- * The source is `null` if omitted or unknown.
- */
+ /// The actual source input which caused the error.
+ ///
+ /// This is usually a [String], but can be other types too.
+ /// If it is a string, parts of it may be included in the [toString] message.
+ ///
+ /// The source is `null` if omitted or unknown.
final dynamic source;
- /**
- * The offset in [source] where the error was detected.
- *
- * A zero-based offset into the source that marks the format error causing
- * this exception to be created. If `source` is a string, this should be a
- * string index in the range `0 <= offset <= source.length`.
- *
- * If input is a string, the [toString] method may represent this offset as
- * a line and character position. The offset should be inside the string,
- * or at the end of the string.
- *
- * May be omitted. If present, [source] should also be present if possible.
- */
+ /// The offset in [source] where the error was detected.
+ ///
+ /// A zero-based offset into the source that marks the format error causing
+ /// this exception to be created. If `source` is a string, this should be a
+ /// string index in the range `0 <= offset <= source.length`.
+ ///
+ /// If input is a string, the [toString] method may represent this offset as
+ /// a line and character position. The offset should be inside the string,
+ /// or at the end of the string.
+ ///
+ /// May be omitted. If present, [source] should also be present if possible.
final int? offset;
- /**
- * Creates a new FormatException with an optional error [message].
- *
- * Optionally also supply the actual [source] with the incorrect format,
- * and the [offset] in the format where a problem was detected.
- */
+ /// Creates a new `FormatException` with an optional error [message].
+ ///
+ /// Optionally also supply the actual [source] with the incorrect format,
+ /// and the [offset] in the format where a problem was detected.
@pragma("vm:entry-point")
const FormatException([this.message = "", this.source, this.offset]);
- /**
- * Returns a description of the format exception.
- *
- * The description always contains the [message].
- *
- * If [source] is present and is a string, the description will contain
- * (at least a part of) the source.
- * If [offset] is also provided, the part of the source included will
- * contain that offset, and the offset will be marked.
- *
- * If the source is a string and it contains a line break before offset,
- * only the line containing offset will be included, and its line number
- * will also be part of the description. Line and character offsets are
- * 1-based.
- */
+ /// Returns a description of the format exception.
+ ///
+ /// The description always contains the [message].
+ ///
+ /// If [source] is present and is a string, the description will contain
+ /// (at least a part of) the source.
+ /// If [offset] is also provided, the part of the source included will
+ /// contain that offset, and the offset will be marked.
+ ///
+ /// If the source is a string and it contains a line break before offset,
+ /// only the line containing offset will be included, and its line number
+ /// will also be part of the description. Line and character offsets are
+ /// 1-based.
String toString() {
String report = "FormatException";
Object? message = this.message;
@@ -179,6 +165,8 @@
}
// Exception thrown when doing integer division with a zero divisor.
+// TODO(30743): Should be removed, and division by zero should just throw an
+// [ArgumentError].
class IntegerDivisionByZeroException implements Exception {
@pragma("vm:entry-point")
const IntegerDivisionByZeroException();
diff --git a/sdk/lib/core/expando.dart b/sdk/lib/core/expando.dart
index ac36b9b..d623579 100644
--- a/sdk/lib/core/expando.dart
+++ b/sdk/lib/core/expando.dart
@@ -4,59 +4,47 @@
part of dart.core;
-/**
- * An [Expando] allows adding new properties to objects.
- *
- * Does not work on numbers, strings, booleans or `null`.
- *
- * An `Expando` does not hold on to the added property value after an object
- * becomes inaccessible.
- *
- * Since you can always create a new number that is identical to an existing
- * number, it means that an expando property on a number could never be
- * released. To avoid this, expando properties cannot be added to numbers.
- * The same argument applies to strings, booleans and `null`, which also have
- * literals that evaluate to identical values when they occur more than once.
- *
- * There is no restriction on other classes, even for compile time constant
- * objects. Be careful if adding expando properties to compile time constants,
- * since they will stay alive forever.
- */
+/// An [Expando] allows adding new properties to objects.
+///
+/// Does not work on numbers, strings, booleans or `null`.
+///
+/// An `Expando` does not hold on to the added property value after an object
+/// becomes inaccessible.
+///
+/// Since you can always create a new number that is identical to an existing
+/// number, it means that an expando property on a number could never be
+/// released. To avoid this, expando properties cannot be added to numbers.
+/// The same argument applies to strings, booleans and `null`, which also have
+/// literals that evaluate to identical values when they occur more than once.
+///
+/// There is no restriction on other classes, even for compile time constant
+/// objects. Be careful if adding expando properties to compile time constants,
+/// since they will stay alive forever.
class Expando<T extends Object> {
- /**
- * The name of the this [Expando] as passed to the constructor. If
- * no name was passed to the constructor, the name is `null`.
- */
+ /// The name of the this [Expando] as passed to the constructor. If
+ /// no name was passed to the constructor, the name is `null`.
final String? name;
- /**
- * Creates a new [Expando]. The optional name is only used for
- * debugging purposes and creating two different [Expando]s with the
- * same name yields two [Expando]s that work on different properties
- * of the objects they are used on.
- */
+ /// Creates a new [Expando]. The optional name is only used for
+ /// debugging purposes and creating two different [Expando]s with the
+ /// same name yields two [Expando]s that work on different properties
+ /// of the objects they are used on.
external Expando([String? name]);
- /**
- * Expando toString method override.
- */
- String toString() => "Expando:${name.toString()}";
+ /// Expando toString method override.
+ String toString() => "Expando:$name";
- /**
- * Gets the value of this [Expando]'s property on the given
- * object. If the object hasn't been expanded, the method returns
- * `null`.
- *
- * The object must not be a number, a string, a boolean or null.
- */
+ /// Gets the value of this [Expando]'s property on the given
+ /// object. If the object hasn't been expanded, the method returns
+ /// `null`.
+ ///
+ /// The object must not be a number, a string or a boolean.
external T? operator [](Object object);
- /**
- * Sets the value of this [Expando]'s property on the given
- * object. Properties can effectively be removed again by setting
- * their value to null.
- *
- * The object must not be a number, a string, a boolean or null.
- */
+ /// Sets the value of this [Expando]'s property on the given
+ /// object. Properties can effectively be removed again by setting
+ /// their value to `null`.
+ ///
+ /// The object must not be a number, a string or a boolean.
external void operator []=(Object object, T? value);
}
diff --git a/sdk/lib/core/function.dart b/sdk/lib/core/function.dart
index e560eb4..b0d7ca1 100644
--- a/sdk/lib/core/function.dart
+++ b/sdk/lib/core/function.dart
@@ -4,67 +4,59 @@
part of dart.core;
-/**
- * The base class for all function types.
- *
- * The run-time type of a function object is subtype of a function type,
- * and as such, a subtype of [Function].
- */
+/// The base class for all function types.
+///
+/// The run-time type of a function object is subtype of a function type,
+/// and as such, a subtype of [Function].
abstract class Function {
- /**
- * Dynamically call [function] with the specified arguments.
- *
- * Acts the same as calling function with positional arguments
- * corresponding to the elements of [positionalArguments] and
- * named arguments corresponding to the elements of [namedArguments].
- *
- * This includes giving the same errors if [function] isn't callable or
- * if it expects different parameters.
- *
- * Example:
- * ```
- * Function.apply(foo, [1,2,3], {#f: 4, #g: 5});
- * ```
- *
- * gives exactly the same result as
- * ```
- * foo(1, 2, 3, f: 4, g: 5).
- * ```
- *
- * If [positionalArguments] is null, it's considered an empty list.
- * If [namedArguments] is omitted or null, it is considered an empty map.
- */
+ /// Dynamically call [function] with the specified arguments.
+ ///
+ /// Acts the same as calling function with positional arguments
+ /// corresponding to the elements of [positionalArguments] and
+ /// named arguments corresponding to the elements of [namedArguments].
+ ///
+ /// This includes giving the same errors if [function] isn't callable or
+ /// if it expects different parameters.
+ ///
+ /// Example:
+ /// ```
+ /// Function.apply(foo, [1, 2, 3], {#f: 4, #g: 5});
+ /// ```
+ ///
+ /// gives exactly the same result as
+ /// ```
+ /// foo(1, 2, 3, f: 4, g: 5).
+ /// ```
+ ///
+ /// If [positionalArguments] is null, it's considered an empty list.
+ /// If [namedArguments] is omitted or null, it is considered an empty map.
external static apply(Function function, List<dynamic>? positionalArguments,
[Map<Symbol, dynamic>? namedArguments]);
- /**
- * Returns a hash code value that is compatible with `operator==`.
- */
+ /// A hash code value that is compatible with `operator==`.
int get hashCode;
- /**
- * Test whether another object is equal to this function.
- *
- * Function objects are only equal to other function objects
- * (an object satisfying `object is Function`),
- * and never to non-function objects.
- *
- * Some function objects are considered equal by `==`
- * because they are recognized as representing the "same function":
- *
- * - It is the same object. Static and top-level functions are compile time
- * constants when used as values, so referring to the same function twice
- * always give the same object, as does referring to a local function
- * declaration twice in the same scope where it was declared.
- * - if they refer to the same member method extracted from the same object.
- * Repeatedly extracting an instance method of an object as a function value
- * gives equal, but not necessarily identical, function values.
- *
- * Different evaluations of function literals
- * never give rise to equal function objects.
- * Each time a function literal is evaluated,
- * it creates a new function value that is not equal to any other function
- * value, not even ones created by the same expression.
- */
+ /// Test whether another object is equal to this function.
+ ///
+ /// Function objects are only equal to other function objects
+ /// (an object satisfying `object is Function`),
+ /// and never to non-function objects.
+ ///
+ /// Some function objects are considered equal by `==`
+ /// because they are recognized as representing the "same function":
+ ///
+ /// - It is the same object. Static and top-level functions are compile time
+ /// constants when used as values, so referring to the same function twice
+ /// always give the same object, as does referring to a local function
+ /// declaration twice in the same scope where it was declared.
+ /// - if they refer to the same member method extracted from the same object.
+ /// Repeatedly extracting an instance method of an object as a function value
+ /// gives equal, but not necessarily identical, function values.
+ ///
+ /// Different evaluations of function literals
+ /// never give rise to equal function objects.
+ /// Each time a function literal is evaluated,
+ /// it creates a new function value that is not equal to any other function
+ /// value, not even ones created by the same expression.
bool operator ==(Object other);
}
diff --git a/sdk/lib/core/identical.dart b/sdk/lib/core/identical.dart
index 20d331e..a8bdedf 100644
--- a/sdk/lib/core/identical.dart
+++ b/sdk/lib/core/identical.dart
@@ -4,19 +4,15 @@
part of dart.core;
-/**
- * Check whether two references are to the same object.
- */
+/// Check whether two references are to the same object.
external bool identical(Object? a, Object? b);
-/**
- * Returns the identity hash code of `object`.
- *
- * Returns the same value as `object.hashCode` if [object] has not overridden
- * [Object.hashCode]. Returns the value that [Object.hashCode] would return
- * on this object, even if `hashCode` has been overridden.
- *
- * This hash code is compatible with [identical].
- */
+/// The identity hash code of [object].
+///
+/// Returns the value that the original [Object.hashCode] would return
+/// on this object, even if `hashCode` has been overridden.
+///
+/// This hash code is compatible with [identical],
+/// which just means that it's guaranteed to be stable over time.
@pragma("vm:entry-point")
external int identityHashCode(Object? object);
diff --git a/sdk/lib/core/int.dart b/sdk/lib/core/int.dart
index b1203ed..5d8f5d3 100644
--- a/sdk/lib/core/int.dart
+++ b/sdk/lib/core/int.dart
@@ -4,38 +4,34 @@
part of dart.core;
-/**
- * An integer number.
- *
- * The default implementation of `int` is 64-bit two's complement integers
- * with operations that wrap to that range on overflow.
- *
- * **Note:** When compiling to JavaScript, integers are restricted to values
- * that can be represented exactly by double-precision floating point values.
- * The available integer values include all integers between -2^53 and 2^53,
- * and some integers with larger magnitude. That includes some integers larger
- * than 2^63.
- * The behavior of the operators and methods in the [int]
- * class therefore sometimes differs between the Dart VM and Dart code
- * compiled to JavaScript. For example, the bitwise operators truncate their
- * operands to 32-bit integers when compiled to JavaScript.
- *
- * Classes cannot extend, implement, or mix in `int`.
- */
+/// An integer number.
+///
+/// The default implementation of `int` is 64-bit two's complement integers
+/// with operations that wrap to that range on overflow.
+///
+/// **Note:** When compiling to JavaScript, integers are restricted to values
+/// that can be represented exactly by double-precision floating point values.
+/// The available integer values include all integers between -2^53 and 2^53,
+/// and some integers with larger magnitude. That includes some integers larger
+/// than 2^63.
+/// The behavior of the operators and methods in the [int]
+/// class therefore sometimes differs between the Dart VM and Dart code
+/// compiled to JavaScript. For example, the bitwise operators truncate their
+/// operands to 32-bit integers when compiled to JavaScript.
+///
+/// Classes cannot extend, implement, or mix in `int`.
abstract class int extends num {
- /**
- * Returns the integer value of the given environment declaration [name].
- *
- * The result is the same as would be returned by:
- * ```
- * int.tryParse(const String.fromEnvironment(name, defaultValue: ""))
- * ?? defaultValue
- * ```
- * Example:
- * ```
- * const int.fromEnvironment("defaultPort", defaultValue: 80)
- * ```
- */
+ /// Returns the integer value of the given environment declaration [name].
+ ///
+ /// The result is the same as would be returned by:
+ /// ```
+ /// int.tryParse(const String.fromEnvironment(name, defaultValue: ""))
+ /// ?? defaultValue
+ /// ```
+ /// Example:
+ /// ```
+ /// const int.fromEnvironment("defaultPort", defaultValue: 80)
+ /// ```
// The .fromEnvironment() constructors are special in that we do not want
// users to call them using "new". We prohibit that by giving them bodies
// that throw, even though const constructors are not allowed to have bodies.
@@ -45,312 +41,272 @@
external const factory int.fromEnvironment(String name,
{int defaultValue = 0});
- /**
- * Bit-wise and operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with only the bits set that are set in
- * both `this` and [other]
- *
- * If both operands are negative, the result is negative, otherwise
- * the result is non-negative.
- */
+ /// Bit-wise and operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with only the bits set that are set in
+ /// both `this` and [other]
+ ///
+ /// If both operands are negative, the result is negative, otherwise
+ /// the result is non-negative.
int operator &(int other);
- /**
- * Bit-wise or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in either
- * of `this` and [other]
- *
- * If both operands are non-negative, the result is non-negative,
- * otherwise the result is negative.
- */
+ /// Bit-wise or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in either
+ /// of `this` and [other]
+ ///
+ /// If both operands are non-negative, the result is non-negative,
+ /// otherwise the result is negative.
int operator |(int other);
- /**
- * Bit-wise exclusive-or operator.
- *
- * Treating both `this` and [other] as sufficiently large two's component
- * integers, the result is a number with the bits set that are set in one,
- * but not both, of `this` and [other]
- *
- * If the operands have the same sign, the result is non-negative,
- * otherwise the result is negative.
- */
+ /// Bit-wise exclusive-or operator.
+ ///
+ /// Treating both `this` and [other] as sufficiently large two's component
+ /// integers, the result is a number with the bits set that are set in one,
+ /// but not both, of `this` and [other]
+ ///
+ /// If the operands have the same sign, the result is non-negative,
+ /// otherwise the result is negative.
int operator ^(int other);
- /**
- * The bit-wise negate operator.
- *
- * Treating `this` as a sufficiently large two's component integer,
- * the result is a number with the opposite bits set.
- *
- * This maps any integer `x` to `-x - 1`.
- */
+ /// The bit-wise negate operator.
+ ///
+ /// Treating `this` as a sufficiently large two's component integer,
+ /// the result is a number with the opposite bits set.
+ ///
+ /// This maps any integer `x` to `-x - 1`.
int operator ~();
- /**
- * Shift the bits of this integer to the left by [shiftAmount].
- *
- * Shifting to the left makes the number larger, effectively multiplying
- * the number by `pow(2, shiftIndex)`.
- *
- * There is no limit on the size of the result. It may be relevant to
- * limit intermediate values by using the "and" operator with a suitable
- * mask.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the left by [shiftAmount].
+ ///
+ /// Shifting to the left makes the number larger, effectively multiplying
+ /// the number by `pow(2, shiftIndex)`.
+ ///
+ /// There is no limit on the size of the result. It may be relevant to
+ /// limit intermediate values by using the "and" operator with a suitable
+ /// mask.
+ ///
+ /// It is an error if [shiftAmount] is negative.
int operator <<(int shiftAmount);
- /**
- * Shift the bits of this integer to the right by [shiftAmount].
- *
- * Shifting to the right makes the number smaller and drops the least
- * significant bits, effectively doing an integer division by
- *`pow(2, shiftIndex)`.
- *
- * It is an error if [shiftAmount] is negative.
- */
+ /// Shift the bits of this integer to the right by [shiftAmount].
+ ///
+ /// Shifting to the right makes the number smaller and drops the least
+ /// significant bits, effectively doing an integer division by
+ ///`pow(2, shiftIndex)`.
+ ///
+ /// It is an error if [shiftAmount] is negative.
int operator >>(int shiftAmount);
- /**
- * Returns this integer to the power of [exponent] modulo [modulus].
- *
- * The [exponent] must be non-negative and [modulus] must be
- * positive.
- */
+ /// Returns this integer to the power of [exponent] modulo [modulus].
+ ///
+ /// The [exponent] must be non-negative and [modulus] must be
+ /// positive.
int modPow(int exponent, int modulus);
- /**
- * Returns the modular multiplicative inverse of this integer
- * modulo [modulus].
- *
- * The [modulus] must be positive.
- *
- * It is an error if no modular inverse exists.
- */
+ /// Returns the modular multiplicative inverse of this integer
+ /// modulo [modulus].
+ ///
+ /// The [modulus] must be positive.
+ ///
+ /// It is an error if no modular inverse exists.
int modInverse(int modulus);
- /**
- * Returns the greatest common divisor of this integer and [other].
- *
- * If either number is non-zero, the result is the numerically greatest
- * integer dividing both `this` and `other`.
- *
- * The greatest common divisor is independent of the order,
- * so `x.gcd(y)` is always the same as `y.gcd(x)`.
- *
- * For any integer `x`, `x.gcd(x)` is `x.abs()`.
- *
- * If both `this` and `other` is zero, the result is also zero.
- */
+ /// Returns the greatest common divisor of this integer and [other].
+ ///
+ /// If either number is non-zero, the result is the numerically greatest
+ /// integer dividing both `this` and `other`.
+ ///
+ /// The greatest common divisor is independent of the order,
+ /// so `x.gcd(y)` is always the same as `y.gcd(x)`.
+ ///
+ /// For any integer `x`, `x.gcd(x)` is `x.abs()`.
+ ///
+ /// If both `this` and `other` is zero, the result is also zero.
int gcd(int other);
- /** Returns true if and only if this integer is even. */
+ /// Returns true if and only if this integer is even.
bool get isEven;
- /** Returns true if and only if this integer is odd. */
+ /// Returns true if and only if this integer is odd.
bool get isOdd;
- /**
- * Returns the minimum number of bits required to store this integer.
- *
- * The number of bits excludes the sign bit, which gives the natural length
- * for non-negative (unsigned) values. Negative values are complemented to
- * return the bit position of the first bit that differs from the sign bit.
- *
- * To find the number of bits needed to store the value as a signed value,
- * add one, i.e. use `x.bitLength + 1`.
- * ```
- * x.bitLength == (-x-1).bitLength
- *
- * 3.bitLength == 2; // 00000011
- * 2.bitLength == 2; // 00000010
- * 1.bitLength == 1; // 00000001
- * 0.bitLength == 0; // 00000000
- * (-1).bitLength == 0; // 11111111
- * (-2).bitLength == 1; // 11111110
- * (-3).bitLength == 2; // 11111101
- * (-4).bitLength == 2; // 11111100
- * ```
- */
+ /// Returns the minimum number of bits required to store this integer.
+ ///
+ /// The number of bits excludes the sign bit, which gives the natural length
+ /// for non-negative (unsigned) values. Negative values are complemented to
+ /// return the bit position of the first bit that differs from the sign bit.
+ ///
+ /// To find the number of bits needed to store the value as a signed value,
+ /// add one, i.e. use `x.bitLength + 1`.
+ /// ```
+ /// x.bitLength == (-x-1).bitLength
+ ///
+ /// 3.bitLength == 2; // 00000011
+ /// 2.bitLength == 2; // 00000010
+ /// 1.bitLength == 1; // 00000001
+ /// 0.bitLength == 0; // 00000000
+ /// (-1).bitLength == 0; // 11111111
+ /// (-2).bitLength == 1; // 11111110
+ /// (-3).bitLength == 2; // 11111101
+ /// (-4).bitLength == 2; // 11111100
+ /// ```
int get bitLength;
- /**
- * Returns the least significant [width] bits of this integer as a
- * non-negative number (i.e. unsigned representation). The returned value has
- * zeros in all bit positions higher than [width].
- * ```
- * (-1).toUnsigned(5) == 31 // 11111111 -> 00011111
- * ```
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit quantity:
- * ```
- * q = (q + 1).toUnsigned(8);
- * ```
- * `q` will count from `0` up to `255` and then wrap around to `0`.
- *
- * If the input fits in [width] bits without truncation, the result is the
- * same as the input. The minimum width needed to avoid truncation of `x` is
- * given by `x.bitLength`, i.e.
- * ```
- * x == x.toUnsigned(x.bitLength);
- * ```
- */
+ /// Returns the least significant [width] bits of this integer as a
+ /// non-negative number (i.e. unsigned representation). The returned value has
+ /// zeros in all bit positions higher than [width].
+ /// ```
+ /// (-1).toUnsigned(5) == 31 // 11111111 -> 00011111
+ /// ```
+ /// This operation can be used to simulate arithmetic from low level languages.
+ /// For example, to increment an 8 bit quantity:
+ /// ```
+ /// q = (q + 1).toUnsigned(8);
+ /// ```
+ /// `q` will count from `0` up to `255` and then wrap around to `0`.
+ ///
+ /// If the input fits in [width] bits without truncation, the result is the
+ /// same as the input. The minimum width needed to avoid truncation of `x` is
+ /// given by `x.bitLength`, i.e.
+ /// ```
+ /// x == x.toUnsigned(x.bitLength);
+ /// ```
int toUnsigned(int width);
- /**
- * Returns the least significant [width] bits of this integer, extending the
- * highest retained bit to the sign. This is the same as truncating the value
- * to fit in [width] bits using an signed 2-s complement representation. The
- * returned value has the same bit value in all positions higher than [width].
- *
- * ```
- * V--sign bit-V
- * 16.toSigned(5) == -16 // 00010000 -> 11110000
- * 239.toSigned(5) == 15 // 11101111 -> 00001111
- * ^ ^
- * ```
- * This operation can be used to simulate arithmetic from low level languages.
- * For example, to increment an 8 bit signed quantity:
- * ```
- * q = (q + 1).toSigned(8);
- * ```
- * `q` will count from `0` up to `127`, wrap to `-128` and count back up to
- * `127`.
- *
- * If the input value fits in [width] bits without truncation, the result is
- * the same as the input. The minimum width needed to avoid truncation of `x`
- * is `x.bitLength + 1`, i.e.
- * ```
- * x == x.toSigned(x.bitLength + 1);
- * ```
- */
+ /// Returns the least significant [width] bits of this integer, extending the
+ /// highest retained bit to the sign. This is the same as truncating the value
+ /// to fit in [width] bits using an signed 2-s complement representation. The
+ /// returned value has the same bit value in all positions higher than [width].
+ ///
+ /// ```
+ /// V--sign bit-V
+ /// 16.toSigned(5) == -16 // 00010000 -> 11110000
+ /// 239.toSigned(5) == 15 // 11101111 -> 00001111
+ /// ^ ^
+ /// ```
+ /// This operation can be used to simulate arithmetic from low level languages.
+ /// For example, to increment an 8 bit signed quantity:
+ /// ```
+ /// q = (q + 1).toSigned(8);
+ /// ```
+ /// `q` will count from `0` up to `127`, wrap to `-128` and count back up to
+ /// `127`.
+ ///
+ /// If the input value fits in [width] bits without truncation, the result is
+ /// the same as the input. The minimum width needed to avoid truncation of `x`
+ /// is `x.bitLength + 1`, i.e.
+ /// ```
+ /// x == x.toSigned(x.bitLength + 1);
+ /// ```
int toSigned(int width);
- /**
- * Return the negative value of this integer.
- *
- * The result of negating an integer always has the opposite sign, except
- * for zero, which is its own negation.
- */
+ /// Return the negative value of this integer.
+ ///
+ /// The result of negating an integer always has the opposite sign, except
+ /// for zero, which is its own negation.
int operator -();
- /**
- * Returns the absolute value of this integer.
- *
- * For any integer `x`, the result is the same as `x < 0 ? -x : x`.
- */
+ /// Returns the absolute value of this integer.
+ ///
+ /// For any integer `x`, the result is the same as `x < 0 ? -x : x`.
int abs();
- /**
- * Returns the sign of this integer.
- *
- * Returns 0 for zero, -1 for values less than zero and
- * +1 for values greater than zero.
- */
+ /// Returns the sign of this integer.
+ ///
+ /// Returns 0 for zero, -1 for values less than zero and
+ /// +1 for values greater than zero.
int get sign;
- /** Returns `this`. */
+ /// Returns `this`.
int round();
- /** Returns `this`. */
+ /// Returns `this`.
int floor();
- /** Returns `this`. */
+ /// Returns `this`.
int ceil();
- /** Returns `this`. */
+ /// Returns `this`.
int truncate();
- /** Returns `this.toDouble()`. */
+ /// Returns `this.toDouble()`.
double roundToDouble();
- /** Returns `this.toDouble()`. */
+ /// Returns `this.toDouble()`.
double floorToDouble();
- /** Returns `this.toDouble()`. */
+ /// Returns `this.toDouble()`.
double ceilToDouble();
- /** Returns `this.toDouble()`. */
+ /// Returns `this.toDouble()`.
double truncateToDouble();
- /**
- * Returns a string representation of this integer.
- *
- * The returned string is parsable by [parse].
- * For any `int` `i`, it is guaranteed that
- * `i == int.parse(i.toString())`.
- */
+ /// Returns a string representation of this integer.
+ ///
+ /// The returned string is parsable by [parse].
+ /// For any `int` `i`, it is guaranteed that
+ /// `i == int.parse(i.toString())`.
String toString();
- /**
- * Converts [this] to a string representation in the given [radix].
- *
- * In the string representation, lower-case letters are used for digits above
- * '9', with 'a' being 10 an 'z' being 35.
- *
- * The [radix] argument must be an integer in the range 2 to 36.
- */
+ /// Converts [this] to a string representation in the given [radix].
+ ///
+ /// In the string representation, lower-case letters are used for digits above
+ /// '9', with 'a' being 10 an 'z' being 35.
+ ///
+ /// The [radix] argument must be an integer in the range 2 to 36.
String toRadixString(int radix);
- /**
- * Parse [source] as a, possibly signed, integer literal and return its value.
- *
- * The [source] must be a non-empty sequence of base-[radix] digits,
- * optionally prefixed with a minus or plus sign ('-' or '+').
- * It must not be `null`.
- *
- * The [radix] must be in the range 2..36. The digits used are
- * first the decimal digits 0..9, and then the letters 'a'..'z' with
- * values 10 through 35. Also accepts upper-case letters with the same
- * values as the lower-case ones.
- *
- * If no [radix] is given then it defaults to 10. In this case, the [source]
- * digits may also start with `0x`, in which case the number is interpreted
- * as a hexadecimal integer literal,
- * When `int` is implemented by 64-bit signed integers,
- * hexadecimal integer literals may represent values larger than
- * 2<sup>63</sup>, in which case the value is parsed as if it is an
- * *unsigned* number, and the resulting value is the corresponding
- * signed integer value.
- *
- * For any int `n` and valid radix `r`, it is guaranteed that
- * `n == int.parse(n.toRadixString(r), radix: r)`.
- *
- * If the [source] string does not contain a valid integer literal,
- * optionally prefixed by a sign, a [FormatException] is thrown
- * (unless the deprecated [onError] parameter is used, see below).
- *
- * Instead of throwing and immediately catching the [FormatException],
- * instead use [tryParse] to handle a parsing error.
- * Example:
- * ```dart
- * var value = int.tryParse(text);
- * if (value == null) ... handle the problem
- * ```
- *
- * The [onError] parameter is deprecated and will be removed.
- * Instead of `int.parse(string, onError: (string) => ...)`,
- * you should use `int.tryParse(string) ?? (...)`.
- *
- * When the source string is not valid and [onError] is provided,
- * whenever a [FormatException] would be thrown,
- * [onError] is instead called with [source] as argument,
- * and the result of that call is returned by [parse].
- */
+ /// Parse [source] as a, possibly signed, integer literal and return its value.
+ ///
+ /// The [source] must be a non-empty sequence of base-[radix] digits,
+ /// optionally prefixed with a minus or plus sign ('-' or '+').
+ ///
+ /// The [radix] must be in the range 2..36. The digits used are
+ /// first the decimal digits 0..9, and then the letters 'a'..'z' with
+ /// values 10 through 35. Also accepts upper-case letters with the same
+ /// values as the lower-case ones.
+ ///
+ /// If no [radix] is given then it defaults to 10. In this case, the [source]
+ /// digits may also start with `0x`, in which case the number is interpreted
+ /// as a hexadecimal integer literal,
+ /// When `int` is implemented by 64-bit signed integers,
+ /// hexadecimal integer literals may represent values larger than
+ /// 2<sup>63</sup>, in which case the value is parsed as if it is an
+ /// *unsigned* number, and the resulting value is the corresponding
+ /// signed integer value.
+ ///
+ /// For any int `n` and valid radix `r`, it is guaranteed that
+ /// `n == int.parse(n.toRadixString(r), radix: r)`.
+ ///
+ /// If the [source] string does not contain a valid integer literal,
+ /// optionally prefixed by a sign, a [FormatException] is thrown
+ /// (unless the deprecated [onError] parameter is used, see below).
+ ///
+ /// Instead of throwing and immediately catching the [FormatException],
+ /// instead use [tryParse] to handle a parsing error.
+ /// Example:
+ /// ```dart
+ /// var value = int.tryParse(text);
+ /// if (value == null) ... handle the problem
+ /// ```
+ ///
+ /// The [onError] parameter is deprecated and will be removed.
+ /// Instead of `int.parse(string, onError: (string) => ...)`,
+ /// you should use `int.tryParse(string) ?? (...)`.
+ ///
+ /// When the source string is not valid and [onError] is provided,
+ /// whenever a [FormatException] would be thrown,
+ /// [onError] is instead called with [source] as argument,
+ /// and the result of that call is returned by [parse].
external static int parse(String source,
{int? radix, @deprecated int onError(String source)?});
- /**
- * Parse [source] as a, possibly signed, integer literal and return its value.
- *
- * Like [parse] except that this function returns `null` where a
- * similar call to [parse] would throw a [FormatException],
- * and the [source] must still not be `null`.
- */
+ /// Parse [source] as a, possibly signed, integer literal.
+ ///
+ /// Like [parse] except that this function returns `null` where a
+ /// similar call to [parse] would throw a [FormatException].
external static int? tryParse(String source, {int? radix});
}
diff --git a/sdk/lib/core/invocation.dart b/sdk/lib/core/invocation.dart
index 7d28cea..8ffe56d 100644
--- a/sdk/lib/core/invocation.dart
+++ b/sdk/lib/core/invocation.dart
@@ -4,110 +4,90 @@
part of dart.core;
-/**
- * Representation of the invocation of a member on an object.
- *
- * This is the type of objects passed to [Object.noSuchMethod] when
- * an object doesn't support the member invocation that was attempted
- * on it.
- */
+/// Representation of the invocation of a member on an object.
+///
+/// This is the type of objects passed to [Object.noSuchMethod] when
+/// an object doesn't support the member invocation that was attempted
+/// on it.
abstract class Invocation {
Invocation();
- /**
- * Creates an invocation corresponding to a method invocation.
- *
- * The method invocation has no type arguments.
- * If the named arguments are omitted, they default to no named arguments.
- */
+ /// Creates an invocation corresponding to a method invocation.
+ ///
+ /// The method invocation has no type arguments.
+ /// If the named arguments are omitted, they default to no named arguments.
factory Invocation.method(
Symbol memberName, Iterable<Object?>? positionalArguments,
[Map<Symbol, Object?>? namedArguments]) =>
_Invocation.method(memberName, null, positionalArguments, namedArguments);
- /**
- * Creates an invocation corresponding to a generic method invocation.
- *
- * If [typeArguments] is `null` or empty, the constructor is equivalent to
- * calling [Invocation.method] with the remaining arguments.
- * All the individual type arguments must be non-null.
- *
- * If the named arguments are omitted, they default to no named arguments.
- */
+ /// Creates an invocation corresponding to a generic method invocation.
+ ///
+ /// If [typeArguments] is `null` or empty, the constructor is equivalent to
+ /// calling [Invocation.method] with the remaining arguments.
+ /// All the individual type arguments must be non-null.
+ ///
+ /// If the named arguments are omitted, they default to no named arguments.
factory Invocation.genericMethod(Symbol memberName,
Iterable<Type>? typeArguments, Iterable<Object?>? positionalArguments,
[Map<Symbol, Object?>? namedArguments]) =>
_Invocation.method(
memberName, typeArguments, positionalArguments, namedArguments);
- /**
- * Creates an invocation corresponding to a getter invocation.
- */
+ /// Creates an invocation corresponding to a getter invocation.
factory Invocation.getter(Symbol name) = _Invocation.getter;
- /**
- * Creates an invocation corresponding to a setter invocation.
- *
- * This constructor accepts any [Symbol] as [memberName], but remember that
- * *actual setter names* end in `=`, so the invocation corresponding
- * to `object.member = value` is
- * ```dart
- * Invocation.setter(const Symbol("member="), value)
- * ```
- */
+ /// Creates an invocation corresponding to a setter invocation.
+ ///
+ /// This constructor accepts any [Symbol] as [memberName], but remember that
+ /// *actual setter names* end in `=`, so the invocation corresponding
+ /// to `object.member = value` is
+ /// ```dart
+ /// Invocation.setter(const Symbol("member="), value)
+ /// ```
factory Invocation.setter(Symbol memberName, Object? argument) =
_Invocation.setter;
- /** The name of the invoked member. */
+ /// The name of the invoked member.
Symbol get memberName;
- /**
- * An unmodifiable view of the type arguments of the call.
- *
- * If the member is a getter, setter or operator,
- * the type argument list is always empty.
- */
+ /// An unmodifiable view of the type arguments of the call.
+ ///
+ /// If the member is a getter, setter or operator,
+ /// the type argument list is always empty.
List<Type> get typeArguments => const <Type>[];
- /**
- * An unmodifiable view of the positional arguments of the call.
- *
- * If the member is a getter, the positional arguments list is
- * always empty.
- */
+ /// An unmodifiable view of the positional arguments of the call.
+ ///
+ /// If the member is a getter, the positional arguments list is
+ /// always empty.
List<dynamic> get positionalArguments;
- /**
- * An unmodifiable view of the named arguments of the call.
- *
- * If the member is a getter, setter or operator,
- * the named arguments map is always empty.
- */
+ /// An unmodifiable view of the named arguments of the call.
+ ///
+ /// If the member is a getter, setter or operator,
+ /// the named arguments map is always empty.
Map<Symbol, dynamic> get namedArguments;
- /** Whether the invocation was a method call. */
+ /// Whether the invocation was a method call.
bool get isMethod;
- /**
- * Whether the invocation was a getter call.
- * If so, all three types of arguments lists are empty.
- */
+ /// Whether the invocation was a getter call.
+ /// If so, all three types of arguments lists are empty.
bool get isGetter;
- /**
- * Whether the invocation was a setter call.
- *
- * If so, [positionalArguments] has exactly one positional
- * argument, [namedArguments] is empty, and typeArguments is
- * empty.
- */
+ /// Whether the invocation was a setter call.
+ ///
+ /// If so, [positionalArguments] has exactly one positional
+ /// argument, [namedArguments] is empty, and typeArguments is
+ /// empty.
bool get isSetter;
- /** Whether the invocation was a getter or a setter call. */
+ /// Whether the invocation was a getter or a setter call.
bool get isAccessor => isGetter || isSetter;
}
-/** Implementation of [Invocation] used by its factory constructors. */
+/// Implementation of [Invocation] used by its factory constructors.
class _Invocation implements Invocation {
final Symbol memberName;
final List<Type> typeArguments;
diff --git a/sdk/lib/core/iterable.dart b/sdk/lib/core/iterable.dart
index 7482058..423de13 100644
--- a/sdk/lib/core/iterable.dart
+++ b/sdk/lib/core/iterable.dart
@@ -4,178 +4,164 @@
part of dart.core;
-/**
- * A collection of values, or "elements", that can be accessed sequentially.
- *
- * The elements of the iterable are accessed by getting an [Iterator]
- * using the [iterator] getter, and using it to step through the values.
- * Stepping with the iterator is done by calling [Iterator.moveNext],
- * and if the call returns `true`,
- * the iterator has now moved to the next element,
- * which is then available as [Iterator.current].
- * If the call returns `false`, there are no more elements.
- * The [Iterator.current] value must only be used when the most
- * recent call to [Iterator.moveNext] has returned `true`.
- * If it is used before calling [Iterator.moveNext] the first time
- * on an iterator, or after a call has returned false or has thrown an error,
- * reading [Iterator.current] may throw or may return an arbitrary value.
- *
- * You can create more than one iterator from the same `Iterable`.
- * Each time `iterator` is read, it returns a new iterator,
- * and different iterators can be stepped through independently,
- * each giving access to all the elements of the iterable.
- * The iterators of the same iterable *should* provide the same values
- * in the same order (unless the underlying collection is modified between
- * the iterations, which some collections allow).
- *
- * You can also iterate over the elements of an `Iterable`
- * using the for-in loop construct, which uses the `iterator` getter behind the
- * scenes.
- * For example, you can iterate over all of the keys of a [Map],
- * because `Map` keys are iterable.
- *
- * Map kidsBooks = {'Matilda': 'Roald Dahl',
- * 'Green Eggs and Ham': 'Dr Seuss',
- * 'Where the Wild Things Are': 'Maurice Sendak'};
- * for (var book in kidsBooks.keys) {
- * print('$book was written by ${kidsBooks[book]}');
- * }
- *
- * The [List] and [Set] classes are both `Iterable`,
- * as are most classes in the `dart:collection` library.
- *
- * Some [Iterable] collections can be modified.
- * Adding an element to a `List` or `Set` will change which elements it
- * contains, and adding a new key to a `Map` changes the elements of [Map.keys].
- * Iterators created after the change will provide the new elements, and may
- * or may not preserve the order of existing elements
- * (for example, a [HashSet] may completely change its order when a single
- * element is added).
- *
- * Changing a collection *while* it is being iterated
- * is generally *not* allowed.
- * Doing so will break the iteration, which is typically signalled
- * by throwing a [ConcurrentModificationError]
- * the next time [Iterator.moveNext] is called.
- * The current value of [Iterator.current] getter
- * should not be affected by the change in the collection,
- * the `current` value was set by the previous call to [Iterator.moveNext].
- *
- * Some iterables compute their elements dynamically every time they are
- * iterated, like the one returned by [Iterable.generate] or the iterable
- * returned by a `sync*` generator function. If the computation doesn't depend
- * on other objects that may change, then the generated sequence should be
- * the same one every time it's iterated.
- *
- * The members of `Iterable`, other than `iterator` itself,
- * work by looking at the elements of the iterable.
- * This can be implemented by running through the [iterator], but some classes
- * may have more efficient ways of finding the result
- * (like [last] or [length] on a [List], or [contains] on a [Set]).
- *
- * The methods that return another `Iterable` (like [map] and [where])
- * are all *lazy* - they will iterate the original (as necessary)
- * every time the returned iterable is iterated, and not before.
- *
- * Since an iterable may be iterated more than once, it's not recommended to
- * have detectable side-effects in the iterator.
- * For methods like [map] and [where], the returned iterable will execute the
- * argument function on every iteration, so those functions should also not
- * have side effects.
- */
+/// A collection of values, or "elements", that can be accessed sequentially.
+///
+/// The elements of the iterable are accessed by getting an [Iterator]
+/// using the [iterator] getter, and using it to step through the values.
+/// Stepping with the iterator is done by calling [Iterator.moveNext],
+/// and if the call returns `true`,
+/// the iterator has now moved to the next element,
+/// which is then available as [Iterator.current].
+/// If the call returns `false`, there are no more elements.
+/// The [Iterator.current] value must only be used when the most
+/// recent call to [Iterator.moveNext] has returned `true`.
+/// If it is used before calling [Iterator.moveNext] the first time
+/// on an iterator, or after a call has returned false or has thrown an error,
+/// reading [Iterator.current] may throw or may return an arbitrary value.
+///
+/// You can create more than one iterator from the same `Iterable`.
+/// Each time `iterator` is read, it returns a new iterator,
+/// and different iterators can be stepped through independently,
+/// each giving access to all the elements of the iterable.
+/// The iterators of the same iterable *should* provide the same values
+/// in the same order (unless the underlying collection is modified between
+/// the iterations, which some collections allow).
+///
+/// You can also iterate over the elements of an `Iterable`
+/// using the for-in loop construct, which uses the `iterator` getter behind the
+/// scenes.
+/// For example, you can iterate over all of the keys of a [Map],
+/// because `Map` keys are iterable.
+/// ```dart
+/// var kidsBooks = {'Matilda': 'Roald Dahl',
+/// 'Green Eggs and Ham': 'Dr Seuss',
+/// 'Where the Wild Things Are': 'Maurice Sendak'};
+/// for (var book in kidsBooks.keys) {
+/// print('$book was written by ${kidsBooks[book]}');
+/// }
+/// ```
+/// The [List] and [Set] classes are both `Iterable`,
+/// as are most classes in the `dart:collection` library.
+///
+/// Some [Iterable] collections can be modified.
+/// Adding an element to a `List` or `Set` will change which elements it
+/// contains, and adding a new key to a `Map` changes the elements of [Map.keys].
+/// Iterators created after the change will provide the new elements, and may
+/// or may not preserve the order of existing elements
+/// (for example, a [HashSet] may completely change its order when a single
+/// element is added).
+///
+/// Changing a collection *while* it is being iterated
+/// is generally *not* allowed.
+/// Doing so will break the iteration, which is typically signalled
+/// by throwing a [ConcurrentModificationError]
+/// the next time [Iterator.moveNext] is called.
+/// The current value of [Iterator.current] getter
+/// should not be affected by the change in the collection,
+/// the `current` value was set by the previous call to [Iterator.moveNext].
+///
+/// Some iterables compute their elements dynamically every time they are
+/// iterated, like the one returned by [Iterable.generate] or the iterable
+/// returned by a `sync*` generator function. If the computation doesn't depend
+/// on other objects that may change, then the generated sequence should be
+/// the same one every time it's iterated.
+///
+/// The members of `Iterable`, other than `iterator` itself,
+/// work by looking at the elements of the iterable.
+/// This can be implemented by running through the [iterator], but some classes
+/// may have more efficient ways of finding the result
+/// (like [last] or [length] on a [List], or [contains] on a [Set]).
+///
+/// The methods that return another `Iterable` (like [map] and [where])
+/// are all *lazy* - they will iterate the original (as necessary)
+/// every time the returned iterable is iterated, and not before.
+///
+/// Since an iterable may be iterated more than once, it's not recommended to
+/// have detectable side-effects in the iterator.
+/// For methods like [map] and [where], the returned iterable will execute the
+/// argument function on every iteration, so those functions should also not
+/// have side effects.
abstract class Iterable<E> {
// TODO(lrn): When we allow forwarding const constructors through
// mixin applications, make this class implement [IterableMixin].
const Iterable();
- /**
- * Creates an `Iterable` which generates its elements dynamically.
- *
- * The generated iterable has [count] elements,
- * and the element at index `n` is computed by calling `generator(n)`.
- * Values are not cached, so each iteration computes the values again.
- *
- * If [generator] is omitted, it defaults to an identity function
- * on integers `(int x) => x`, so it may only be omitted if the type
- * parameter allows integer values. That is, if [E] is a super-type
- * of [int].
- *
- * As an `Iterable`, `new Iterable.generate(n, generator))` is equivalent to
- * `const [0, ..., n - 1].map(generator)`.
- */
+ /// Creates an `Iterable` which generates its elements dynamically.
+ ///
+ /// The generated iterable has [count] elements,
+ /// and the element at index `n` is computed by calling `generator(n)`.
+ /// Values are not cached, so each iteration computes the values again.
+ ///
+ /// If [generator] is omitted, it defaults to an identity function
+ /// on integers `(int x) => x`, so it may only be omitted if the type
+ /// parameter allows integer values. That is, if [E] is a super-type
+ /// of [int].
+ ///
+ /// As an `Iterable`, `Iterable.generate(n, generator))` is equivalent to
+ /// `const [0, ..., n - 1].map(generator)`.
factory Iterable.generate(int count, [E generator(int index)?]) {
if (count <= 0) return EmptyIterable<E>();
return _GeneratorIterable<E>(count, generator);
}
- /**
- * Creates an empty iterable.
- *
- * The empty iterable has no elements, and iterating it always stops
- * immediately.
- */
+ /// Creates an empty iterable.
+ ///
+ /// The empty iterable has no elements, and iterating it always stops
+ /// immediately.
const factory Iterable.empty() = EmptyIterable<E>;
- /**
- * Adapts [source] to be an `Iterable<T>`.
- *
- * Any time the iterable would produce an element that is not a [T],
- * the element access will throw. If all elements of [source] are actually
- * instances of [T], or if only elements that are actually instances of [T]
- * are accessed, then the resulting iterable can be used as an `Iterable<T>`.
- */
+ /// Adapts [source] to be an `Iterable<T>`.
+ ///
+ /// Any time the iterable would produce an element that is not a [T],
+ /// the element access will throw. If all elements of [source] are actually
+ /// instances of [T], or if only elements that are actually instances of [T]
+ /// are accessed, then the resulting iterable can be used as an `Iterable<T>`.
static Iterable<T> castFrom<S, T>(Iterable<S> source) =>
CastIterable<S, T>(source);
- /**
- * Returns a new `Iterator` that allows iterating the elements of this
- * `Iterable`.
- *
- * Iterable classes may specify the iteration order of their elements
- * (for example [List] always iterate in index order),
- * or they may leave it unspecified (for example a hash-based [Set]
- * may iterate in any order).
- *
- * Each time `iterator` is read, it returns a new iterator,
- * which can be used to iterate through all the elements again.
- * The iterators of the same iterable can be stepped through independently,
- * but should return the same elements in the same order,
- * as long as the underlying collection isn't changed.
- *
- * Modifying the collection may cause new iterators to produce
- * different elements, and may change the order of existing elements.
- * A [List] specifies its iteration order precisely,
- * so modifying the list changes the iteration order predictably.
- * A hash-based [Set] may change its iteration order completely
- * when adding a new element to the set.
- *
- * Modifying the underlying collection after creating the new iterator
- * may cause an error the next time [Iterator.moveNext] is called
- * on that iterator.
- * Any *modifiable* iterable class should specify which operations will
- * break iteration.
- */
+ /// Returns a new `Iterator` that allows iterating the elements of this
+ /// `Iterable`.
+ ///
+ /// Iterable classes may specify the iteration order of their elements
+ /// (for example [List] always iterate in index order),
+ /// or they may leave it unspecified (for example a hash-based [Set]
+ /// may iterate in any order).
+ ///
+ /// Each time `iterator` is read, it returns a new iterator,
+ /// which can be used to iterate through all the elements again.
+ /// The iterators of the same iterable can be stepped through independently,
+ /// but should return the same elements in the same order,
+ /// as long as the underlying collection isn't changed.
+ ///
+ /// Modifying the collection may cause new iterators to produce
+ /// different elements, and may change the order of existing elements.
+ /// A [List] specifies its iteration order precisely,
+ /// so modifying the list changes the iteration order predictably.
+ /// A hash-based [Set] may change its iteration order completely
+ /// when adding a new element to the set.
+ ///
+ /// Modifying the underlying collection after creating the new iterator
+ /// may cause an error the next time [Iterator.moveNext] is called
+ /// on that iterator.
+ /// Any *modifiable* iterable class should specify which operations will
+ /// break iteration.
Iterator<E> get iterator;
- /**
- * Provides a view of this iterable as an iterable of [R] instances.
- *
- * If this iterable only contains instances of [R], all operations
- * will work correctly. If any operation tries to access an element
- * that is not an instance of [R], the access will throw instead.
- *
- * When the returned iterable creates a new object that depends on
- * the type [R], e.g., from [toList], it will have exactly the type [R].
- */
+ /// Provides a view of this iterable as an iterable of [R] instances.
+ ///
+ /// If this iterable only contains instances of [R], all operations
+ /// will work correctly. If any operation tries to access an element
+ /// that is not an instance of [R], the access will throw instead.
+ ///
+ /// When the returned iterable creates a new object that depends on
+ /// the type [R], e.g., from [toList], it will have exactly the type [R].
Iterable<R> cast<R>() => Iterable.castFrom<E, R>(this);
- /**
- * Returns the lazy concatenation of this iterable and [other].
- *
- * The returned iterable will provide the same elements as this iterable,
- * and, after that, the elements of [other], in the same order as in the
- * original iterables.
- */
+ /// Returns the lazy concatenation of this iterable and [other].
+ ///
+ /// The returned iterable will provide the same elements as this iterable,
+ /// and, after that, the elements of [other], in the same order as in the
+ /// original iterables.
Iterable<E> followedBy(Iterable<E> other) {
var self = this; // TODO(lrn): Remove when we can promote `this`.
if (self is EfficientLengthIterable<E>) {
@@ -184,90 +170,80 @@
return FollowedByIterable<E>(this, other);
}
- /**
- * Returns a new lazy [Iterable] with elements that are created by
- * calling `f` on each element of this `Iterable` in iteration order.
- *
- * This method returns a view of the mapped elements. As long as the
- * returned [Iterable] is not iterated over, the supplied function [f] will
- * not be invoked. The transformed elements will not be cached. Iterating
- * multiple times over the returned [Iterable] will invoke the supplied
- * function [f] multiple times on the same element.
- *
- * Methods on the returned iterable are allowed to omit calling `f`
- * on any element where the result isn't needed.
- * For example, [elementAt] may call `f` only once.
- */
+ /// Returns a new lazy [Iterable] with elements that are created by
+ /// calling `f` on each element of this `Iterable` in iteration order.
+ ///
+ /// This method returns a view of the mapped elements. As long as the
+ /// returned [Iterable] is not iterated over, the supplied function [f] will
+ /// not be invoked. The transformed elements will not be cached. Iterating
+ /// multiple times over the returned [Iterable] will invoke the supplied
+ /// function [f] multiple times on the same element.
+ ///
+ /// Methods on the returned iterable are allowed to omit calling `f`
+ /// on any element where the result isn't needed.
+ /// For example, [elementAt] may call `f` only once.
Iterable<T> map<T>(T f(E e)) => MappedIterable<E, T>(this, f);
- /**
- * Returns a new lazy [Iterable] with all elements that satisfy the
- * predicate [test].
- *
- * The matching elements have the same order in the returned iterable
- * as they have in [iterator].
- *
- * This method returns a view of the mapped elements.
- * As long as the returned [Iterable] is not iterated over,
- * the supplied function [test] will not be invoked.
- * Iterating will not cache results, and thus iterating multiple times over
- * the returned [Iterable] may invoke the supplied
- * function [test] multiple times on the same element.
- */
+ /// Returns a new lazy [Iterable] with all elements that satisfy the
+ /// predicate [test].
+ ///
+ /// The matching elements have the same order in the returned iterable
+ /// as they have in [iterator].
+ ///
+ /// This method returns a view of the mapped elements.
+ /// As long as the returned [Iterable] is not iterated over,
+ /// the supplied function [test] will not be invoked.
+ /// Iterating will not cache results, and thus iterating multiple times over
+ /// the returned [Iterable] may invoke the supplied
+ /// function [test] multiple times on the same element.
Iterable<E> where(bool test(E element)) => WhereIterable<E>(this, test);
- /**
- * Returns a new lazy [Iterable] with all elements that have type [T].
- *
- * The matching elements have the same order in the returned iterable
- * as they have in [iterator].
- *
- * This method returns a view of the mapped elements.
- * Iterating will not cache results, and thus iterating multiple times over
- * the returned [Iterable] may yield different results,
- * if the underlying elements change between iterations.
- */
+ /// Returns a new lazy [Iterable] with all elements that have type [T].
+ ///
+ /// The matching elements have the same order in the returned iterable
+ /// as they have in [iterator].
+ ///
+ /// This method returns a view of the mapped elements.
+ /// Iterating will not cache results, and thus iterating multiple times over
+ /// the returned [Iterable] may yield different results,
+ /// if the underlying elements change between iterations.
Iterable<T> whereType<T>() => WhereTypeIterable<T>(this);
- /**
- * Expands each element of this [Iterable] into zero or more elements.
- *
- * The resulting Iterable runs through the elements returned
- * by [f] for each element of this, in iteration order.
- *
- * The returned [Iterable] is lazy, and calls [f] for each element
- * of this every time it's iterated.
- *
- * Example:
- *
- * var pairs = [[1, 2], [3, 4]];
- * var flattened = pairs.expand((pair) => pair).toList();
- * print(flattened); // => [1, 2, 3, 4];
- *
- * var input = [1, 2, 3];
- * var duplicated = input.expand((i) => [i, i]).toList();
- * print(duplicated); // => [1, 1, 2, 2, 3, 3]
- *
- */
+ /// Expands each element of this [Iterable] into zero or more elements.
+ ///
+ /// The resulting Iterable runs through the elements returned
+ /// by [f] for each element of this, in iteration order.
+ ///
+ /// The returned [Iterable] is lazy, and calls [f] for each element
+ /// of this every time it's iterated.
+ ///
+ /// Example:
+ /// ```dart
+ /// var pairs = [[1, 2], [3, 4]];
+ /// var flattened = pairs.expand((pair) => pair).toList();
+ /// print(flattened); // => [1, 2, 3, 4];
+ ///
+ /// var input = [1, 2, 3];
+ /// var duplicated = input.expand((i) => [i, i]).toList();
+ /// print(duplicated); // => [1, 1, 2, 2, 3, 3]
+ /// ```
Iterable<T> expand<T>(Iterable<T> f(E element)) =>
ExpandIterable<E, T>(this, f);
- /**
- * Returns true if the collection contains an element equal to [element].
- *
- * This operation will check each element in order for being equal to
- * [element], unless it has a more efficient way to find an element
- * equal to [element].
- *
- * The equality used to determine whether [element] is equal to an element of
- * the iterable defaults to the [Object.==] of the element.
- *
- * Some types of iterable may have a different equality used for its elements.
- * For example, a [Set] may have a custom equality
- * (see [Set.identity]) that its `contains` uses.
- * Likewise the `Iterable` returned by a [Map.keys] call
- * should use the same equality that the `Map` uses for keys.
- */
+ /// Whether the collection contains an element equal to [element].
+ ///
+ /// This operation will check each element in order for being equal to
+ /// [element], unless it has a more efficient way to find an element
+ /// equal to [element].
+ ///
+ /// The equality used to determine whether [element] is equal to an element of
+ /// the iterable defaults to the [Object.==] of the element.
+ ///
+ /// Some types of iterable may have a different equality used for its elements.
+ /// For example, a [Set] may have a custom equality
+ /// (see [Set.identity]) that its `contains` uses.
+ /// Likewise the `Iterable` returned by a [Map.keys] call
+ /// should use the same equality that the `Map` uses for keys.
bool contains(Object? element) {
for (E e in this) {
if (e == element) return true;
@@ -275,36 +251,32 @@
return false;
}
- /**
- * Applies the function [f] to each element of this collection in iteration
- * order.
- */
+ /// Applies the function [f] to each element of this collection in iteration
+ /// order.
void forEach(void f(E element)) {
for (E element in this) f(element);
}
- /**
- * Reduces a collection to a single value by iteratively combining elements
- * of the collection using the provided function.
- *
- * The iterable must have at least one element.
- * If it has only one element, that element is returned.
- *
- * Otherwise this method starts with the first element from the iterator,
- * and then combines it with the remaining elements in iteration order,
- * as if by:
- *
- * E value = iterable.first;
- * iterable.skip(1).forEach((element) {
- * value = combine(value, element);
- * });
- * return value;
- *
- * Example of calculating the sum of an iterable:
- *
- * iterable.reduce((value, element) => value + element);
- *
- */
+ /// Reduces a collection to a single value by iteratively combining elements
+ /// of the collection using the provided function.
+ ///
+ /// The iterable must have at least one element.
+ /// If it has only one element, that element is returned.
+ ///
+ /// Otherwise this method starts with the first element from the iterator,
+ /// and then combines it with the remaining elements in iteration order,
+ /// as if by:
+ /// ```dart
+ /// E value = iterable.first;
+ /// iterable.skip(1).forEach((element) {
+ /// value = combine(value, element);
+ /// });
+ /// return value;
+ /// ```
+ /// Example of calculating the sum of an iterable:
+ /// ```dart
+ /// iterable.reduce((value, element) => value + element);
+ /// ```
E reduce(E combine(E value, E element)) {
Iterator<E> iterator = this.iterator;
if (!iterator.moveNext()) {
@@ -317,37 +289,33 @@
return value;
}
- /**
- * Reduces a collection to a single value by iteratively combining each
- * element of the collection with an existing value
- *
- * Uses [initialValue] as the initial value,
- * then iterates through the elements and updates the value with
- * each element using the [combine] function, as if by:
- *
- * var value = initialValue;
- * for (E element in this) {
- * value = combine(value, element);
- * }
- * return value;
- *
- * Example of calculating the sum of an iterable:
- *
- * iterable.fold(0, (prev, element) => prev + element);
- *
- */
+ /// Reduces a collection to a single value by iteratively combining each
+ /// element of the collection with an existing value
+ ///
+ /// Uses [initialValue] as the initial value,
+ /// then iterates through the elements and updates the value with
+ /// each element using the [combine] function, as if by:
+ /// ```dart
+ /// var value = initialValue;
+ /// for (E element in this) {
+ /// value = combine(value, element);
+ /// }
+ /// return value;
+ /// ```
+ /// Example of calculating the sum of an iterable:
+ /// ```dart
+ /// iterable.fold(0, (prev, element) => prev + element);
+ /// ```
T fold<T>(T initialValue, T combine(T previousValue, E element)) {
var value = initialValue;
for (E element in this) value = combine(value, element);
return value;
}
- /**
- * Checks whether every element of this iterable satisfies [test].
- *
- * Checks every element in iteration order, and returns `false` if
- * any of them make [test] return `false`, otherwise returns `true`.
- */
+ /// Checks whether every element of this iterable satisfies [test].
+ ///
+ /// Checks every element in iteration order, and returns `false` if
+ /// any of them make [test] return `false`, otherwise returns `true`.
bool every(bool test(E element)) {
for (E element in this) {
if (!test(element)) return false;
@@ -355,14 +323,12 @@
return true;
}
- /**
- * Converts each element to a [String] and concatenates the strings.
- *
- * Iterates through elements of this iterable,
- * converts each one to a [String] by calling [Object.toString],
- * and then concatenates the strings, with the
- * [separator] string interleaved between the elements.
- */
+ /// Converts each element to a [String] and concatenates the strings.
+ ///
+ /// Iterates through elements of this iterable,
+ /// converts each one to a [String] by calling [Object.toString],
+ /// and then concatenates the strings, with the
+ /// [separator] string interleaved between the elements.
String join([String separator = ""]) {
Iterator<E> iterator = this.iterator;
if (!iterator.moveNext()) return "";
@@ -381,12 +347,10 @@
return buffer.toString();
}
- /**
- * Checks whether any element of this iterable satisfies [test].
- *
- * Checks every element in iteration order, and returns `true` if
- * any of them make [test] return `true`, otherwise returns false.
- */
+ /// Checks whether any element of this iterable satisfies [test].
+ ///
+ /// Checks every element in iteration order, and returns `true` if
+ /// any of them make [test] return `true`, otherwise returns false.
bool any(bool test(E element)) {
for (E element in this) {
if (test(element)) return true;
@@ -394,34 +358,28 @@
return false;
}
- /**
- * Creates a [List] containing the elements of this [Iterable].
- *
- * The elements are in iteration order.
- * The list is fixed-length if [growable] is false.
- */
+ /// Creates a [List] containing the elements of this [Iterable].
+ ///
+ /// The elements are in iteration order.
+ /// The list is fixed-length if [growable] is false.
List<E> toList({bool growable = true}) {
return List<E>.of(this, growable: growable);
}
- /**
- * Creates a [Set] containing the same elements as this iterable.
- *
- * The set may contain fewer elements than the iterable,
- * if the iterable contains an element more than once,
- * or it contains one or more elements that are equal.
- * The order of the elements in the set is not guaranteed to be the same
- * as for the iterable.
- */
+ /// Creates a [Set] containing the same elements as this iterable.
+ ///
+ /// The set may contain fewer elements than the iterable,
+ /// if the iterable contains an element more than once,
+ /// or it contains one or more elements that are equal.
+ /// The order of the elements in the set is not guaranteed to be the same
+ /// as for the iterable.
Set<E> toSet() => Set<E>.of(this);
- /**
- * Returns the number of elements in [this].
- *
- * Counting all elements may involve iterating through all elements and can
- * therefore be slow.
- * Some iterables have a more efficient way to find the number of elements.
- */
+ /// Returns the number of elements in [this].
+ ///
+ /// Counting all elements may involve iterating through all elements and can
+ /// therefore be slow.
+ /// Some iterables have a more efficient way to find the number of elements.
int get length {
assert(this is! EfficientLengthIterable);
int count = 0;
@@ -432,92 +390,78 @@
return count;
}
- /**
- * Returns `true` if there are no elements in this collection.
- *
- * May be computed by checking if `iterator.moveNext()` returns `false`.
- */
+ /// Returns `true` if there are no elements in this collection.
+ ///
+ /// May be computed by checking if `iterator.moveNext()` returns `false`.
bool get isEmpty => !iterator.moveNext();
- /**
- * Returns true if there is at least one element in this collection.
- *
- * May be computed by checking if `iterator.moveNext()` returns `true`.
- */
+ /// Returns true if there is at least one element in this collection.
+ ///
+ /// May be computed by checking if `iterator.moveNext()` returns `true`.
bool get isNotEmpty => !isEmpty;
- /**
- * Returns a lazy iterable of the [count] first elements of this iterable.
- *
- * The returned `Iterable` may contain fewer than `count` elements, if `this`
- * contains fewer than `count` elements.
- *
- * The elements can be computed by stepping through [iterator] until [count]
- * elements have been seen.
- *
- * The `count` must not be negative.
- */
+ /// Returns a lazy iterable of the [count] first elements of this iterable.
+ ///
+ /// The returned `Iterable` may contain fewer than `count` elements, if `this`
+ /// contains fewer than `count` elements.
+ ///
+ /// The elements can be computed by stepping through [iterator] until [count]
+ /// elements have been seen.
+ ///
+ /// The `count` must not be negative.
Iterable<E> take(int count) {
return TakeIterable<E>(this, count);
}
- /**
- * Returns a lazy iterable of the leading elements satisfying [test].
- *
- * The filtering happens lazily. Every new iterator of the returned
- * iterable starts iterating over the elements of `this`.
- *
- * The elements can be computed by stepping through [iterator] until an
- * element is found where `test(element)` is false. At that point,
- * the returned iterable stops (its `moveNext()` returns false).
- */
+ /// Returns a lazy iterable of the leading elements satisfying [test].
+ ///
+ /// The filtering happens lazily. Every new iterator of the returned
+ /// iterable starts iterating over the elements of `this`.
+ ///
+ /// The elements can be computed by stepping through [iterator] until an
+ /// element is found where `test(element)` is false. At that point,
+ /// the returned iterable stops (its `moveNext()` returns false).
Iterable<E> takeWhile(bool test(E value)) {
return TakeWhileIterable<E>(this, test);
}
- /**
- * Returns an [Iterable] that provides all but the first [count] elements.
- *
- * When the returned iterable is iterated, it starts iterating over `this`,
- * first skipping past the initial [count] elements.
- * If `this` has fewer than `count` elements, then the resulting Iterable is
- * empty.
- * After that, the remaining elements are iterated in the same order as
- * in this iterable.
- *
- * Some iterables may be able to find later elements without first iterating
- * through earlier elements, for example when iterating a [List].
- * Such iterables are allowed to ignore the initial skipped elements.
- *
- * The [count] must not be negative.
- */
+ /// Returns an [Iterable] that provides all but the first [count] elements.
+ ///
+ /// When the returned iterable is iterated, it starts iterating over `this`,
+ /// first skipping past the initial [count] elements.
+ /// If `this` has fewer than `count` elements, then the resulting Iterable is
+ /// empty.
+ /// After that, the remaining elements are iterated in the same order as
+ /// in this iterable.
+ ///
+ /// Some iterables may be able to find later elements without first iterating
+ /// through earlier elements, for example when iterating a [List].
+ /// Such iterables are allowed to ignore the initial skipped elements.
+ ///
+ /// The [count] must not be negative.
Iterable<E> skip(int count) {
return SkipIterable<E>(this, count);
}
- /**
- * Returns an `Iterable` that skips leading elements while [test] is satisfied.
- *
- * The filtering happens lazily. Every new [Iterator] of the returned
- * iterable iterates over all elements of `this`.
- *
- * The returned iterable provides elements by iterating this iterable,
- * but skipping over all initial elements where `test(element)` returns
- * true. If all elements satisfy `test` the resulting iterable is empty,
- * otherwise it iterates the remaining elements in their original order,
- * starting with the first element for which `test(element)` returns `false`.
- */
+ /// Returns an `Iterable` that skips leading elements while [test] is satisfied.
+ ///
+ /// The filtering happens lazily. Every new [Iterator] of the returned
+ /// iterable iterates over all elements of `this`.
+ ///
+ /// The returned iterable provides elements by iterating this iterable,
+ /// but skipping over all initial elements where `test(element)` returns
+ /// true. If all elements satisfy `test` the resulting iterable is empty,
+ /// otherwise it iterates the remaining elements in their original order,
+ /// starting with the first element for which `test(element)` returns `false`.
Iterable<E> skipWhile(bool test(E value)) {
return SkipWhileIterable<E>(this, test);
}
- /**
- * Returns the first element.
- *
- * Throws a [StateError] if `this` is empty.
- * Otherwise returns the first element in the iteration order,
- * equivalent to `this.elementAt(0)`.
- */
+ /// Returns the first element.
+ ///
+ /// Throws a [StateError] if `this` is empty.
+ /// Otherwise returns the first element in the iteration order,
+ /// equivalent to `this.elementAt(0)`.
E get first {
Iterator<E> it = iterator;
if (!it.moveNext()) {
@@ -526,16 +470,14 @@
return it.current;
}
- /**
- * Returns the last element.
- *
- * Throws a [StateError] if `this` is empty.
- * Otherwise may iterate through the elements and returns the last one
- * seen.
- * Some iterables may have more efficient ways to find the last element
- * (for example a list can directly access the last element,
- * without iterating through the previous ones).
- */
+ /// Returns the last element.
+ ///
+ /// Throws a [StateError] if `this` is empty.
+ /// Otherwise may iterate through the elements and returns the last one
+ /// seen.
+ /// Some iterables may have more efficient ways to find the last element
+ /// (for example a list can directly access the last element,
+ /// without iterating through the previous ones).
E get last {
Iterator<E> it = iterator;
if (!it.moveNext()) {
@@ -548,11 +490,9 @@
return result;
}
- /**
- * Checks that this iterable has only one element, and returns that element.
- *
- * Throws a [StateError] if `this` is empty or has more than one element.
- */
+ /// Checks that this iterable has only one element, and returns that element.
+ ///
+ /// Throws a [StateError] if `this` is empty or has more than one element.
E get single {
Iterator<E> it = iterator;
if (!it.moveNext()) throw IterableElementError.noElement();
@@ -561,15 +501,13 @@
return result;
}
- /**
- * Returns the first element that satisfies the given predicate [test].
- *
- * Iterates through elements and returns the first to satisfy [test].
- *
- * If no element satisfies [test], the result of invoking the [orElse]
- * function is returned.
- * If [orElse] is omitted, it defaults to throwing a [StateError].
- */
+ /// Returns the first element that satisfies the given predicate [test].
+ ///
+ /// Iterates through elements and returns the first to satisfy [test].
+ ///
+ /// If no element satisfies [test], the result of invoking the [orElse]
+ /// function is returned.
+ /// If [orElse] is omitted, it defaults to throwing a [StateError].
E firstWhere(bool test(E element), {E orElse()?}) {
for (E element in this) {
if (test(element)) return element;
@@ -578,20 +516,18 @@
throw IterableElementError.noElement();
}
- /**
- * Returns the last element that satisfies the given predicate [test].
- *
- * An iterable that can access its elements directly may check its
- * elements in any order (for example a list starts by checking the
- * last element and then moves towards the start of the list).
- * The default implementation iterates elements in iteration order,
- * checks `test(element)` for each,
- * and finally returns that last one that matched.
- *
- * If no element satisfies [test], the result of invoking the [orElse]
- * function is returned.
- * If [orElse] is omitted, it defaults to throwing a [StateError].
- */
+ /// Returns the last element that satisfies the given predicate [test].
+ ///
+ /// An iterable that can access its elements directly may check its
+ /// elements in any order (for example a list starts by checking the
+ /// last element and then moves towards the start of the list).
+ /// The default implementation iterates elements in iteration order,
+ /// checks `test(element)` for each,
+ /// and finally returns that last one that matched.
+ ///
+ /// If no element satisfies [test], the result of invoking the [orElse]
+ /// function is returned.
+ /// If [orElse] is omitted, it defaults to throwing a [StateError].
E lastWhere(bool test(E element), {E orElse()?}) {
late E result;
bool foundMatching = false;
@@ -606,15 +542,13 @@
throw IterableElementError.noElement();
}
- /**
- * Returns the single element that satisfies [test].
- *
- * Checks elements to see if `test(element)` returns true.
- * If exactly one element satisfies [test], that element is returned.
- * If more than one matching element is found, throws [StateError].
- * If no matching element is found, returns the result of [orElse].
- * If [orElse] is omitted, it defaults to throwing a [StateError].
- */
+ /// Returns the single element that satisfies [test].
+ ///
+ /// Checks elements to see if `test(element)` returns true.
+ /// If exactly one element satisfies [test], that element is returned.
+ /// If more than one matching element is found, throws [StateError].
+ /// If no matching element is found, returns the result of [orElse].
+ /// If [orElse] is omitted, it defaults to throwing a [StateError].
E singleWhere(bool test(E element), {E orElse()?}) {
late E result;
bool foundMatching = false;
@@ -632,17 +566,15 @@
throw IterableElementError.noElement();
}
- /**
- * Returns the [index]th element.
- *
- * The [index] must be non-negative and less than [length].
- * Index zero represents the first element (so `iterable.elementAt(0)` is
- * equivalent to `iterable.first`).
- *
- * May iterate through the elements in iteration order, ignoring the
- * first [index] elements and then returning the next.
- * Some iterables may have a more efficient way to find the element.
- */
+ /// Returns the [index]th element.
+ ///
+ /// The [index] must be non-negative and less than [length].
+ /// Index zero represents the first element (so `iterable.elementAt(0)` is
+ /// equivalent to `iterable.first`).
+ ///
+ /// May iterate through the elements in iteration order, ignoring the
+ /// first [index] elements and then returning the next.
+ /// Some iterables may have a more efficient way to find the element.
E elementAt(int index) {
RangeError.checkNotNegative(index, "index");
int elementIndex = 0;
@@ -653,22 +585,20 @@
throw RangeError.index(index, this, "index", null, elementIndex);
}
- /**
- * Returns a string representation of (some of) the elements of `this`.
- *
- * Elements are represented by their own `toString` results.
- *
- * The default representation always contains the first three elements.
- * If there are less than a hundred elements in the iterable, it also
- * contains the last two elements.
- *
- * If the resulting string isn't above 80 characters, more elements are
- * included from the start of the iterable.
- *
- * The conversion may omit calling `toString` on some elements if they
- * are known to not occur in the output, and it may stop iterating after
- * a hundred elements.
- */
+ /// Returns a string representation of (some of) the elements of `this`.
+ ///
+ /// Elements are represented by their own `toString` results.
+ ///
+ /// The default representation always contains the first three elements.
+ /// If there are less than a hundred elements in the iterable, it also
+ /// contains the last two elements.
+ ///
+ /// If the resulting string isn't above 80 characters, more elements are
+ /// included from the start of the iterable.
+ ///
+ /// The conversion may omit calling `toString` on some elements if they
+ /// are known to not occur in the output, and it may stop iterating after
+ /// a hundred elements.
String toString() => IterableBase.iterableToShortString(this, '(', ')');
}
@@ -696,16 +626,12 @@
static int _id(int n) => n;
}
-/**
- * An [Iterator] that allows moving backwards as well as forwards.
- */
+/// An [Iterator] that allows moving backwards as well as forwards.
abstract class BidirectionalIterator<E> implements Iterator<E> {
- /**
- * Move back to the previous element.
- *
- * Returns true and updates [current] if successful. Returns false
- * and updates [current] to an implementation defined state if there is no
- * previous element
- */
+ /// Move back to the previous element.
+ ///
+ /// Returns true and updates [current] if successful. Returns false
+ /// and updates [current] to an implementation defined state if there is no
+ /// previous element
bool movePrevious();
}
diff --git a/sdk/lib/core/iterator.dart b/sdk/lib/core/iterator.dart
index 13c76b4..7ea322e 100644
--- a/sdk/lib/core/iterator.dart
+++ b/sdk/lib/core/iterator.dart
@@ -4,72 +4,66 @@
part of dart.core;
-/**
- * An interface for getting items, one at a time, from an object.
- *
- * The for-in construct transparently uses `Iterator` to test for the end
- * of the iteration, and to get each item (or _element_).
- *
- * If the object iterated over is changed during the iteration, the
- * behavior is unspecified.
- *
- * The `Iterator` is initially positioned before the first element.
- * Before accessing the first element the iterator must thus be advanced using
- * [moveNext] to point to the first element.
- * If no element is left, then [moveNext] returns false,
- * and all further calls to [moveNext] will also return false.
- *
- * The [current] value must not be accessed before calling [moveNext]
- * or after a call to [moveNext] has returned false.
- *
- * A typical usage of an Iterator looks as follows:
- *
- * var it = obj.iterator;
- * while (it.moveNext()) {
- * use(it.current);
- * }
- *
- * **See also:**
- * [Iteration](https://dart.dev/guides/libraries/library-tour#iteration)
- * in the [library tour](https://dart.dev/guides/libraries/library-tour)
- */
+/// An interface for getting items, one at a time, from an object.
+///
+/// The for-in construct transparently uses `Iterator` to test for the end
+/// of the iteration, and to get each item (or _element_).
+///
+/// If the object iterated over is changed during the iteration, the
+/// behavior is unspecified.
+///
+/// The `Iterator` is initially positioned before the first element.
+/// Before accessing the first element the iterator must thus be advanced using
+/// [moveNext] to point to the first element.
+/// If no element is left, then [moveNext] returns false,
+/// and all further calls to [moveNext] will also return false.
+///
+/// The [current] value must not be accessed before calling [moveNext]
+/// or after a call to [moveNext] has returned false.
+///
+/// A typical usage of an `Iterator` looks as follows:
+/// ```dart
+/// var it = obj.iterator;
+/// while (it.moveNext()) {
+/// use(it.current);
+/// }
+/// ```
+/// **See also:**
+/// [Iteration](https://dart.dev/guides/libraries/library-tour#iteration)
+/// in the [library tour](https://dart.dev/guides/libraries/library-tour)
abstract class Iterator<E> {
- /**
- * Advances the iterator to the next element of the iteration.
- *
- * Should be called before reading [current].
- * If the call to `moveNext` returns `true`,
- * then [current] will contain the next element of the iteration
- * until `moveNext` is called again.
- * If the call returns `false`, there are no further elements
- * and [current] should not be used any more.
- *
- * It is safe to call [moveNext] after it has already returned `false`,
- * but it must keep returning `false` and not have any other effect.
- *
- * A call to `moveNext` may throw for various reasons,
- * including a concurrent change to an underlying collection.
- * If that happens, the iterator may be in an inconsistent
- * state, and any further behavior of the iterator is unspecified,
- * including the effect of reading [current].
- */
+ /// Advances the iterator to the next element of the iteration.
+ ///
+ /// Should be called before reading [current].
+ /// If the call to `moveNext` returns `true`,
+ /// then [current] will contain the next element of the iteration
+ /// until `moveNext` is called again.
+ /// If the call returns `false`, there are no further elements
+ /// and [current] should not be used any more.
+ ///
+ /// It is safe to call [moveNext] after it has already returned `false`,
+ /// but it must keep returning `false` and not have any other effect.
+ ///
+ /// A call to `moveNext` may throw for various reasons,
+ /// including a concurrent change to an underlying collection.
+ /// If that happens, the iterator may be in an inconsistent
+ /// state, and any further behavior of the iterator is unspecified,
+ /// including the effect of reading [current].
bool moveNext();
- /**
- * Returns the current element.
- *
- * If the iterator has not yet been moved to the first element
- * ([moveNext] has not been called yet),
- * or if the iterator has been moved past the last element of the [Iterable]
- * ([moveNext] has returned false),
- * then [current] is unspecified.
- * An [Iterator] may either throw or return an iterator specific default value
- * in that case.
- *
- * The `current` getter should keep its value until the next call to
- * [moveNext], even if an underlying collection changes.
- * After a successful call to `moveNext`, the user doesn't need to cache
- * the current value, but can keep reading it from the iterator.
- */
+ /// The current element.
+ ///
+ /// If the iterator has not yet been moved to the first element
+ /// ([moveNext] has not been called yet),
+ /// or if the iterator has been moved past the last element of the [Iterable]
+ /// ([moveNext] has returned false),
+ /// then [current] is unspecified.
+ /// An [Iterator] may either throw or return an iterator specific default value
+ /// in that case.
+ ///
+ /// The `current` getter should keep its value until the next call to
+ /// [moveNext], even if an underlying collection changes.
+ /// After a successful call to `moveNext`, the user doesn't need to cache
+ /// the current value, but can keep reading it from the iterator.
E get current;
}
diff --git a/sdk/lib/core/list.dart b/sdk/lib/core/list.dart
index e342bb7..dc2404f 100644
--- a/sdk/lib/core/list.dart
+++ b/sdk/lib/core/list.dart
@@ -4,225 +4,205 @@
part of dart.core;
-/**
- * An indexable collection of objects with a length.
- *
- * Subclasses of this class implement different kinds of lists.
- * The most common kinds of lists are:
- *
- * * Fixed-length list.
- * An error occurs when attempting to use operations
- * that can change the length of the list.
- *
- * * Growable list. Full implementation of the API defined in this class.
- *
- * The default growable list, as created by `[]`, keeps
- * an internal buffer, and grows that buffer when necessary. This guarantees
- * that a sequence of [add] operations will each execute in amortized constant
- * time. Setting the length directly may take time proportional to the new
- * length, and may change the internal capacity so that a following add
- * operation will need to immediately increase the buffer capacity.
- * Other list implementations may have different performance behavior.
- *
- * The following code illustrates that some List implementations support
- * only a subset of the API.
- *
- * List<int> fixedLengthList = new List.filled(5);
- * fixedLengthList.length = 0; // Error
- * fixedLengthList.add(499); // Error
- * fixedLengthList[0] = 87;
- * List<int> growableList = [1, 2];
- * growableList.length = 0;
- * growableList.add(499);
- * growableList[0] = 87;
- *
- * Lists are [Iterable]. Iteration occurs over values in index order. Changing
- * the values does not affect iteration, but changing the valid
- * indices—that is, changing the list's length—between iteration
- * steps causes a [ConcurrentModificationError]. This means that only growable
- * lists can throw ConcurrentModificationError. If the length changes
- * temporarily and is restored before continuing the iteration, the iterator
- * does not detect it.
- *
- * It is generally not allowed to modify the list's length (adding or removing
- * elements) while an operation on the list is being performed,
- * for example during a call to [forEach] or [sort].
- * Changing the list's length while it is being iterated, either by iterating it
- * directly or through iterating an [Iterable] that is backed by the list, will
- * break the iteration.
- */
+/// An indexable collection of objects with a length.
+///
+/// Subclasses of this class implement different kinds of lists.
+/// The most common kinds of lists are:
+///
+/// * Fixed-length list.
+/// An error occurs when attempting to use operations
+/// that can change the length of the list.
+///
+/// * Growable list. Full implementation of the API defined in this class.
+///
+/// The default growable list, as created by `[]`, keeps
+/// an internal buffer, and grows that buffer when necessary. This guarantees
+/// that a sequence of [add] operations will each execute in amortized constant
+/// time. Setting the length directly may take time proportional to the new
+/// length, and may change the internal capacity so that a following add
+/// operation will need to immediately increase the buffer capacity.
+/// Other list implementations may have different performance behavior.
+///
+/// The following code illustrates that some List implementations support
+/// only a subset of the API.
+/// ```dart
+/// var fixedLengthList = List<int>.filled(5, 0);
+/// fixedLengthList.length = 0; // Error
+/// fixedLengthList.add(499); // Error
+/// fixedLengthList[0] = 87;
+/// var growableList = [1, 2];
+/// growableList.length = 0;
+/// growableList.add(499);
+/// growableList[0] = 87;
+/// ```
+/// Lists are [Iterable]. Iteration occurs over values in index order. Changing
+/// the values does not affect iteration, but changing the valid
+/// indices—that is, changing the list's length—between iteration
+/// steps causes a [ConcurrentModificationError]. This means that only growable
+/// lists can throw ConcurrentModificationError. If the length changes
+/// temporarily and is restored before continuing the iteration, the iterator
+/// might not detect it.
+///
+/// It is generally not allowed to modify the list's length (adding or removing
+/// elements) while an operation on the list is being performed,
+/// for example during a call to [forEach] or [sort].
+/// Changing the list's length while it is being iterated, either by iterating it
+/// directly or through iterating an [Iterable] that is backed by the list, will
+/// break the iteration.
abstract class List<E> implements EfficientLengthIterable<E> {
- /**
- * Creates a list of the given length.
- *
- * **NOTICE**: This constructor cannot be used in null-safe code.
- * Use [List.filled] to create a non-empty list.
- * This requires a fill value to initialize the list elements with.
- * To create an empty list, use `[]` for a growable list or
- * `List.empty` for a fixed length list (or where growability is determined
- * at run-time).
- *
- * The created list is fixed-length if [length] is provided.
- *
- * List fixedLengthList = new List.filled(3);
- * fixedLengthList.length; // 3
- * fixedLengthList.length = 1; // Error
- *
- * The list has length 0 and is growable if [length] is omitted.
- *
- * List growableList = [];
- * growableList.length; // 0;
- * growableList.length = 3;
- *
- * To create a growable list with a given length, for a nullable element type,
- * just assign the length right after creation:
- *
- * List growableList = []..length = 500;
- *
- * For a non-nullable element type, an alternative is the following:
- *
- * List<int> growableList = List<int>.filled(500, 0, growable: true);
- *
- * The [length] must not be negative or null, if it is provided.
- *
- * If the element type is not nullable, [length] must not be greater than
- * zero.
- */
- @deprecated
+ /// Creates a list of the given length.
+ ///
+ /// **NOTICE**: This constructor cannot be used in null-safe code.
+ /// Use [List.filled] to create a non-empty list.
+ /// This requires a fill value to initialize the list elements with.
+ /// To create an empty list, use `[]` for a growable list or
+ /// `List.empty` for a fixed length list (or where growability is determined
+ /// at run-time).
+ ///
+ /// The created list is fixed-length if [length] is provided.
+ /// ```dart
+ /// var fixedLengthList = List(3);
+ /// fixedLengthList.length; // 3
+ /// fixedLengthList.length = 1; // Error
+ /// ```
+ /// The list has length 0 and is growable if [length] is omitted.
+ /// ```dart
+ /// var growableList = List();
+ /// growableList.length; // 0;
+ /// growableList.length = 3;
+ /// ```
+ /// To create a growable list with a given length, for a nullable element type,
+ /// just assign the length right after creation:
+ /// ```dart
+ /// List<SomeNullableType> growableList = []..length = 500;
+ /// ```
+ /// For a non-nullable element type, an alternative is the following:
+ /// ```dart
+ /// List<int> growableList = List<int>.filled(500, 0, growable: true);
+ /// ```
+ /// The [length] must not be negative or null, if it is provided.
+ ///
+ /// If the element type is not nullable, [length] must not be greater than
+ /// zero.
+ @Deprecated("Use a list literal, [], or the List.filled constructor instead")
external factory List([int? length]);
- /**
- * Creates a list of the given length with [fill] at each position.
- *
- * The [length] must be a non-negative integer.
- *
- * Example:
- * ```dart
- * new List<int>.filled(3, 0, growable: true); // [0, 0, 0]
- * ```
- *
- * The created list is fixed-length if [growable] is false (the default)
- * and growable if [growable] is true.
- * If the list is growable, changing its length will not initialize new
- * entries with [fill].
- * After being created and filled, the list is no different from any other
- * growable or fixed-length list created using [List].
- *
- * All elements of the returned list share the same [fill] value.
- * ```
- * var shared = new List.filled(3, []);
- * shared[0].add(499);
- * print(shared); // => [[499], [499], [499]]
- * ```
- *
- * You can use [List.generate] to create a list with a new object at
- * each position.
- * ```
- * var unique = new List.generate(3, (_) => []);
- * unique[0].add(499);
- * print(unique); // => [[499], [], []]
- * ```
- */
+ /// Creates a list of the given length with [fill] at each position.
+ ///
+ /// The [length] must be a non-negative integer.
+ ///
+ /// Example:
+ /// ```dart
+ /// List<int>.filled(3, 0, growable: true); // [0, 0, 0]
+ /// ```
+ ///
+ /// The created list is fixed-length if [growable] is false (the default)
+ /// and growable if [growable] is true.
+ /// If the list is growable, increasing its [length] will *not* initialize
+ /// new entries with [fill].
+ /// After being created and filled, the list is no different from any other
+ /// growable or fixed-length list created
+ /// using `[]` or other [List] constructors.
+ ///
+ /// All elements of the created list share the same [fill] value.
+ /// ```
+ /// var shared = List.filled(3, []);
+ /// shared[0].add(499);
+ /// print(shared); // => [[499], [499], [499]]
+ /// ```
+ /// You can use [List.generate] to create a list with a fixed length
+ /// and a new object at each position.
+ /// ```
+ /// var unique = List.generate(3, (_) => []);
+ /// unique[0].add(499);
+ /// print(unique); // => [[499], [], []]
+ /// ```
external factory List.filled(int length, E fill, {bool growable = false});
- /**
- * Creates a new empty list.
- *
- * If [growable] is `false`, which is the default,
- * the list is a fixed-length list of length zero.
- * If [growable] is `true`, the list is growable and equivalent to `<E>[]`.
- */
+ /// Creates a new empty list.
+ ///
+ /// If [growable] is `false`, which is the default,
+ /// the list is a fixed-length list of length zero.
+ /// If [growable] is `true`, the list is growable and equivalent to `<E>[]`.
@Since("2.8")
external factory List.empty({bool growable = false});
- /**
- * Creates a list containing all [elements].
- *
- * The [Iterator] of [elements] provides the order of the elements.
- *
- * All the [elements] should be instances of [E].
- * The `elements` iterable itself may have any element type, so this
- * constructor can be used to down-cast a `List`, for example as:
- * ```dart
- * List<SuperType> superList = ...;
- * List<SubType> subList =
- * new List<SubType>.from(superList.whereType<SubType>());
- * ```
- *
- * This constructor creates a growable list when [growable] is true;
- * otherwise, it returns a fixed-length list.
- */
+ /// Creates a list containing all [elements].
+ ///
+ /// The [Iterator] of [elements] provides the order of the elements.
+ ///
+ /// All the [elements] should be instances of [E].
+ /// The `elements` iterable itself may have any element type, so this
+ /// constructor can be used to down-cast a `List`, for example as:
+ /// ```dart
+ /// List<dynamic> dynList = ...some JSON value...;
+ /// List<Map<String, dynamic>> fooList =
+ /// List.from(dynList.where((x) => x is Map && map["kind"] == "foo"));
+ /// ```
+ ///
+ /// This constructor creates a growable list when [growable] is true;
+ /// otherwise, it returns a fixed-length list.
external factory List.from(Iterable elements, {bool growable = true});
- /**
- * Creates a list from [elements].
- *
- * The [Iterator] of [elements] provides the order of the elements.
- *
- * This constructor creates a growable list when [growable] is true;
- * otherwise, it returns a fixed-length list.
- */
+ /// Creates a list from [elements].
+ ///
+ /// The [Iterator] of [elements] provides the order of the elements.
+ ///
+ /// This constructor creates a growable list when [growable] is true;
+ /// otherwise, it returns a fixed-length list.
external factory List.of(Iterable<E> elements, {bool growable = true});
- /**
- * Generates a list of values.
- *
- * Creates a list with [length] positions and fills it with values created by
- * calling [generator] for each index in the range `0` .. `length - 1`
- * in increasing order.
- * ```dart
- * List<int>.generate(3, (int index) => index * index); // [0, 1, 4]
- * ```
- * The created list is fixed-length if [growable] is set to false.
- *
- * The [length] must be non-negative.
- */
+ /// Generates a list of values.
+ ///
+ /// Creates a list with [length] positions and fills it with values created by
+ /// calling [generator] for each index in the range `0` .. `length - 1`
+ /// in increasing order.
+ /// ```dart
+ /// List<int>.generate(3, (int index) => index * index); // [0, 1, 4]
+ /// ```
+ /// The created list is fixed-length if [growable] is set to false.
+ ///
+ /// The [length] must be non-negative.
external factory List.generate(int length, E generator(int index),
{bool growable = true});
- /**
- * Creates an unmodifiable list containing all [elements].
- *
- * The [Iterator] of [elements] provides the order of the elements.
- *
- * An unmodifiable list cannot have its length or elements changed.
- * If the elements are themselves immutable, then the resulting list
- * is also immutable.
- */
+ /// Creates an unmodifiable list containing all [elements].
+ ///
+ /// The [Iterator] of [elements] provides the order of the elements.
+ ///
+ /// An unmodifiable list cannot have its length or elements changed.
+ /// If the elements are themselves immutable, then the resulting list
+ /// is also immutable.
external factory List.unmodifiable(Iterable elements);
- /**
- * Adapts [source] to be a `List<T>`.
- *
- * Any time the list would produce an element that is not a [T],
- * the element access will throw.
- *
- * Any time a [T] value is attempted stored into the adapted list,
- * the store will throw unless the value is also an instance of [S].
- *
- * If all accessed elements of [source] are actually instances of [T],
- * and if all elements stored into the returned list are actually instance
- * of [S],
- * then the returned list can be used as a `List<T>`.
- */
+ /// Adapts [source] to be a `List<T>`.
+ ///
+ /// Any time the list would produce an element that is not a [T],
+ /// the element access will throw.
+ ///
+ /// Any time a [T] value is attempted stored into the adapted list,
+ /// the store will throw unless the value is also an instance of [S].
+ ///
+ /// If all accessed elements of [source] are actually instances of [T],
+ /// and if all elements stored into the returned list are actually instance
+ /// of [S],
+ /// then the returned list can be used as a `List<T>`.
static List<T> castFrom<S, T>(List<S> source) => CastList<S, T>(source);
- /**
- * Copy a range of one list into another list.
- *
- * This is a utility function that can be used to implement methods like
- * [setRange].
- *
- * The range from [start] to [end] must be a valid range of [source],
- * and there must be room for `end - start` elements from position [at].
- * If [start] is omitted, it defaults to zero.
- * If [end] is omitted, it defaults to [source.length].
- *
- * If [source] and [target] is the same list, overlapping source and target
- * ranges are respected so that the target range ends up containing the
- * initial content of the source range.
- * Otherwise the order of element copying is not guaranteed.
- */
+ /// Copy a range of one list into another list.
+ ///
+ /// This is a utility function that can be used to implement methods like
+ /// [setRange].
+ ///
+ /// The range from [start] to [end] must be a valid range of [source],
+ /// and there must be room for `end - start` elements from position [at].
+ /// If [start] is omitted, it defaults to zero.
+ /// If [end] is omitted, it defaults to [source.length].
+ ///
+ /// If [source] and [target] is the same list, overlapping source and target
+ /// ranges are respected so that the target range ends up containing the
+ /// initial content of the source range.
+ /// Otherwise the order of element copying is not guaranteed.
static void copyRange<T>(List<T> target, int at, List<T> source,
[int? start, int? end]) {
start ??= 0;
@@ -247,19 +227,17 @@
}
}
- /**
- * Write the elements of an iterable into a list.
- *
- * This is a utility function that can be used to implement methods like
- * [setAll].
- *
- * The elements of [source] are written into [target] from position [at].
- * The [source] must not contain more elements after writing the last
- * position of [target].
- *
- * If the source is a list, the [copyRange] function is likely to be more
- * efficient.
- */
+ /// Write the elements of an iterable into a list.
+ ///
+ /// This is a utility function that can be used to implement methods like
+ /// [setAll].
+ ///
+ /// The elements of [source] are written into [target] from position [at].
+ /// The [source] must not contain more elements after writing the last
+ /// position of [target].
+ ///
+ /// If the source is a list, the [copyRange] function is likely to be more
+ /// efficient.
static void writeIterable<T>(List<T> target, int at, Iterable<T> source) {
RangeError.checkValueInInterval(at, 0, target.length, "at");
int index = at;
@@ -273,484 +251,444 @@
}
}
- /**
- * Returns a view of this list as a list of [R] instances.
- *
- * If this list contains only instances of [R], all read operations
- * will work correctly. If any operation tries to access an element
- * that is not an instance of [R], the access will throw instead.
- *
- * Elements added to the list (e.g., by using [add] or [addAll])
- * must be instance of [R] to be valid arguments to the adding function,
- * and they must be instances of [E] as well to be accepted by
- * this list as well.
- *
- * Typically implemented as `List.castFrom<E, R>(this)`.
- */
+ /// Returns a view of this list as a list of [R] instances.
+ ///
+ /// If this list contains only instances of [R], all read operations
+ /// will work correctly. If any operation tries to access an element
+ /// that is not an instance of [R], the access will throw instead.
+ ///
+ /// Elements added to the list (e.g., by using [add] or [addAll])
+ /// must be instance of [R] to be valid arguments to the adding function,
+ /// and they must be instances of [E] as well to be accepted by
+ /// this list as well.
+ ///
+ /// Typically implemented as `List.castFrom<E, R>(this)`.
List<R> cast<R>();
- /**
- * Returns the object at the given [index] in the list
- * or throws a [RangeError] if [index] is out of bounds.
- */
+ /// The object at the given [index] in the list.
+ ///
+ /// The [index] must be a valid index of this list,
+ /// which means that `index` must be non-negative and
+ /// less than [length].
E operator [](int index);
- /**
- * Sets the value at the given [index] in the list to [value]
- * or throws a [RangeError] if [index] is out of bounds.
- */
+ /// Sets the value at the given [index] in the list to [value].
+ ///
+ /// The [index] must be a valid index of this list,
+ /// which means that `index` must be non-negative and
+ /// less than [length].
void operator []=(int index, E value);
- /**
- * Updates the first position of the list to contain [value].
- *
- * Equivalent to `theList[0] = value;`.
- *
- * The list must be non-empty.
- */
+ /// Updates the first position of the list to contain [value].
+ ///
+ /// Equivalent to `theList[0] = value;`.
+ ///
+ /// The list must be non-empty.
void set first(E value);
- /**
- * Updates the last position of the list to contain [value].
- *
- * Equivalent to `theList[theList.length - 1] = value;`.
- *
- * The list must be non-empty.
- */
+ /// Updates the last position of the list to contain [value].
+ ///
+ /// Equivalent to `theList[theList.length - 1] = value;`.
+ ///
+ /// The list must be non-empty.
void set last(E value);
- /**
- * The number of objects in this list.
- *
- * The valid indices for a list are `0` through `length - 1`.
- */
+ /// The number of objects in this list.
+ ///
+ /// The valid indices for a list are `0` through `length - 1`.
int get length;
- /**
- * Changes the length of this list.
- *
- * If [newLength] is greater than
- * the current length, entries are initialized to `null`.
- * Increasing the length fails if the element type does not allow `null`.
- *
- * Throws an [UnsupportedError] if the list is fixed-length or
- * if attempting to enlarge the list when `null` is not a valid element.
- */
+ /// Changes the length of this list.
+ ///
+ /// The list must be growable.
+ /// If [newLength] is greater than current length,
+ /// new entries are initialized to `null`,
+ /// so [newLength] must not be greater than the current length
+ /// if the element type [E] is non-nullable.
set length(int newLength);
- /**
- * Adds [value] to the end of this list,
- * extending the length by one.
- *
- * Throws an [UnsupportedError] if the list is fixed-length.
- */
+ /// Adds [value] to the end of this list,
+ /// extending the length by one.
+ ///
+ /// The list must be growable.
void add(E value);
- /**
- * Appends all objects of [iterable] to the end of this list.
- *
- * Extends the length of the list by the number of objects in [iterable].
- * Throws an [UnsupportedError] if this list is fixed-length.
- */
+ /// Appends all objects of [iterable] to the end of this list.
+ ///
+ /// Extends the length of the list by the number of objects in [iterable].
+ /// The list must be growable.
void addAll(Iterable<E> iterable);
- /**
- * Returns an [Iterable] of the objects in this list in reverse order.
- */
+ /// An [Iterable] of the objects in this list in reverse order.
Iterable<E> get reversed;
- /**
- * Sorts this list according to the order specified by the [compare] function.
- *
- * The [compare] function must act as a [Comparator].
- *
- * List<String> numbers = ['two', 'three', 'four'];
- * // Sort from shortest to longest.
- * numbers.sort((a, b) => a.length.compareTo(b.length));
- * print(numbers); // [two, four, three]
- *
- * The default List implementations use [Comparable.compare] if
- * [compare] is omitted.
- *
- * List<int> nums = [13, 2, -11];
- * nums.sort();
- * print(nums); // [-11, 2, 13]
- *
- * A [Comparator] may compare objects as equal (return zero), even if they
- * are distinct objects.
- * The sort function is not guaranteed to be stable, so distinct objects
- * that compare as equal may occur in any order in the result:
- *
- * List<String> numbers = ['one', 'two', 'three', 'four'];
- * numbers.sort((a, b) => a.length.compareTo(b.length));
- * print(numbers); // [one, two, four, three] OR [two, one, four, three]
- */
+ /// Sorts this list according to the order specified by the [compare] function.
+ ///
+ /// The [compare] function must act as a [Comparator].
+ /// ```dart
+ /// var numbers = ['two', 'three', 'four'];
+ /// // Sort from shortest to longest.
+ /// numbers.sort((a, b) => a.length.compareTo(b.length));
+ /// print(numbers); // [two, four, three]
+ /// ```
+ /// The default [List] implementations use [Comparable.compare] if
+ /// [compare] is omitted.
+ /// ```dart
+ /// List<int> nums = [13, 2, -11];
+ /// nums.sort();
+ /// print(nums); // [-11, 2, 13]
+ /// ```
+ /// In that case, the elements of the list must be [Comparable] to
+ /// each other.
+ ///
+ /// A [Comparator] may compare objects as equal (return zero), even if they
+ /// are distinct objects.
+ /// The sort function is not guaranteed to be stable, so distinct objects
+ /// that compare as equal may occur in any order in the result:
+ /// ```dart
+ /// var numbers = ['one', 'two', 'three', 'four'];
+ /// numbers.sort((a, b) => a.length.compareTo(b.length));
+ /// print(numbers); // [one, two, four, three] OR [two, one, four, three]
+ /// ```
void sort([int compare(E a, E b)?]);
- /**
- * Shuffles the elements of this list randomly.
- */
+ /// Shuffles the elements of this list randomly.
void shuffle([Random? random]);
- /**
- * Returns the first index of [element] in this list.
- *
- * Searches the list from index [start] to the end of the list.
- * The first time an object [:o:] is encountered so that [:o == element:],
- * the index of [:o:] is returned.
- *
- * List<String> notes = ['do', 're', 'mi', 're'];
- * notes.indexOf('re'); // 1
- * notes.indexOf('re', 2); // 3
- *
- * Returns -1 if [element] is not found.
- *
- * notes.indexOf('fa'); // -1
- */
+ /// The first index of [element] in this list.
+ ///
+ /// Searches the list from index [start] to the end of the list.
+ /// The first time an object `o` is encountered so that `o == element`,
+ /// the index of `o` is returned.
+ /// ```dart
+ /// var notes = ['do', 're', 'mi', 're'];
+ /// notes.indexOf('re'); // 1
+ /// notes.indexOf('re', 2); // 3
+ /// ```
+ /// Returns -1 if [element] is not found.
+ /// ```dart
+ /// notes.indexOf('fa'); // -1
+ /// ```
int indexOf(E element, [int start = 0]);
- /**
- * Returns the first index in the list that satisfies the provided [test].
- *
- * Searches the list from index [start] to the end of the list.
- * The first time an object `o` is encountered so that `test(o)` is true,
- * the index of `o` is returned.
- *
- * ```
- * List<String> notes = ['do', 're', 'mi', 're'];
- * notes.indexWhere((note) => note.startsWith('r')); // 1
- * notes.indexWhere((note) => note.startsWith('r'), 2); // 3
- * ```
- *
- * Returns -1 if [element] is not found.
- * ```
- * notes.indexWhere((note) => note.startsWith('k')); // -1
- * ```
- */
+ /// The first index in the list that satisfies the provided [test].
+ ///
+ /// Searches the list from index [start] to the end of the list.
+ /// The first time an object `o` is encountered so that `test(o)` is true,
+ /// the index of `o` is returned.
+ ///
+ /// ```
+ /// var notes = ['do', 're', 'mi', 're'];
+ /// notes.indexWhere((note) => note.startsWith('r')); // 1
+ /// notes.indexWhere((note) => note.startsWith('r'), 2); // 3
+ /// ```
+ ///
+ /// Returns -1 if [element] is not found.
+ /// ```
+ /// notes.indexWhere((note) => note.startsWith('k')); // -1
+ /// ```
int indexWhere(bool test(E element), [int start = 0]);
- /**
- * Returns the last index in the list that satisfies the provided [test].
- *
- * Searches the list from index [start] to 0.
- * The first time an object `o` is encountered so that `test(o)` is true,
- * the index of `o` is returned.
- * If [start] is omitted, it defaults to the [length] of the list.
- *
- * ```
- * List<String> notes = ['do', 're', 'mi', 're'];
- * notes.lastIndexWhere((note) => note.startsWith('r')); // 3
- * notes.lastIndexWhere((note) => note.startsWith('r'), 2); // 1
- * ```
- *
- * Returns -1 if [element] is not found.
- * ```
- * notes.lastIndexWhere((note) => note.startsWith('k')); // -1
- * ```
- */
+ /// The last index in the list that satisfies the provided [test].
+ ///
+ /// Searches the list from index [start] to 0.
+ /// The first time an object `o` is encountered so that `test(o)` is true,
+ /// the index of `o` is returned.
+ /// If [start] is omitted, it defaults to the [length] of the list.
+ ///
+ /// ```
+ /// var notes = ['do', 're', 'mi', 're'];
+ /// notes.lastIndexWhere((note) => note.startsWith('r')); // 3
+ /// notes.lastIndexWhere((note) => note.startsWith('r'), 2); // 1
+ /// ```
+ ///
+ /// Returns -1 if [element] is not found.
+ /// ```
+ /// notes.lastIndexWhere((note) => note.startsWith('k')); // -1
+ /// ```
int lastIndexWhere(bool test(E element), [int? start]);
- /**
- * Returns the last index of [element] in this list.
- *
- * Searches the list backwards from index [start] to 0.
- *
- * The first time an object [:o:] is encountered so that [:o == element:],
- * the index of [:o:] is returned.
- *
- * List<String> notes = ['do', 're', 'mi', 're'];
- * notes.lastIndexOf('re', 2); // 1
- *
- * If [start] is not provided, this method searches from the end of the
- * list.
- *
- * notes.lastIndexOf('re'); // 3
- *
- * Returns -1 if [element] is not found.
- *
- * notes.lastIndexOf('fa'); // -1
- */
+ /// The last index of [element] in this list.
+ ///
+ /// Searches the list backwards from index [start] to 0.
+ ///
+ /// The first time an object `o` is encountered so that `o == element`,
+ /// the index of `o` is returned.
+ /// ```dart
+ /// var notes = ['do', 're', 'mi', 're'];
+ /// notes.lastIndexOf('re', 2); // 1
+ /// ```
+ /// If [start] is not provided, this method searches from the end of the
+ /// list.
+ /// ```dart
+ /// notes.lastIndexOf('re'); // 3
+ /// ```
+ /// Returns -1 if [element] is not found.
+ /// ```dart
+ /// notes.lastIndexOf('fa'); // -1
+ /// ```
int lastIndexOf(E element, [int? start]);
- /**
- * Removes all objects from this list;
- * the length of the list becomes zero.
- *
- * Throws an [UnsupportedError], and retains all objects, if this
- * is a fixed-length list.
- */
+ /// Removes all objects from this list; the length of the list becomes zero.
+ ///
+ /// The list must be growable.
void clear();
- /**
- * Inserts [element] at position [index] in this list.
- *
- * This increases the length of the list by one and shifts all objects
- * at or after the index towards the end of the list.
- *
- * The list must be growable.
- * The [index] value must be non-negative and no greater than [length].
- */
+ /// Inserts [element] at position [index] in this list.
+ ///
+ /// This increases the length of the list by one and shifts all objects
+ /// at or after the index towards the end of the list.
+ ///
+ /// The list must be growable.
+ /// The [index] value must be non-negative and no greater than [length].
void insert(int index, E element);
- /**
- * Inserts all objects of [iterable] at position [index] in this list.
- *
- * This increases the length of the list by the length of [iterable] and
- * shifts all later objects towards the end of the list.
- *
- * The list must be growable.
- * The [index] value must be non-negative and no greater than [length].
- */
+ /// Inserts all objects of [iterable] at position [index] in this list.
+ ///
+ /// This increases the length of the list by the length of [iterable] and
+ /// shifts all later objects towards the end of the list.
+ ///
+ /// The list must be growable.
+ /// The [index] value must be non-negative and no greater than [length].
void insertAll(int index, Iterable<E> iterable);
- /**
- * Overwrites objects of `this` with the objects of [iterable], starting
- * at position [index] in this list.
- *
- * List<String> list = ['a', 'b', 'c'];
- * list.setAll(1, ['bee', 'sea']);
- * list.join(', '); // 'a, bee, sea'
- *
- * This operation does not increase the length of `this`.
- *
- * The [index] must be non-negative and no greater than [length].
- *
- * The [iterable] must not have more elements than what can fit from [index]
- * to [length].
- *
- * If `iterable` is based on this list, its values may change /during/ the
- * `setAll` operation.
- */
+ /// Overwrites elements with the objects of [iterable].
+ ///
+ /// The elements of [iterable] are written into this list,
+ /// starting at position [index].
+ /// ```dart
+ /// var list = ['a', 'b', 'c', 'd'];
+ /// list.setAll(1, ['bee', 'sea']);
+ /// list.join(', '); // 'a, bee, sea, d'
+ /// ```
+ /// This operation does not increase the length of the list.
+ ///
+ /// The [index] must be non-negative and no greater than [length].
+ ///
+ /// The [iterable] must not have more elements than what can fit from [index]
+ /// to [length].
+ ///
+ /// If `iterable` is based on this list, its values may change _during_ the
+ /// `setAll` operation.
void setAll(int index, Iterable<E> iterable);
- /**
- * Removes the first occurrence of [value] from this list.
- *
- * Returns true if [value] was in the list, false otherwise.
- *
- * List<String> parts = ['head', 'shoulders', 'knees', 'toes'];
- * parts.remove('head'); // true
- * parts.join(', '); // 'shoulders, knees, toes'
- *
- * The method has no effect if [value] was not in the list.
- *
- * // Note: 'head' has already been removed.
- * parts.remove('head'); // false
- * parts.join(', '); // 'shoulders, knees, toes'
- *
- * An [UnsupportedError] occurs if the list is fixed-length.
- */
+ /// Removes the first occurrence of [value] from this list.
+ ///
+ /// Returns true if [value] was in the list, false otherwise.
+ /// ```dart
+ /// var parts = ['head', 'shoulders', 'knees', 'toes'];
+ /// parts.remove('head'); // true
+ /// parts.join(', '); // 'shoulders, knees, toes'
+ /// ```
+ /// The method has no effect if [value] was not in the list.
+ /// ```dart
+ /// // Note: 'head' has already been removed.
+ /// parts.remove('head'); // false
+ /// parts.join(', '); // 'shoulders, knees, toes'
+ /// ```
+ ///
+ /// The list must be growable.
bool remove(Object? value);
- /**
- * Removes the object at position [index] from this list.
- *
- * This method reduces the length of `this` by one and moves all later objects
- * down by one position.
- *
- * Returns the removed object.
- *
- * The [index] must be in the range `0 ≤ index < length`.
- *
- * Throws an [UnsupportedError] if this is a fixed-length list. In that case
- * the list is not modified.
- */
+ /// Removes the object at position [index] from this list.
+ ///
+ /// This method reduces the length of `this` by one and moves all later objects
+ /// down by one position.
+ ///
+ /// Returns the removed value.
+ ///
+ /// The [index] must be in the range `0 ≤ index < length`.
+ ///
+ /// The list must be growable.
E removeAt(int index);
- /**
- * Pops and returns the last object in this list.
- *
- * The list must not be empty.
- *
- * Throws an [UnsupportedError] if this is a fixed-length list.
- */
+ /// Removes and returns the last object in this list.
+ ///
+ /// The list must be growable and non-empty.
E removeLast();
- /**
- * Removes all objects from this list that satisfy [test].
- *
- * An object [:o:] satisfies [test] if [:test(o):] is true.
- *
- * List<String> numbers = ['one', 'two', 'three', 'four'];
- * numbers.removeWhere((item) => item.length == 3);
- * numbers.join(', '); // 'three, four'
- *
- * Throws an [UnsupportedError] if this is a fixed-length list.
- */
+ /// Removes all objects from this list that satisfy [test].
+ ///
+ /// An object `o` satisfies [test] if `test(o)` is true.
+ /// ```dart
+ /// var numbers = ['one', 'two', 'three', 'four'];
+ /// numbers.removeWhere((item) => item.length == 3);
+ /// numbers.join(', '); // 'three, four'
+ /// ```
+ /// The list must be growable.
void removeWhere(bool test(E element));
- /**
- * Removes all objects from this list that fail to satisfy [test].
- *
- * An object [:o:] satisfies [test] if [:test(o):] is true.
- *
- * List<String> numbers = ['one', 'two', 'three', 'four'];
- * numbers.retainWhere((item) => item.length == 3);
- * numbers.join(', '); // 'one, two'
- *
- * Throws an [UnsupportedError] if this is a fixed-length list.
- */
+ /// Removes all objects from this list that fail to satisfy [test].
+ ///
+ /// An object `o` satisfies [test] if `test(o)` is true.
+ /// ```dart
+ /// var numbers = ['one', 'two', 'three', 'four'];
+ /// numbers.retainWhere((item) => item.length == 3);
+ /// numbers.join(', '); // 'one, two'
+ /// ```
+ /// The list must be growable.
void retainWhere(bool test(E element));
- /**
- * Returns the concatenation of this list and [other].
- *
- * Returns a new list containing the elements of this list followed by
- * the elements of [other].
- *
- * The default behavior is to return a normal growable list.
- * Some list types may choose to return a list of the same type as themselves
- * (see [Uint8List.+]);
- */
+ /// Returns the concatenation of this list and [other].
+ ///
+ /// Returns a new list containing the elements of this list followed by
+ /// the elements of [other].
+ ///
+ /// The default behavior is to return a normal growable list.
+ /// Some list types may choose to return a list of the same type as themselves
+ /// (see [Uint8List.+]);
List<E> operator +(List<E> other);
- /**
- * Returns a new list containing the elements between [start] and [end].
- *
- * The new list is a `List<E>` containing the elements of this list at
- * positions greater than or equal to [start] and less than [end] in the same
- * order as they occur in this list.
- *
- * ```dart
- * var colors = ["red", "green", "blue", "orange", "pink"];
- * print(colors.sublist(1, 3)); // [green, blue]
- * ```
- *
- * If [end] is omitted, it defaults to the [length] of this list.
- *
- * ```dart
- * print(colors.sublist(1)); // [green, blue, orange, pink]
- * ```
- *
- * The `start` and `end` positions must satisfy the relations
- * 0 ≤ `start` ≤ `end` ≤ `this.length`
- * If `end` is equal to `start`, then the returned list is empty.
- */
+ /// Returns a new list containing the elements between [start] and [end].
+ ///
+ /// The new list is a `List<E>` containing the elements of this list at
+ /// positions greater than or equal to [start] and less than [end] in the same
+ /// order as they occur in this list.
+ ///
+ /// ```dart
+ /// var colors = ["red", "green", "blue", "orange", "pink"];
+ /// print(colors.sublist(1, 3)); // [green, blue]
+ /// ```
+ ///
+ /// If [end] is omitted, it defaults to the [length] of this list.
+ ///
+ /// ```dart
+ /// print(colors.sublist(1)); // [green, blue, orange, pink]
+ /// ```
+ ///
+ /// The `start` and `end` positions must satisfy the relations
+ /// 0 ≤ `start` ≤ `end` ≤ [length]
+ /// If `end` is equal to `start`, then the returned list is empty.
List<E> sublist(int start, [int? end]);
- /**
- * Returns an [Iterable] that iterates over the objects in the range
- * [start] inclusive to [end] exclusive.
- *
- * The provided range, given by [start] and [end], must be valid at the time
- * of the call.
- *
- * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
- * `len` is this list's `length`. The range starts at `start` and has length
- * `end - start`. An empty range (with `end == start`) is valid.
- *
- * The returned [Iterable] behaves like `skip(start).take(end - start)`.
- * That is, it does *not* throw if this list changes size.
- *
- * List<String> colors = ['red', 'green', 'blue', 'orange', 'pink'];
- * Iterable<String> range = colors.getRange(1, 4);
- * range.join(', '); // 'green, blue, orange'
- * colors.length = 3;
- * range.join(', '); // 'green, blue'
- */
+ /// Creates an [Iterable] that iterates over a range of elements.
+ ///
+ /// The returned iterable iterates over the elements of this list
+ /// with positions greater than or equal to [start] and less than [end].
+ ///
+ /// The provided range, [start] and [end], must be valid at the time
+ /// of the call.
+ /// A range from [start] to [end] is valid if 0 ≤ `start` ≤ `end` ≤ [length].
+ /// An empty range (with `end == start`) is valid.
+ ///
+ /// The returned [Iterable] behaves like `skip(start).take(end - start)`.
+ /// That is, it does *not* break if this list changes size, it just
+ /// ends early if it reaches the end of the list early
+ /// (if `end`, or even `start`, becomes greater than [length]).
+ /// ```dart
+ /// List<String> colors = ['red', 'green', 'blue', 'orange', 'pink'];
+ /// Iterable<String> range = colors.getRange(1, 4);
+ /// range.join(', '); // 'green, blue, orange'
+ /// colors.length = 3;
+ /// range.join(', '); // 'green, blue'
+ /// ```
Iterable<E> getRange(int start, int end);
- /**
- * Copies the objects of [iterable], skipping [skipCount] objects first,
- * into the range [start], inclusive, to [end], exclusive, of the list.
- *
- * List<int> list1 = [1, 2, 3, 4];
- * List<int> list2 = [5, 6, 7, 8, 9];
- * // Copies the 4th and 5th items in list2 as the 2nd and 3rd items
- * // of list1.
- * list1.setRange(1, 3, list2, 3);
- * list1.join(', '); // '1, 8, 9, 4'
- *
- * The provided range, given by [start] and [end], must be valid.
- * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
- * `len` is this list's `length`. The range starts at `start` and has length
- * `end - start`. An empty range (with `end == start`) is valid.
- *
- * The [iterable] must have enough objects to fill the range from `start`
- * to `end` after skipping [skipCount] objects.
- *
- * If `iterable` is this list, the operation copies the elements
- * originally in the range from `skipCount` to `skipCount + (end - start)` to
- * the range `start` to `end`, even if the two ranges overlap.
- *
- * If `iterable` depends on this list in some other way, no guarantees are
- * made.
- */
+ /// Writes some elements of [iterable] into a range of this list.
+ ///
+ /// Copies the objects of [iterable], skipping [skipCount] objects first,
+ /// into the range from [start], inclusive, to [end], exclusive, of this list.
+ /// ```dart
+ /// var list1 = [1, 2, 3, 4];
+ /// var list2 = [5, 6, 7, 8, 9];
+ /// // Copies the 4th and 5th items in list2 as the 2nd and 3rd items
+ /// // of list1.
+ /// list1.setRange(1, 3, list2, 3);
+ /// list1.join(', '); // '1, 8, 9, 4'
+ /// ```
+ /// The provided range, given by [start] and [end], must be valid.
+ /// A range from [start] to [end] is valid if 0 ≤ `start` ≤ `end` ≤ [length].
+ /// An empty range (with `end == start`) is valid.
+ ///
+ /// The [iterable] must have enough objects to fill the range from `start`
+ /// to `end` after skipping [skipCount] objects.
+ ///
+ /// If `iterable` is this list, the operation correctly copies the elements
+ /// originally in the range from `skipCount` to `skipCount + (end - start)` to
+ /// the range `start` to `end`, even if the two ranges overlap.
+ ///
+ /// If `iterable` depends on this list in some other way, no guarantees are
+ /// made.
void setRange(int start, int end, Iterable<E> iterable, [int skipCount = 0]);
- /**
- * Removes the objects in the range [start] inclusive to [end] exclusive.
- *
- * The provided range, given by [start] and [end], must be valid.
- * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
- * `len` is this list's `length`. The range starts at `start` and has length
- * `end - start`. An empty range (with `end == start`) is valid.
- *
- * Throws an [UnsupportedError] if this is a fixed-length list. In that case
- * the list is not modified.
- */
+ /// Removes a range of elements from the list.
+ ///
+ /// Removes the elements with positions greater than or equal to [start]
+ /// and less than [end], from the list.
+ /// This reduces the list's length by `end - start`.
+ ///
+ /// The provided range, given by [start] and [end], must be valid.
+ /// A range from [start] to [end] is valid if 0 ≤ `start` ≤ `end` ≤ [length].
+ /// An empty range (with `end == start`) is valid.
+ ///
+ /// The list must be growable.
void removeRange(int start, int end);
- /**
- * Sets the objects in the range [start] inclusive to [end] exclusive
- * to the given [fillValue].
- *
- * The provided range, given by [start] and [end], must be valid.
- * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
- * `len` is this list's `length`. The range starts at `start` and has length
- * `end - start`. An empty range (with `end == start`) is valid.
- *
- * Example:
- * ```dart
- * List<int> list = new List.filled(3);
- * list.fillRange(0, 2, 1);
- * print(list); // [1, 1, null]
- * ```
- *
- * If the element type is not nullable, omitting [fillValue] or passing `null`
- * as [fillValue] will make the `fillRange` fail.
- */
+ /// Overwrites a range of elements with [fillValue].
+ ///
+ /// Sets the positions greater than or equal to [start] and less than [end],
+ /// to [fillValue].
+ ///
+ /// The provided range, given by [start] and [end], must be valid.
+ /// A range from [start] to [end] is valid if 0 ≤ `start` ≤ `end` ≤ [length].
+ /// An empty range (with `end == start`) is valid.
+ ///
+ /// Example:
+ /// ```dart
+ /// var list = List.filled(5, -1);
+ /// print(list); // [-1, -1, -1, -1, -1]
+ /// list.fillRange(1, 3, 4);
+ /// print(list); // [-1, 4, 4, -1, -1]
+ /// ```
+ ///
+ /// If the element type is not nullable, the [fillValue] must be provided and
+ /// must be non-`null`.
void fillRange(int start, int end, [E? fillValue]);
- /**
- * Removes the objects in the range [start] inclusive to [end] exclusive
- * and inserts the contents of [replacement] in its place.
- *
- * List<int> list = [1, 2, 3, 4, 5];
- * list.replaceRange(1, 4, [6, 7]);
- * list.join(', '); // '1, 6, 7, 5'
- *
- * The provided range, given by [start] and [end], must be valid.
- * A range from [start] to [end] is valid if `0 <= start <= end <= len`, where
- * `len` is this list's `length`. The range starts at `start` and has length
- * `end - start`. An empty range (with `end == start`) is valid.
- *
- * This method does not work on fixed-length lists, even when [replacement]
- * has the same number of elements as the replaced range. In that case use
- * [setRange] instead.
- */
+ /// Replaces a range of elements with the elements of [replacement].
+ ///
+ /// Removes the objects in the range from [start] to [end],
+ /// then inserts the elements of [replacements] at [start].
+ /// ```dart
+ /// var list = [1, 2, 3, 4, 5];
+ /// list.replaceRange(1, 4, [6, 7]);
+ /// list.join(', '); // '1, 6, 7, 5'
+ /// ```
+ /// The provided range, given by [start] and [end], must be valid.
+ /// A range from [start] to [end] is valid if 0 ≤ `start` ≤ `end` ≤ [length].
+ /// An empty range (with `end == start`) is valid.
+ ///
+ /// The operation `list.replaceRange(start, end, replacements)`
+ /// is roughly equivalent to:
+ /// ```dart
+ /// list.removeRange(start, end);
+ /// list.insertAll(start, replacements);
+ /// ```
+ /// but may be more efficient.
+ ///
+ /// The list must be growable.
+ /// This method does not work on fixed-length lists, even when [replacement]
+ /// has the same number of elements as the replaced range. In that case use
+ /// [setRange] instead.
void replaceRange(int start, int end, Iterable<E> replacement);
- /**
- * Returns an unmodifiable [Map] view of `this`.
- *
- * The map uses the indices of this list as keys and the corresponding objects
- * as values. The `Map.keys` [Iterable] iterates the indices of this list
- * in numerical order.
- *
- * List<String> words = ['fee', 'fi', 'fo', 'fum'];
- * Map<int, String> map = words.asMap(); // {0: fee, 1: fi, 2: fo, 3: fum}
- * map[0] + map[1]; // 'feefi';
- * map.keys.toList(); // [0, 1, 2, 3]
- */
+ /// An unmodifiable [Map] view of this list.
+ ///
+ /// The map uses the indices of this list as keys and the corresponding objects
+ /// as values. The `Map.keys` [Iterable] iterates the indices of this list
+ /// in numerical order.
+ /// ```dart
+ /// var words = ['fee', 'fi', 'fo', 'fum'];
+ /// var map = words.asMap(); // {0: fee, 1: fi, 2: fo, 3: fum}
+ /// map[0] + map[1]; // 'feefi';
+ /// map.keys.toList(); // [0, 1, 2, 3]
+ /// ```
Map<int, E> asMap();
- /**
- * Whether this list is equal to [other].
- *
- * Lists are, by default, only equal to themselves.
- * Even if [other] is also a list, the equality comparison
- * does not compare the elements of the two lists.
- */
+ /// Whether this list is equal to [other].
+ ///
+ /// Lists are, by default, only equal to themselves.
+ /// Even if [other] is also a list, the equality comparison
+ /// does not compare the elements of the two lists.
bool operator ==(Object other);
}
diff --git a/sdk/lib/core/map.dart b/sdk/lib/core/map.dart
index cbb1608..9c5572c 100644
--- a/sdk/lib/core/map.dart
+++ b/sdk/lib/core/map.dart
@@ -4,399 +4,350 @@
part of dart.core;
-/**
- * A collection of key/value pairs, from which you retrieve a value
- * using its associated key.
- *
- * There is a finite number of keys in the map,
- * and each key has exactly one value associated with it.
- *
- * Maps, and their keys and values, can be iterated.
- * The order of iteration is defined by the individual type of map.
- * Examples:
- *
- * * The plain [HashMap] is unordered (no order is guaranteed),
- * * the [LinkedHashMap] iterates in key insertion order,
- * * and a sorted map like [SplayTreeMap] iterates the keys in sorted order.
- *
- * It is generally not allowed to modify the map (add or remove keys) while
- * an operation is being performed on the map, for example in functions called
- * during a [forEach] or [putIfAbsent] call.
- * Modifying the map while iterating the keys or values
- * may also break the iteration.
- *
- * It is generally not allowed to modify the equality of keys (and thus not
- * their hashcode) while they are in the map. Some specialized subtypes may be
- * more permissive, in which case they should document this behavior.
- */
+/// A collection of key/value pairs, from which you retrieve a value
+/// using its associated key.
+///
+/// There is a finite number of keys in the map,
+/// and each key has exactly one value associated with it.
+///
+/// Maps, and their keys and values, can be iterated.
+/// The order of iteration is defined by the individual type of map.
+/// Examples:
+///
+/// * The plain [HashMap] is unordered (no order is guaranteed),
+/// * the [LinkedHashMap] iterates in key insertion order,
+/// * and a sorted map like [SplayTreeMap] iterates the keys in sorted order.
+///
+/// It is generally not allowed to modify the map (add or remove keys) while
+/// an operation is being performed on the map, for example in functions called
+/// during a [forEach] or [putIfAbsent] call.
+/// Modifying the map while iterating the keys or values
+/// may also break the iteration.
+///
+/// It is generally not allowed to modify the equality of keys (and thus not
+/// their hashcode) while they are in the map. Some specialized subtypes may be
+/// more permissive, in which case they should document this behavior.
abstract class Map<K, V> {
- /**
- * Creates a Map instance with the default implementation, [LinkedHashMap].
- *
- * This constructor is equivalent to the non-const map literal `<K,V>{}`.
- *
- * A `LinkedHashMap` requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows null as a key.
- * It iterates in key insertion order.
- */
+ /// Creates an empty [LinkedHashMap].
+ ///
+ /// This constructor is equivalent to the non-const map literal `<K,V>{}`.
+ ///
+ /// A `LinkedHashMap` requires the keys to implement compatible
+ /// `operator==` and `hashCode`.
+ /// It iterates in key insertion order.
external factory Map();
- /**
- * Creates a [LinkedHashMap] instance that contains all key/value pairs of
- * [other].
- *
- * The keys must all be instances of [K] and the values of [V].
- * The [other] map itself can have any type.
- *
- * A `LinkedHashMap` requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows `null` as a key.
- * It iterates in key insertion order.
- */
+ /// Creates a [LinkedHashMap] with the same keys and values as [other].
+ ///
+ /// The keys must all be instances of [K] and the values of [V].
+ /// The [other] map itself can have any type, unlike for [Map.of],
+ /// and the key and value types are checked (and can fail) at run-time.
+ ///
+ /// Prefer using [Map.of] when possible, and only use `Map.from`
+ /// to create a new map with more precise types than the original,
+ /// and when it's known that all the keys and values have those
+ /// more precise types.
+ ///
+ /// A `LinkedHashMap` requires the keys to implement compatible
+ /// `operator==` and `hashCode`.
+ /// It iterates in key insertion order.
factory Map.from(Map other) = LinkedHashMap<K, V>.from;
- /**
- * Creates a [LinkedHashMap] with the same keys and values as [other].
- *
- * A `LinkedHashMap` requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows `null` as a key.
- * It iterates in key insertion order.
- */
+ /// Creates a [LinkedHashMap] with the same keys and values as [other].
+ ///
+ /// A `LinkedHashMap` requires the keys to implement compatible
+ /// `operator==` and `hashCode`, and it allows `null` as a key.
+ /// It iterates in key insertion order.
factory Map.of(Map<K, V> other) = LinkedHashMap<K, V>.of;
- /**
- * Creates an unmodifiable hash based map containing the entries of [other].
- *
- * The keys must all be instances of [K] and the values of [V].
- * The [other] map itself can have any type.
- *
- * The map requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows `null` as a key.
- * The created map iterates keys in a fixed order,
- * preserving the order provided by [other].
- *
- * The resulting map behaves like the result of [Map.from],
- * except that the map returned by this constructor is not modifiable.
- */
+ /// Creates an unmodifiable hash-based map containing the entries of [other].
+ ///
+ /// The keys must all be instances of [K] and the values of [V].
+ /// The [other] map itself can have any type.
+ ///
+ /// The map requires the keys to implement compatible
+ /// `operator==` and `hashCode`.
+ /// The created map iterates keys in a fixed order,
+ /// preserving the order provided by [other].
+ ///
+ /// The resulting map behaves like the result of [Map.from],
+ /// except that the map returned by this constructor is not modifiable.
external factory Map.unmodifiable(Map<dynamic, dynamic> other);
- /**
- * Creates an identity map with the default implementation, [LinkedHashMap].
- *
- * An identity map uses [identical] for equality and [identityHashCode]
- * for hash codes of keys instead of the intrinsic [Object.==] and
- * [Object.hashCode] of the keys.
- *
- * The returned map allows `null` as a key.
- * It iterates in key insertion order.
- */
+ /// Creates an identity map with the default implementation, [LinkedHashMap].
+ ///
+ /// An identity map uses [identical] for equality and [identityHashCode]
+ /// for hash codes of keys instead of the intrinsic [Object.==] and
+ /// [Object.hashCode] of the keys.
+ ///
+ /// The map iterates in key insertion order.
factory Map.identity() = LinkedHashMap<K, V>.identity;
- /**
- * Creates a Map instance in which the keys and values are computed from the
- * [iterable].
- *
- * The created map is a [LinkedHashMap].
- * A `LinkedHashMap` requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows null as a key.
- * It iterates in key insertion order.
- *
- * For each element of the [iterable] this constructor computes a key/value
- * pair, by applying [key] and [value] respectively.
- *
- * The example below creates a new Map from a List. The keys of `map` are
- * `list` values converted to strings, and the values of the `map` are the
- * squares of the `list` values:
- *
- * List<int> list = [1, 2, 3];
- * Map<String, int> map = new Map.fromIterable(list,
- * key: (item) => item.toString(),
- * value: (item) => item * item);
- *
- * map['1'] + map['2']; // 1 + 4
- * map['3'] - map['2']; // 9 - 4
- *
- * If no values are specified for [key] and [value] the default is the
- * identity function.
- *
- * In the following example, the keys and corresponding values of `map`
- * are `list` values:
- *
- * map = new Map.fromIterable(list);
- * map[1] + map[2]; // 1 + 2
- * map[3] - map[2]; // 3 - 2
- *
- * The keys computed by the source [iterable] do not need to be unique. The
- * last occurrence of a key will simply overwrite any previous value.
- */
+ /// Creates a Map instance in which the keys and values are computed from the
+ /// [iterable].
+ ///
+ /// For each element of the [iterable], a key/value pair is computed
+ /// by applying [key] and [value] respectively to the element of the iterable.
+ ///
+ /// Equivalent to the map literal:
+ /// ```dart
+ /// <K, V>{for (var v in iterable) key(v): value(v)}
+ /// ```
+ /// The literal is generally preferable because it allows
+ /// for a more precise typing.
+ ///
+ /// The example below creates a new map from a list of integers.
+ /// The keys of `map` are the `list` values converted to strings,
+ /// and the values of the `map` are the squares of the `list` values:
+ /// ```dart
+ /// List<int> list = [1, 2, 3];
+ /// var map = Map<String, int>.fromIterable(list,
+ /// key: (item) => item.toString(),
+ /// value: (item) => item * item);
+ /// // map is {"1": 1, "2": 4, "3": 9}
+ /// ```
+ /// If no values are specified for [key] and [value],
+ /// the default is the identity function.
+ /// In that case, the iterable element must be assignable to the
+ /// key or value type of the created map.
+ ///
+ /// In the following example, the keys and corresponding values of `map`
+ /// are the `list` values directly:
+ /// ```dart
+ /// var map = Map<int, int>.fromIterable(list);
+ /// // map is {1: 1, 2: 2, 3: 3}
+ /// ```
+ /// The keys computed by the source [iterable] do not need to be unique.
+ /// The last occurrence of a key will overwrite
+ /// the value of any previous occurrence.
+ ///
+ /// The created map is a [LinkedHashMap].
+ /// A `LinkedHashMap` requires the keys to implement compatible
+ /// `operator==` and `hashCode`.
+ /// It iterates in key insertion order.
factory Map.fromIterable(Iterable iterable,
- {K key(element)?, V value(element)?}) = LinkedHashMap<K, V>.fromIterable;
+ {K key(dynamic element)?,
+ V value(dynamic element)?}) = LinkedHashMap<K, V>.fromIterable;
- /**
- * Creates a Map instance associating the given [keys] to [values].
- *
- * The created map is a [LinkedHashMap].
- * A `LinkedHashMap` requires the keys to implement compatible
- * `operator==` and `hashCode`, and it allows null as a key.
- * It iterates in key insertion order.
- *
- * This constructor iterates over [keys] and [values] and maps each element of
- * [keys] to the corresponding element of [values].
- *
- * List<String> letters = ['b', 'c'];
- * List<String> words = ['bad', 'cat'];
- * Map<String, String> map = new Map.fromIterables(letters, words);
- * map['b'] + map['c']; // badcat
- *
- * If [keys] contains the same object multiple times, the last occurrence
- * overwrites the previous value.
- *
- * The two [Iterable]s must have the same length.
- */
+ /// Creates a map associating the given [keys] to the given [values].
+ ///
+ /// The map construction iterates over [keys] and [values] simultaneously,
+ /// and adds an entry to the map for each pair of key and value.
+ /// ```dart
+ /// List<String> letters = ['b', 'c'];
+ /// List<String> words = ['bad', 'cat'];
+ /// var map = Map.fromIterables(letters, words);
+ /// // map is {"b": "bad", "c": "cat"}
+ /// ```
+ /// If [keys] contains the same object multiple times,
+ /// the value of the last occurrence overwrites any previous value.
+ ///
+ /// The two [Iterable]s must have the same length.
+ ///
+ /// The created map is a [LinkedHashMap].
+ /// A `LinkedHashMap` requires the keys to implement compatible
+ /// `operator==` and `hashCode`.
+ /// It iterates in key insertion order.
factory Map.fromIterables(Iterable<K> keys, Iterable<V> values) =
LinkedHashMap<K, V>.fromIterables;
- /**
- * Adapts [source] to be a `Map<K2, V2>`.
- *
- * Any time the set would produce a key or value that is not a [K2] or [V2],
- * the access will throw.
- *
- * Any time [K2] key or [V2] value is attempted added into the adapted map,
- * the store will throw unless the key is also an instance of [K] and
- * the value is also an instance of [V].
- *
- * If all accessed entries of [source] are have [K2] keys and [V2] values
- * and if all entries added to the returned map have [K] keys and [V]] values,
- * then the returned map can be used as a `Map<K2, V2>`.
- */
+ /// Adapts [source] to be a `Map<K2, V2>`.
+ ///
+ /// Any time the set would produce a key or value that is not a [K2] or [V2],
+ /// the access will throw.
+ ///
+ /// Any time [K2] key or [V2] value is attempted added into the adapted map,
+ /// the store will throw unless the key is also an instance of [K] and
+ /// the value is also an instance of [V].
+ ///
+ /// If all accessed entries of [source] are have [K2] keys and [V2] values
+ /// and if all entries added to the returned map have [K] keys and [V]] values,
+ /// then the returned map can be used as a `Map<K2, V2>`.
static Map<K2, V2> castFrom<K, V, K2, V2>(Map<K, V> source) =>
CastMap<K, V, K2, V2>(source);
- /**
- * Creates a new map and adds all entries.
- *
- * Returns a new `Map<K, V>` where all entries of [entries]
- * have been added in iteration order.
- *
- * If multiple [entries] have the same key,
- * later occurrences overwrite the earlier ones.
- */
+ /// Creates a new map and adds all entries.
+ ///
+ /// Returns a new `Map<K, V>` where all entries of [entries]
+ /// have been added in iteration order.
+ ///
+ /// If multiple [entries] have the same key,
+ /// later occurrences overwrite the value of the earlier ones.
+ ///
+ /// Equivalent to the map literal:
+ /// ```dart
+ /// <K, V>{for (var e in entries) e.key: e.value}
+ /// ```
factory Map.fromEntries(Iterable<MapEntry<K, V>> entries) =>
<K, V>{}..addEntries(entries);
- /**
- * Provides a view of this map as having [RK] keys and [RV] instances,
- * if necessary.
- *
- * If this map is already a `Map<RK, RV>`, it is returned unchanged.
- *
- * If this set contains only keys of type [RK] and values of type [RV],
- * all read operations will work correctly.
- * If any operation exposes a non-[RK] key or non-[RV] value,
- * the operation will throw instead.
- *
- * Entries added to the map must be valid for both a `Map<K, V>` and a
- * `Map<RK, RV>`.
- */
+ /// Provides a view of this map as having [RK] keys and [RV] instances,
+ /// if necessary.
+ ///
+ /// If this map is already a `Map<RK, RV>`, it is returned unchanged.
+ ///
+ /// If this set contains only keys of type [RK] and values of type [RV],
+ /// all read operations will work correctly.
+ /// If any operation exposes a non-[RK] key or non-[RV] value,
+ /// the operation will throw instead.
+ ///
+ /// Entries added to the map must be valid for both a `Map<K, V>` and a
+ /// `Map<RK, RV>`.
Map<RK, RV> cast<RK, RV>();
- /**
- * Returns true if this map contains the given [value].
- *
- * Returns true if any of the values in the map are equal to `value`
- * according to the `==` operator.
- */
+ /// Whether this map contains the given [value].
+ ///
+ /// Returns true if any of the values in the map are equal to `value`
+ /// according to the `==` operator.
bool containsValue(Object? value);
- /**
- * Returns true if this map contains the given [key].
- *
- * Returns true if any of the keys in the map are equal to `key`
- * according to the equality used by the map.
- */
+ /// Whether this map contains the given [key].
+ ///
+ /// Returns true if any of the keys in the map are equal to `key`
+ /// according to the equality used by the map.
bool containsKey(Object? key);
- /**
- * Returns the value for the given [key] or null if [key] is not in the map.
- *
- * Some maps allow keys to have `null` as a value.
- * For those maps, a lookup using this operator cannot distinguish between a
- * key not being in the map and the key having a `null` value.
- * Methods like [containsKey] or [putIfAbsent] can be used if the distinction
- * is important.
- */
+ /// The value for the given [key], or `null` if [key] is not in the map.
+ ///
+ /// Some maps allow `null` as a value.
+ /// For those maps, a lookup using this operator cannot distinguish between a
+ /// key not being in the map, and the key being there with a `null` value.
+ /// Methods like [containsKey] or [putIfAbsent] can be used if the distinction
+ /// is important.
V? operator [](Object? key);
- /**
- * Associates the [key] with the given [value].
- *
- * If the key was already in the map, its associated value is changed.
- * Otherwise the key/value pair is added to the map.
- */
+ /// Associates the [key] with the given [value].
+ ///
+ /// If the key was already in the map, its associated value is changed.
+ /// Otherwise the key/value pair is added to the map.
void operator []=(K key, V value);
- /**
- * The map entries of [this].
- */
+ /// The map entries of [this].
Iterable<MapEntry<K, V>> get entries;
- /**
- * Returns a new map where all entries of this map are transformed by
- * the given [f] function.
- */
- Map<K2, V2> map<K2, V2>(MapEntry<K2, V2> f(K key, V value));
+ /// Returns a new map where all entries of this map are transformed by
+ /// the given [convert] function.
+ Map<K2, V2> map<K2, V2>(MapEntry<K2, V2> convert(K key, V value));
- /**
- * Adds all key/value pairs of [newEntries] to this map.
- *
- * If a key of [newEntries] is already in this map,
- * the corresponding value is overwritten.
- *
- * The operation is equivalent to doing `this[entry.key] = entry.value`
- * for each [MapEntry] of the iterable.
- */
+ /// Adds all key/value pairs of [newEntries] to this map.
+ ///
+ /// If a key of [newEntries] is already in this map,
+ /// the corresponding value is overwritten.
+ ///
+ /// The operation is equivalent to doing `this[entry.key] = entry.value`
+ /// for each [MapEntry] of the iterable.
void addEntries(Iterable<MapEntry<K, V>> newEntries);
- /**
- * Updates the value for the provided [key].
- *
- * Returns the new value of the key.
- *
- * If the key is present, invokes [update] with the current value and stores
- * the new value in the map.
- *
- * If the key is not present and [ifAbsent] is provided, calls [ifAbsent]
- * and adds the key with the returned value to the map.
- *
- * It's an error if the key is not present and [ifAbsent] is not provided.
- */
+ /// Updates the value for the provided [key].
+ ///
+ /// Returns the new value associated with the key.
+ ///
+ /// If the key is present, invokes [update] with the current value and stores
+ /// the new value in the map.
+ ///
+ /// If the key is not present and [ifAbsent] is provided, calls [ifAbsent]
+ /// and adds the key with the returned value to the map.
+ ///
+ /// If the key is not present, [ifAbsent] must be provided.
V update(K key, V update(V value), {V ifAbsent()?});
- /**
- * Updates all values.
- *
- * Iterates over all entries in the map and updates them with the result
- * of invoking [update].
- */
+ /// Updates all values.
+ ///
+ /// Iterates over all entries in the map and updates them with the result
+ /// of invoking [update].
void updateAll(V update(K key, V value));
- /**
- * Removes all entries of this map that satisfy the given [predicate].
- */
- void removeWhere(bool predicate(K key, V value));
+ /// Removes all entries of this map that satisfy the given [test].
+ void removeWhere(bool test(K key, V value));
- /**
- * Look up the value of [key], or add a new value if it isn't there.
- *
- * Returns the value associated to [key], if there is one.
- * Otherwise calls [ifAbsent] to get a new value, associates [key] to
- * that value, and then returns the new value.
- *
- * Map<String, int> scores = {'Bob': 36};
- * for (var key in ['Bob', 'Rohan', 'Sophena']) {
- * scores.putIfAbsent(key, () => key.length);
- * }
- * scores['Bob']; // 36
- * scores['Rohan']; // 5
- * scores['Sophena']; // 7
- *
- * Calling [ifAbsent] must not add or remove keys from the map.
- */
+ /// Look up the value of [key], or add a new entry if it isn't there.
+ ///
+ /// Returns the value associated to [key], if there is one.
+ /// Otherwise calls [ifAbsent] to get a new value, associates [key] to
+ /// that value, and then returns the new value.
+ /// ```dart
+ /// Map<String, int> scores = {'Bob': 36};
+ /// for (var key in ['Bob', 'Rohan', 'Sophena']) {
+ /// scores.putIfAbsent(key, () => key.length);
+ /// }
+ /// scores['Bob']; // 36
+ /// scores['Rohan']; // 5
+ /// scores['Sophena']; // 7
+ /// ```
+ /// Calling [ifAbsent] must not add or remove keys from the map.
V putIfAbsent(K key, V ifAbsent());
- /**
- * Adds all key/value pairs of [other] to this map.
- *
- * If a key of [other] is already in this map, its value is overwritten.
- *
- * The operation is equivalent to doing `this[key] = value` for each key
- * and associated value in other. It iterates over [other], which must
- * therefore not change during the iteration.
- */
+ /// Adds all key/value pairs of [other] to this map.
+ ///
+ /// If a key of [other] is already in this map, its value is overwritten.
+ ///
+ /// The operation is equivalent to doing `this[key] = value` for each key
+ /// and associated value in other. It iterates over [other], which must
+ /// therefore not change during the iteration.
void addAll(Map<K, V> other);
- /**
- * Removes [key] and its associated value, if present, from the map.
- *
- * Returns the value associated with `key` before it was removed.
- * Returns `null` if `key` was not in the map.
- *
- * Note that values can be `null` and a returned `null` value doesn't
- * always mean that the key was absent.
- */
+ /// Removes [key] and its associated value, if present, from the map.
+ ///
+ /// Returns the value associated with `key` before it was removed.
+ /// Returns `null` if `key` was not in the map.
+ ///
+ /// Note that some maps allow `null` as a value,
+ /// so a returned `null` value doesn't always mean that the key was absent.
V? remove(Object? key);
- /**
- * Removes all pairs from the map.
- *
- * After this, the map is empty.
- */
+ /// Removes all entries from the map.
+ ///
+ /// After this, the map is empty.
void clear();
- /**
- * Applies [f] to each key/value pair of the map.
- *
- * Calling `f` must not add or remove keys from the map.
- */
- void forEach(void f(K key, V value));
+ /// Applies [action] to each key/value pair of the map.
+ ///
+ /// Calling `action` must not add or remove keys from the map.
+ void forEach(void action(K key, V value));
- /**
- * The keys of [this].
- *
- * The returned iterable has efficient `length` and `contains` operations,
- * based on [length] and [containsKey] of the map.
- *
- * The order of iteration is defined by the individual `Map` implementation,
- * but must be consistent between changes to the map.
- *
- * Modifying the map while iterating the keys
- * may break the iteration.
- */
+ /// The keys of [this].
+ ///
+ /// The returned iterable has efficient `length` and `contains` operations,
+ /// based on [length] and [containsKey] of the map.
+ ///
+ /// The order of iteration is defined by the individual `Map` implementation,
+ /// but must be consistent between changes to the map.
+ ///
+ /// Modifying the map while iterating the keys may break the iteration.
Iterable<K> get keys;
- /**
- * The values of [this].
- *
- * The values are iterated in the order of their corresponding keys.
- * This means that iterating [keys] and [values] in parallel will
- * provide matching pairs of keys and values.
- *
- * The returned iterable has an efficient `length` method based on the
- * [length] of the map. Its [Iterable.contains] method is based on
- * `==` comparison.
- *
- * Modifying the map while iterating the
- * values may break the iteration.
- */
+ /// The values of [this].
+ ///
+ /// The values are iterated in the order of their corresponding keys.
+ /// This means that iterating [keys] and [values] in parallel will
+ /// provide matching pairs of keys and values.
+ ///
+ /// The returned iterable has an efficient `length` method based on the
+ /// [length] of the map. Its [Iterable.contains] method is based on
+ /// `==` comparison.
+ ///
+ /// Modifying the map while iterating the values may break the iteration.
Iterable<V> get values;
- /**
- * The number of key/value pairs in the map.
- */
+ /// The number of key/value pairs in the map.
int get length;
- /**
- * Returns true if there is no key/value pair in the map.
- */
+ /// Whether there is no key/value pair in the map.
bool get isEmpty;
- /**
- * Returns true if there is at least one key/value pair in the map.
- */
+ /// Whether there is at least one key/value pair in the map.
bool get isNotEmpty;
}
-/**
- * A key/value pair representing an entry in a [Map].
- */
+/// A key/value pair representing an entry in a [Map].
class MapEntry<K, V> {
- /** The key of the entry. */
+ /// The key of the entry.
final K key;
- /** The value associated to [key] in the map. */
+ /// The value associated to [key] in the map.
final V value;
- /** Creates an entry with [key] and [value]. */
+ /// Creates an entry with [key] and [value].
const factory MapEntry(K key, V value) = MapEntry<K, V>._;
const MapEntry._(this.key, this.value);
diff --git a/sdk/lib/core/null.dart b/sdk/lib/core/null.dart
index f8588a1..eb7a006 100644
--- a/sdk/lib/core/null.dart
+++ b/sdk/lib/core/null.dart
@@ -4,13 +4,22 @@
part of dart.core;
-/**
- * The reserved word `null` denotes an object that is the sole instance of
- * this class.
- *
- * It is a compile-time error for a class to attempt to extend or implement
- * [Null].
- */
+/// The reserved word `null` denotes an object that is the sole instance of
+/// this class.
+///
+/// The `Null` class is the only class which does not implement `Object`.
+/// It is a compile-time error for a class to attempt to extend or implement
+/// [Null].
+///
+/// The language contains a number of specialized operators for working with
+/// `null` value. Examples:
+/// ```dart
+/// e1! // Throws if e1 is null.
+/// e2 ?? e3 // Same as e2, unless e2 is null, then use value of e3
+/// x ??= e4 // Same as x unless x is null, then same as `x = e4`.
+/// e5?.foo() // call `foo` on e5, unless e5 is null.
+/// [...? e6] // spreads e6 into the list literal, unless e6 is null.
+/// ```
@pragma("vm:entry-point")
class Null {
factory Null._uninstantiable() {
@@ -19,6 +28,6 @@
external int get hashCode;
- /** Returns the string `"null"`. */
+ /// Returns the string `"null"`.
String toString() => "null";
}
diff --git a/sdk/lib/core/num.dart b/sdk/lib/core/num.dart
index 55bb910..36c8fec 100644
--- a/sdk/lib/core/num.dart
+++ b/sdk/lib/core/num.dart
@@ -4,470 +4,482 @@
part of dart.core;
-/**
- * An integer or floating-point number.
- *
- * It is a compile-time error for any type other than [int] or [double]
- * to attempt to extend or implement num.
- */
+/// An integer or floating-point number.
+///
+/// It is a compile-time error for any type other than [int] or [double]
+/// to attempt to extend or implement `num`.
abstract class num implements Comparable<num> {
- /**
- * Test whether this value is numerically equal to `other`.
- *
- * If both operands are doubles, they are equal if they have the same
- * representation, except that:
- *
- * * zero and minus zero (0.0 and -0.0) are considered equal. They
- * both have the numerical value zero.
- * * NaN is not equal to anything, including NaN. If either operand is
- * NaN, the result is always false.
- *
- * If one operand is a double and the other is an int, they are equal if
- * the double has an integer value (finite with no fractional part) and
- * `identical(doubleValue.toInt(), intValue)` is true.
- *
- * If both operands are integers, they are equal if they have the same value.
- *
- * Returns false if `other` is not a [num].
- *
- * Notice that the behavior for NaN is non-reflexive. This means that
- * equality of double values is not a proper equality relation, as is
- * otherwise required of `operator==`. Using NaN in, e.g., a [HashSet]
- * will fail to work. The behavior is the standard IEEE-754 equality of
- * doubles.
- *
- * If you can avoid NaN values, the remaining doubles do have a proper
- * equality relation, and can be used safely.
- *
- * Use [compareTo] for a comparison that distinguishes zero and minus zero,
- * and that considers NaN values as equal.
- */
+ /// Test whether this value is numerically equal to `other`.
+ ///
+ /// If both operands are [double]s, they are equal if they have the same
+ /// representation, except that:
+ ///
+ /// * zero and minus zero (0.0 and -0.0) are considered equal. They
+ /// both have the numerical value zero.
+ /// * NaN is not equal to anything, including NaN. If either operand is
+ /// NaN, the result is always false.
+ ///
+ /// If one operand is a [double] and the other is an [int], they are equal if
+ /// the double has an integer value (finite with no fractional part) and
+ /// the numbers have the same numerical value.
+ ///
+ /// If both operands are integers, they are equal if they have the same value.
+ ///
+ /// Returns false if [other] is not a [num].
+ ///
+ /// Notice that the behavior for NaN is non-reflexive. This means that
+ /// equality of double values is not a proper equality relation, as is
+ /// otherwise required of `operator==`. Using NaN in, e.g., a [HashSet]
+ /// will fail to work. The behavior is the standard IEEE-754 equality of
+ /// doubles.
+ ///
+ /// If you can avoid NaN values, the remaining doubles do have a proper
+ /// equality relation, and can be used safely.
+ ///
+ /// Use [compareTo] for a comparison that distinguishes zero and minus zero,
+ /// and that considers NaN values as equal.
bool operator ==(Object other);
- /**
- * Returns a hash code for a numerical value.
- *
- * The hash code is compatible with equality. It returns the same value
- * for an [int] and a [double] with the same numerical value, and therefore
- * the same value for the doubles zero and minus zero.
- *
- * No guarantees are made about the hash code of NaN values.
- */
+ /// Returns a hash code for a numerical value.
+ ///
+ /// The hash code is compatible with equality. It returns the same value
+ /// for an [int] and a [double] with the same numerical value, and therefore
+ /// the same value for the doubles zero and minus zero.
+ ///
+ /// No guarantees are made about the hash code of NaN values.
int get hashCode;
- /**
- * Compares this to `other`.
- *
- * Returns a negative number if `this` is less than `other`, zero if they are
- * equal, and a positive number if `this` is greater than `other`.
- *
- * The ordering represented by this method is a total ordering of [num]
- * values. All distinct doubles are non-equal, as are all distinct integers,
- * but integers are equal to doubles if they have the same numerical
- * value.
- *
- * For doubles, the `compareTo` operation is different from the partial
- * ordering given by [operator==], [operator<] and [operator>]. For example,
- * IEEE doubles impose that `0.0 == -0.0` and all comparison operations on
- * NaN return false.
- *
- * This function imposes a complete ordering for doubles. When using
- * `compareTo` the following properties hold:
- *
- * - All NaN values are considered equal, and greater than any numeric value.
- * - -0.0 is less than 0.0 (and the integer 0), but greater than any non-zero
- * negative value.
- * - Negative infinity is less than all other values and positive infinity is
- * greater than all non-NaN values.
- * - All other values are compared using their numeric value.
- *
- * Examples:
- * ```
- * print(1.compareTo(2)); // => -1
- * print(2.compareTo(1)); // => 1
- * print(1.compareTo(1)); // => 0
- *
- * // The following comparisons yield different results than the
- * // corresponding comparison operators.
- * print((-0.0).compareTo(0.0)); // => -1
- * print(double.nan.compareTo(double.nan)); // => 0
- * print(double.infinity.compareTo(double.nan)); // => -1
- *
- * // -0.0, and NaN comparison operators have rules imposed by the IEEE
- * // standard.
- * print(-0.0 == 0.0); // => true
- * print(double.nan == double.nan); // => false
- * print(double.infinity < double.nan); // => false
- * print(double.nan < double.infinity); // => false
- * print(double.nan == double.infinity); // => false
- * ```
- */
+ /// Compares this to `other`.
+ ///
+ /// Returns a negative number if `this` is less than `other`, zero if they are
+ /// equal, and a positive number if `this` is greater than `other`.
+ ///
+ /// The ordering represented by this method is a total ordering of [num]
+ /// values. All distinct doubles are non-equal, as are all distinct integers,
+ /// but integers are equal to doubles if they have the same numerical
+ /// value.
+ ///
+ /// For doubles, the `compareTo` operation is different from the partial
+ /// ordering given by [operator==], [operator<] and [operator>]. For example,
+ /// IEEE doubles impose that `0.0 == -0.0` and all comparison operations on
+ /// NaN return false.
+ ///
+ /// This function imposes a complete ordering for doubles. When using
+ /// `compareTo` the following properties hold:
+ ///
+ /// - All NaN values are considered equal, and greater than any numeric value.
+ /// - -0.0 is less than 0.0 (and the integer 0), but greater than any non-zero
+ /// negative value.
+ /// - Negative infinity is less than all other values and positive infinity is
+ /// greater than all non-NaN values.
+ /// - All other values are compared using their numeric value.
+ ///
+ /// Examples:
+ /// ```
+ /// print(1.compareTo(2)); // => -1
+ /// print(2.compareTo(1)); // => 1
+ /// print(1.compareTo(1)); // => 0
+ ///
+ /// // The following comparisons yield different results than the
+ /// // corresponding comparison operators.
+ /// print((-0.0).compareTo(0.0)); // => -1
+ /// print(double.nan.compareTo(double.nan)); // => 0
+ /// print(double.infinity.compareTo(double.nan)); // => -1
+ ///
+ /// // -0.0, and NaN comparison operators have rules imposed by the IEEE
+ /// // standard.
+ /// print(-0.0 == 0.0); // => true
+ /// print(double.nan == double.nan); // => false
+ /// print(double.infinity < double.nan); // => false
+ /// print(double.nan < double.infinity); // => false
+ /// print(double.nan == double.infinity); // => false
+ /// ```
int compareTo(num other);
- /** Addition operator. */
+ /// Adds [other] to this number.
+ ///
+ /// The result is an [int], as described by [int.+],
+ /// if both this number and [other] is an integer,
+ /// otherwise the result is a [double].
num operator +(num other);
- /** Subtraction operator. */
+ /// Subtracts [other] from this number.
+ ///
+ /// The result is an [int], as described by [int.-],
+ /// if both this number and [other] is an integer,
+ /// otherwise the result is a [double].
num operator -(num other);
- /** Multiplication operator. */
+ /// Multiplies this number by [other].
+ ///
+ /// The result is an [int], as described by [int.*],
+ /// if both this number and [other] is an integer,
+ /// otherwise the result is a [double].
num operator *(num other);
- /**
- * Euclidean modulo operator.
- *
- * Returns the remainder of the Euclidean division. The Euclidean division of
- * two integers `a` and `b` yields two integers `q` and `r` such that
- * `a == b * q + r` and `0 <= r < b.abs()`.
- *
- * The Euclidean division is only defined for integers, but can be easily
- * extended to work with doubles. In that case `r` may have a non-integer
- * value, but it still verifies `0 <= r < |b|`.
- *
- * The sign of the returned value `r` is always positive.
- *
- * See [remainder] for the remainder of the truncating division.
- */
+ /// Euclidean modulo of this number by [other].
+ ///
+ /// Returns the remainder of the Euclidean division.
+ /// The Euclidean division of two integers `a` and `b`
+ /// yields two integers `q` and `r` such that
+ /// `a == b * q + r` and `0 <= r < b.abs()`.
+ ///
+ /// The Euclidean division is only defined for integers, but can be easily
+ /// extended to work with doubles. In that case `q` is stil an integer,
+ /// but `r` may have a non-integer value that still satisfies `0 <= r < |b|`.
+ ///
+ /// The sign of the returned value `r` is always positive.
+ ///
+ /// See [remainder] for the remainder of the truncating division.
+ ///
+ /// The result is an [int], as described by [int.%],
+ /// if both this number and [other] is an integer,
+ /// otherwise the result is a [double].
num operator %(num other);
- /** Division operator. */
+ /// Divides this number by [other].
double operator /(num other);
- /**
- * Truncating division operator.
- *
- * If either operand is a [double] then the result of the truncating division
- * `a ~/ b` is equivalent to `(a / b).truncate().toInt()`.
- *
- * If both operands are [int]s then `a ~/ b` performs the truncating
- * integer division.
- */
+ /// Truncating division operator.
+ ///
+ /// If either operand is a [double] then the result of the truncating division
+ /// `a ~/ b` is equivalent to `(a / b).truncate().toInt()`.
+ ///
+ /// If both operands are [int]s then `a ~/ b` performs the truncating
+ /// integer division.
int operator ~/(num other);
- /** Negate operator. */
+ /// The negation of this value.
+ ///
+ /// The negation of a number is a number of the same kind
+ /// (`int` or `double`) representing the negation of the
+ /// numbers numerical value (the result of subtracting the
+ /// number from zero), if that value *exists*.
+ ///
+ /// Negating a double gives a number with same magnitude
+ /// as the original value (`number.abs() == (-number).abs()`),
+ /// and the opposite sign (`-(number.sign) == (-number).sign`).
+ ///
+ /// Negating an integer, `-number`, is equivalent to subtracting
+ /// it from zero, `0 - number`.
+ ///
+ /// (Both properties generally also hold for the other type,
+ /// but with a few edge case exceptions).
num operator -();
- /**
- * Returns the remainder of the truncating division of `this` by [other].
- *
- * The result `r` of this operation satisfies:
- * `this == (this ~/ other) * other + r`.
- * As a consequence the remainder `r` has the same sign as the divider `this`.
- */
+ /// The remainder of the truncating division of `this` by [other].
+ ///
+ /// The result `r` of this operation satisfies:
+ /// `this == (this ~/ other) * other + r`.
+ /// As a consequence the remainder `r` has the same sign as the divider `this`.
+ ///
+ /// The result is an [int], as described by [int.remainder],
+ /// if both this number and [other] is an integer,
+ /// otherwise the result is a [double].
num remainder(num other);
- /** Relational less than operator. */
+ /// Whether [other] is numerically smaller than this number.
+ ///
+ /// If either operand is the [double] NaN, the result is always false.
bool operator <(num other);
- /** Relational less than or equal operator. */
+ /// Whether [other] is numerically smaller than or equal to this number.
+ ///
+ /// If either operand is the [double] NaN, the result is always false.
bool operator <=(num other);
- /** Relational greater than operator. */
+ /// Whether [other] is numerically greater than this number.
+ ///
+ /// If either operand is the [double] NaN, the result is always false.
bool operator >(num other);
- /** Relational greater than or equal operator. */
+ /// Whether [other] is numerically greater than or equal to this number.
+ ///
+ /// If either operand is the [double] NaN, the result is always false.
bool operator >=(num other);
- /** True if the number is the double Not-a-Number value; otherwise, false. */
+ /// Whether the number is the double Not-a-Number value.
bool get isNaN;
- /**
- * True if the number is negative; otherwise, false.
- *
- * Negative numbers are those less than zero, and the double `-0.0`.
- */
+ /// Whether if the number is negative.
+ ///
+ /// Negative numbers are those less than zero, and the double `-0.0`.
bool get isNegative;
- /**
- * True if the number is positive infinity or negative infinity; otherwise,
- * false.
- */
+ /// Whether the number is positive infinity or negative infinity.
bool get isInfinite;
- /**
- * True if the number is finite; otherwise, false.
- *
- * The only non-finite numbers are NaN, positive infinity, and
- * negative infinity.
- */
+ /// Whether the number is finite.
+ ///
+ /// The only non-finite numbers are NaN, positive infinity, and
+ /// negative infinity. All integers are finite.
bool get isFinite;
- /** Returns the absolute value of this [num]. */
+ /// The absolute value of this number.
+ ///
+ /// The absolute value is the value itself, if the value is non-negative,
+ /// and `-value` if the value is negative.
num abs();
- /**
- * Returns minus one, zero or plus one depending on the sign and
- * numerical value of the number.
- *
- * Returns minus one if the number is less than zero,
- * plus one if the number is greater than zero,
- * and zero if the number is equal to zero.
- *
- * Returns NaN if the number is the double NaN value.
- *
- * Returns a number of the same type as this number.
- * For doubles, `-0.0.sign == -0.0`.
-
- * The result satisfies:
- *
- * n == n.sign * n.abs()
- *
- * for all numbers `n` (except NaN, because NaN isn't `==` to itself).
- */
+ /// Negative one, zero or positive one depending on the sign and
+ /// numerical value of the number.
+ ///
+ /// Returns minus one if the number is less than zero,
+ /// plus one if the number is greater than zero,
+ /// and zero if the number is equal to zero.
+ ///
+ /// Returns NaN if the number is the [double] NaN value.
+ ///
+ /// Returns a number of the same type as this number.
+ /// For doubles, `-0.0.sign == -0.0`.
+ ///
+ /// The result satisfies:
+ /// ```dart
+ /// n == n.sign * n.abs()
+ /// ```
+ /// for all numbers `n` (except NaN, because NaN isn't `==` to itself).
num get sign;
- /**
- * Returns the integer closest to `this`.
- *
- * Rounds away from zero when there is no closest integer:
- * `(3.5).round() == 4` and `(-3.5).round() == -4`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// The integer closest to this number.
+ ///
+ /// Rounds away from zero when there is no closest integer:
+ /// `(3.5).round() == 4` and `(-3.5).round() == -4`.
+ ///
+ /// The number must be finite (see [isFinite]).
+ ///
+ /// If the value is greater than the highest representable positive integer,
+ /// the result is that highest positive integer.
+ /// If the value is smaller than the highest representable negative integer,
+ /// the result is that highest negative integer.
int round();
- /**
- * Returns the greatest integer no greater than `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// The greatest integer no greater than this number.
+ ///
+ /// Rounds fractional values towards negative infinity.
+ ///
+ /// The number must be finite (see [isFinite]).
+ ///
+ /// If the value is greater than the highest representable positive integer,
+ /// the result is that highest positive integer.
+ /// If the value is smaller than the highest representable negative integer,
+ /// the result is that highest negative integer.
int floor();
- /**
- * Returns the least integer no smaller than `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// The least integer no smaller than `this`.
+ ///
+ /// Rounds fractional values towards positive infinitiy.
+ ///
+ /// The number must be finite (see [isFinite]).
+ ///
+ /// If the value is greater than the highest representable positive integer,
+ /// the result is that highest positive integer.
+ /// If the value is smaller than the highest representable negative integer,
+ /// the result is that highest negative integer.
int ceil();
- /**
- * Returns the integer obtained by discarding any fractional
- * digits from `this`.
- *
- * If `this` is not finite (`NaN` or infinity), throws an [UnsupportedError].
- */
+ /// The integer obtained by discarding any fractional digits from `this`.
+ ///
+ /// Rounds fractional values towards zero.
+ ///
+ /// The number must be finite (see [isFinite]).
+ ///
+ /// If the value is greater than the highest representable positive integer,
+ /// the result is that highest positive integer.
+ /// If the value is smaller than the highest representable negative integer,
+ /// the result is that highest negative integer.
int truncate();
- /**
- * Returns the double integer value closest to `this`.
- *
- * Rounds away from zero when there is no closest integer:
- * `(3.5).roundToDouble() == 4` and `(-3.5).roundToDouble() == -4`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is a
- * non-finite double value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`,
- * and `-0.0` is therefore considered closer to negative numbers than `0.0`.
- * This means that for a value, `d` in the range `-0.5 < d < 0.0`,
- * the result is `-0.0`.
- *
- * The result is always a double.
- * If this is a numerically large integer, the result may be an infinite
- * double.
- */
+ /// The double integer value closest to this value.
+ ///
+ /// Rounds away from zero when there is no closest integer:
+ /// `(3.5).roundToDouble() == 4` and `(-3.5).roundToDouble() == -4`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is a
+ /// non-finite double value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`,
+ /// and `-0.0` is therefore considered closer to negative numbers than `0.0`.
+ /// This means that for a value, `d` in the range `-0.5 < d < 0.0`,
+ /// the result is `-0.0`.
double roundToDouble();
- /**
- * Returns the greatest double integer value no greater than `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is a
- * non-finite double value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `0.0 < d < 1.0` will return `0.0`.
- *
- * The result is always a double.
- * If this is a numerically large integer, the result may be an infinite
- * double.
- */
+ /// Returns the greatest double integer value no greater than `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is a
+ /// non-finite double value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `0.0 < d < 1.0` will return `0.0`.
double floorToDouble();
- /**
- * Returns the least double integer value no smaller than `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is a
- * non-finite double value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`.
- *
- * The result is always a double.
- * If this is a numerically large integer, the result may be an infinite
- * double.
- */
+ /// Returns the least double integer value no smaller than `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is a
+ /// non-finite double value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`.
double ceilToDouble();
- /**
- * Returns the double integer value obtained by discarding any fractional
- * digits from the double value of `this`.
- *
- * If this is already an integer valued double, including `-0.0`, or it is a
- * non-finite double value, the value is returned unmodified.
- *
- * For the purpose of rounding, `-0.0` is considered to be below `0.0`.
- * A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`, and
- * in the range `0.0 < d < 1.0` it will return 0.0.
- *
- * The result is always a double.
- * If this is a numerically large integer, the result may be an infinite
- * double.
- */
+ /// Returns the double integer value obtained by discarding any fractional
+ /// digits from the double value of `this`.
+ ///
+ /// If this is already an integer valued double, including `-0.0`, or it is a
+ /// non-finite double value, the value is returned unmodified.
+ ///
+ /// For the purpose of rounding, `-0.0` is considered to be below `0.0`.
+ /// A number `d` in the range `-1.0 < d < 0.0` will return `-0.0`, and
+ /// in the range `0.0 < d < 1.0` it will return 0.0.
double truncateToDouble();
- /**
- * Returns this [num] clamped to be in the range [lowerLimit]-[upperLimit].
- *
- * The comparison is done using [compareTo] and therefore takes `-0.0` into
- * account. This also implies that [double.nan] is treated as the maximal
- * double value.
- *
- * The arguments [lowerLimit] and [upperLimit] must form a valid range where
- * `lowerLimit.compareTo(upperLimit) <= 0`.
- */
+ /// Returns this [num] clamped to be in the range [lowerLimit]-[upperLimit].
+ ///
+ /// The comparison is done using [compareTo] and therefore takes `-0.0` into
+ /// account. This also implies that [double.nan] is treated as the maximal
+ /// double value.
+ ///
+ /// The arguments [lowerLimit] and [upperLimit] must form a valid range where
+ /// `lowerLimit.compareTo(upperLimit) <= 0`.
num clamp(num lowerLimit, num upperLimit);
- /** Truncates this [num] to an integer and returns the result as an [int]. */
+ /// Truncates this [num] to an integer and returns the result as an [int].
+ ///
+ /// Equivalent to [truncate].
int toInt();
- /**
- * Return this [num] as a [double].
- *
- * If the number is not representable as a [double], an
- * approximation is returned. For numerically large integers, the
- * approximation may be infinite.
- */
+ /// This number as a [double].
+ ///
+ /// If an integer number is not precisely representable as a [double],
+ /// an approximation is returned.
double toDouble();
- /**
- * Returns a decimal-point string-representation of `this`.
- *
- * Converts `this` to a [double] before computing the string representation.
- *
- * If the absolute value of `this` is greater or equal to `10^21` then this
- * methods returns an exponential representation computed by
- * `this.toStringAsExponential()`. Otherwise the result
- * is the closest string representation with exactly [fractionDigits] digits
- * after the decimal point. If [fractionDigits] equals 0 then the decimal
- * point is omitted.
- *
- * The parameter [fractionDigits] must be an integer satisfying:
- * `0 <= fractionDigits <= 20`.
- *
- * Examples:
- *
- * 1.toStringAsFixed(3); // 1.000
- * (4321.12345678).toStringAsFixed(3); // 4321.123
- * (4321.12345678).toStringAsFixed(5); // 4321.12346
- * 123456789012345.toStringAsFixed(3); // 123456789012345.000
- * 10000000000000000.toStringAsFixed(4); // 10000000000000000.0000
- * 5.25.toStringAsFixed(0); // 5
- */
+ /// A decimal-point string-representation of this number.
+ ///
+ /// Converts this number to a [double]
+ /// before computing the string representation,
+ /// as by [toDouble].
+ ///
+ /// If the absolute value of `this` is greater then or equal to `10^21` then
+ /// this methods returns an exponential representation computed by
+ /// `this.toStringAsExponential()`. Otherwise the result
+ /// is the closest string representation with exactly [fractionDigits] digits
+ /// after the decimal point. If [fractionDigits] equals 0 then the decimal
+ /// point is omitted.
+ ///
+ /// The parameter [fractionDigits] must be an integer satisfying:
+ /// `0 <= fractionDigits <= 20`.
+ ///
+ /// Examples:
+ /// ```dart
+ /// 1.toStringAsFixed(3); // 1.000
+ /// (4321.12345678).toStringAsFixed(3); // 4321.123
+ /// (4321.12345678).toStringAsFixed(5); // 4321.12346
+ /// 123456789012345.toStringAsFixed(3); // 123456789012345.000
+ /// 10000000000000000.toStringAsFixed(4); // 10000000000000000.0000
+ /// 5.25.toStringAsFixed(0); // 5
+ /// ```
String toStringAsFixed(int fractionDigits);
- /**
- * Returns an exponential string-representation of `this`.
- *
- * Converts `this` to a [double] before computing the string representation.
- *
- * If [fractionDigits] is given then it must be an integer satisfying:
- * `0 <= fractionDigits <= 20`. In this case the string contains exactly
- * [fractionDigits] after the decimal point. Otherwise, without the parameter,
- * the returned string uses the shortest number of digits that accurately
- * represent [this].
- *
- * If [fractionDigits] equals 0 then the decimal point is omitted.
- * Examples:
- *
- * 1.toStringAsExponential(); // 1e+0
- * 1.toStringAsExponential(3); // 1.000e+0
- * 123456.toStringAsExponential(); // 1.23456e+5
- * 123456.toStringAsExponential(3); // 1.235e+5
- * 123.toStringAsExponential(0); // 1e+2
- */
+ /// An exponential string-representation of this number.
+ ///
+ /// Converts this number to a [double]
+ /// before computing the string representation.
+ ///
+ /// If [fractionDigits] is given then it must be an integer satisfying:
+ /// `0 <= fractionDigits <= 20`. In this case the string contains exactly
+ /// [fractionDigits] after the decimal point. Otherwise, without the parameter,
+ /// the returned string uses the shortest number of digits that accurately
+ /// represent this number.
+ ///
+ /// If [fractionDigits] equals 0 then the decimal point is omitted.
+ /// Examples:
+ /// ```dart
+ /// 1.toStringAsExponential(); // 1e+0
+ /// 1.toStringAsExponential(3); // 1.000e+0
+ /// 123456.toStringAsExponential(); // 1.23456e+5
+ /// 123456.toStringAsExponential(3); // 1.235e+5
+ /// 123.toStringAsExponential(0); // 1e+2
+ /// ```
String toStringAsExponential([int? fractionDigits]);
- /**
- * Converts `this` to a double and returns a string representation with
- * exactly [precision] significant digits.
- *
- * The parameter [precision] must be an integer satisfying:
- * `1 <= precision <= 21`.
- *
- * Examples:
- *
- * 1.toStringAsPrecision(2); // 1.0
- * 1e15.toStringAsPrecision(3); // 1.00e+15
- * 1234567.toStringAsPrecision(3); // 1.23e+6
- * 1234567.toStringAsPrecision(9); // 1234567.00
- * 12345678901234567890.toStringAsPrecision(20); // 12345678901234567168
- * 12345678901234567890.toStringAsPrecision(14); // 1.2345678901235e+19
- * 0.00000012345.toStringAsPrecision(15); // 1.23450000000000e-7
- * 0.0000012345.toStringAsPrecision(15); // 0.00000123450000000000
- */
+ /// A string representation with [precision] significant digits.
+ ///
+ /// Converts this number to a [double]
+ /// and returns a string representation of that value
+ /// with exactly [precision] significant digits.
+ ///
+ /// The parameter [precision] must be an integer satisfying:
+ /// `1 <= precision <= 21`.
+ ///
+ /// Examples:
+ /// ```dart
+ /// 1.toStringAsPrecision(2); // 1.0
+ /// 1e15.toStringAsPrecision(3); // 1.00e+15
+ /// 1234567.toStringAsPrecision(3); // 1.23e+6
+ /// 1234567.toStringAsPrecision(9); // 1234567.00
+ /// 12345678901234567890.toStringAsPrecision(20); // 12345678901234567168
+ /// 12345678901234567890.toStringAsPrecision(14); // 1.2345678901235e+19
+ /// 0.00000012345.toStringAsPrecision(15); // 1.23450000000000e-7
+ /// 0.0000012345.toStringAsPrecision(15); // 0.00000123450000000000
+ /// ```
String toStringAsPrecision(int precision);
- /**
- * Returns the shortest string that correctly represent the input number.
- *
- * All [double]s in the range `10^-6` (inclusive) to `10^21` (exclusive)
- * are converted to their decimal representation with at least one digit
- * after the decimal point. For all other doubles,
- * except for special values like `NaN` or `Infinity`, this method returns an
- * exponential representation (see [toStringAsExponential]).
- *
- * Returns `"NaN"` for [double.nan], `"Infinity"` for [double.infinity], and
- * `"-Infinity"` for [double.negativeInfinity].
- *
- * An [int] is converted to a decimal representation with no decimal point.
- *
- * Examples:
- *
- * (0.000001).toString(); // "0.000001"
- * (0.0000001).toString(); // "1e-7"
- * (111111111111111111111.0).toString(); // "111111111111111110000.0"
- * (100000000000000000000.0).toString(); // "100000000000000000000.0"
- * (1000000000000000000000.0).toString(); // "1e+21"
- * (1111111111111111111111.0).toString(); // "1.1111111111111111e+21"
- * 1.toString(); // "1"
- * 111111111111111111111.toString(); // "111111111111111110000"
- * 100000000000000000000.toString(); // "100000000000000000000"
- * 1000000000000000000000.toString(); // "1000000000000000000000"
- * 1111111111111111111111.toString(); // "1111111111111111111111"
- * 1.234e5.toString(); // 123400
- * 1234.5e6.toString(); // 1234500000
- * 12.345e67.toString(); // 1.2345e+68
- *
- * Note: the conversion may round the output if the returned string
- * is accurate enough to uniquely identify the input-number.
- * For example the most precise representation of the [double] `9e59` equals
- * `"899999999999999918767229449717619953810131273674690656206848"`, but
- * this method returns the shorter (but still uniquely identifying) `"9e59"`.
- *
- */
+ /// The shortest string that correctly represent this number number.
+ ///
+ /// All [double]s in the range `10^-6` (inclusive) to `10^21` (exclusive)
+ /// are converted to their decimal representation with at least one digit
+ /// after the decimal point. For all other doubles,
+ /// except for special values like `NaN` or `Infinity`, this method returns an
+ /// exponential representation (see [toStringAsExponential]).
+ ///
+ /// Returns `"NaN"` for [double.nan], `"Infinity"` for [double.infinity], and
+ /// `"-Infinity"` for [double.negativeInfinity].
+ ///
+ /// An [int] is converted to a decimal representation with no decimal point.
+ ///
+ /// Examples:
+ /// ```dart
+ /// (0.000001).toString(); // "0.000001"
+ /// (0.0000001).toString(); // "1e-7"
+ /// (111111111111111111111.0).toString(); // "111111111111111110000.0"
+ /// (100000000000000000000.0).toString(); // "100000000000000000000.0"
+ /// (1000000000000000000000.0).toString(); // "1e+21"
+ /// (1111111111111111111111.0).toString(); // "1.1111111111111111e+21"
+ /// 1.toString(); // "1"
+ /// 111111111111111111111.toString(); // "111111111111111110000"
+ /// 100000000000000000000.toString(); // "100000000000000000000"
+ /// 1000000000000000000000.toString(); // "1000000000000000000000"
+ /// 1111111111111111111111.toString(); // "1111111111111111111111"
+ /// 1.234e5.toString(); // 123400
+ /// 1234.5e6.toString(); // 1234500000
+ /// 12.345e67.toString(); // 1.2345e+68
+ /// ```
+ /// Note: the conversion may round the output if the returned string
+ /// is accurate enough to uniquely identify the input-number.
+ /// For example the most precise representation of the [double] `9e59` equals
+ /// `"899999999999999918767229449717619953810131273674690656206848"`, but
+ /// this method returns the shorter (but still uniquely identifying) `"9e59"`.
String toString();
- /**
- * Parses a string containing a number literal into a number.
- *
- * The method first tries to read the [input] as integer (similar to
- * [int.parse] without a radix).
- * If that fails, it tries to parse the [input] as a double (similar to
- * [double.parse]).
- * If that fails, too, it invokes [onError] with [input], and the result
- * of that invocation becomes the result of calling `parse`.
- *
- * If no [onError] is supplied, it defaults to a function that throws a
- * [FormatException].
- *
- * For any number `n`, this function satisfies
- * `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double`
- * with a payload).
- *
- * The [onError] parameter is deprecated and will be removed.
- * Instead of `num.parse(string, (string) { ... })`,
- * you should use `num.tryParse(string) ?? (...)`.
- */
+ /// Parses a string containing a number literal into a number.
+ ///
+ /// The method first tries to read the [input] as integer (similar to
+ /// [int.parse] without a radix).
+ /// If that fails, it tries to parse the [input] as a double (similar to
+ /// [double.parse]).
+ /// If that fails, too, it invokes [onError] with [input], and the result
+ /// of that invocation becomes the result of calling `parse`.
+ ///
+ /// If no [onError] is supplied, it defaults to a function that throws a
+ /// [FormatException].
+ ///
+ /// For any number `n`, this function satisfies
+ /// `identical(n, num.parse(n.toString()))` (except when `n` is a NaN `double`
+ /// with a payload).
+ ///
+ /// The [onError] parameter is deprecated and will be removed.
+ /// Instead of `num.parse(string, (string) { ... })`,
+ /// you should use `num.tryParse(string) ?? (...)`.
static num parse(String input, [@deprecated num onError(String input)?]) {
num? result = tryParse(input);
if (result != null) return result;
@@ -475,12 +487,10 @@
return onError(input);
}
- /**
- * Parses a string containing a number literal into a number.
- *
- * Like [parse] except that this function returns `null` for invalid inputs
- * instead of throwing.
- */
+ /// Parses a string containing a number literal into a number.
+ ///
+ /// Like [parse] except that this function returns `null` for invalid inputs
+ /// instead of throwing.
static num? tryParse(String input) {
String source = input.trim();
// TODO(lrn): Optimize to detect format and result type in one check.
diff --git a/sdk/lib/core/object.dart b/sdk/lib/core/object.dart
index b55d80d..008f969 100644
--- a/sdk/lib/core/object.dart
+++ b/sdk/lib/core/object.dart
@@ -4,113 +4,146 @@
part of dart.core;
-/**
- * The base class for all Dart objects.
- *
- * Because Object is the root of the Dart class hierarchy,
- * every other Dart class is a subclass of Object.
- *
- * When you define a class, you should override [toString]
- * to return a string describing an instance of that class.
- * You might also need to define [hashCode] and [operator ==], as described in the
- * [Implementing map
- * keys](https://dart.dev/guides/libraries/library-tour#implementing-map-keys)
- * section of the [library
- * tour](https://dart.dev/guides/libraries/library-tour).
- */
+/// The base class for all Dart objects exception `null`.
+///
+/// Because `Object` is a root of the non-nullable Dart class hierarchy,
+/// every other non-`Null` Dart class is a subclass of `Object`.
+///
+/// When you define a class, you should consider overriding [toString]
+/// to return a string describing an instance of that class.
+/// You might also need to define [hashCode] and [operator ==], as described in the
+/// [Implementing map keys](https://dart.dev/guides/libraries/library-tour#implementing-map-keys)
+/// section of the [library tour](https://dart.dev/guides/libraries/library-tour).
@pragma("vm:entry-point")
class Object {
- /**
- * Creates a new [Object] instance.
- *
- * [Object] instances have no meaningful state, and are only useful
- * through their identity. An [Object] instance is equal to itself
- * only.
- */
+ /// Creates a new [Object] instance.
+ ///
+ /// [Object] instances have no meaningful state, and are only useful
+ /// through their identity. An [Object] instance is equal to itself
+ /// only.
@pragma("vm:recognized", "other")
const Object();
- /**
- * The equality operator.
- *
- * The default behavior for all [Object]s is to return true if and
- * only if `this` and [other] are the same object.
- *
- * Override this method to specify a different equality relation on
- * a class. The overriding method must still be an equivalence relation.
- * That is, it must be:
- *
- * * Total: It must return a boolean for all arguments. It should never throw
- * or return `null`.
- *
- * * Reflexive: For all objects `o`, `o == o` must be true.
- *
- * * Symmetric: For all objects `o1` and `o2`, `o1 == o2` and `o2 == o1` must
- * either both be true, or both be false.
- *
- * * Transitive: For all objects `o1`, `o2`, and `o3`, if `o1 == o2` and
- * `o2 == o3` are true, then `o1 == o3` must be true.
- *
- * The method should also be consistent over time,
- * so whether two objects are equal should only change
- * if at least one of the objects was modified.
- *
- * If a subclass overrides the equality operator it should override
- * the [hashCode] method as well to maintain consistency.
- */
+ /// The equality operator.
+ ///
+ /// The default behavior for all [Object]s is to return true if and
+ /// only if this object and [other] are the same object.
+ ///
+ /// Override this method to specify a different equality relation on
+ /// a class. The overriding method must still be an equivalence relation.
+ /// That is, it must be:
+ ///
+ /// * Total: It must return a boolean for all arguments. It should never throw.
+ ///
+ /// * Reflexive: For all objects `o`, `o == o` must be true.
+ ///
+ /// * Symmetric: For all objects `o1` and `o2`, `o1 == o2` and `o2 == o1` must
+ /// either both be true, or both be false.
+ ///
+ /// * Transitive: For all objects `o1`, `o2`, and `o3`, if `o1 == o2` and
+ /// `o2 == o3` are true, then `o1 == o3` must be true.
+ ///
+ /// The method should also be consistent over time,
+ /// so whether two objects are equal should only change
+ /// if at least one of the objects was modified.
+ ///
+ /// If a subclass overrides the equality operator, it should override
+ /// the [hashCode] method as well to maintain consistency.
external bool operator ==(Object other);
- /**
- * The hash code for this object.
- *
- * A hash code is a single integer which represents the state of the object
- * that affects [operator ==] comparisons.
- *
- * All objects have hash codes.
- * The default hash code represents only the identity of the object,
- * the same way as the default [operator ==] implementation only considers objects
- * equal if they are identical (see [identityHashCode]).
- *
- * If [operator ==] is overridden to use the object state instead,
- * the hash code must also be changed to represent that state.
- *
- * Hash codes must be the same for objects that are equal to each other
- * according to [operator ==].
- * The hash code of an object should only change if the object changes
- * in a way that affects equality.
- * There are no further requirements for the hash codes.
- * They need not be consistent between executions of the same program
- * and there are no distribution guarantees.
- *
- * Objects that are not equal are allowed to have the same hash code,
- * it is even technically allowed that all instances have the same hash code,
- * but if clashes happen too often, it may reduce the efficiency of hash-based
- * data structures like [HashSet] or [HashMap].
- *
- * If a subclass overrides [hashCode], it should override the
- * [operator ==] operator as well to maintain consistency.
- */
+ /// The hash code for this object.
+ ///
+ /// A hash code is a single integer which represents the state of the object
+ /// that affects [operator ==] comparisons.
+ ///
+ /// All objects have hash codes.
+ /// The default hash code implemented by [Object]
+ /// represents only the identity of the object,
+ /// the same way as the default [operator ==] implementation only considers objects
+ /// equal if they are identical (see [identityHashCode]).
+ ///
+ /// If [operator ==] is overridden to use the object state instead,
+ /// the hash code must also be changed to represent that state,
+ /// otherwise the object cannot be used in hash based data structures
+ /// like the default [Set] and [Map] implementations.
+ ///
+ /// Hash codes must be the same for objects that are equal to each other
+ /// according to [operator ==].
+ /// The hash code of an object should only change if the object changes
+ /// in a way that affects equality.
+ /// There are no further requirements for the hash codes.
+ /// They need not be consistent between executions of the same program
+ /// and there are no distribution guarantees.
+ ///
+ /// Objects that are not equal are allowed to have the same hash code.
+ /// It is even technically allowed that all instances have the same hash code,
+ /// but if clashes happen too often,
+ /// it may reduce the efficiency of hash-based data structures
+ /// like [HashSet] or [HashMap].
+ ///
+ /// If a subclass overrides [hashCode], it should override the
+ /// [operator ==] operator as well to maintain consistency.
external int get hashCode;
- /**
- * Returns a string representation of this object.
- */
+ /// A string representation of this object.
+ ///
+ /// Some classes have a default textual representation,
+ /// often paired with a static `parse` function (like [int.parse]).
+ /// These classes will provide the textual representation as
+ /// their string represetion.
+ ///
+ /// Other classes have no meaningful textual representation
+ /// that a program will care about.
+ /// Such classes will typically override `toString` to provide
+ /// useful information when inspecting the object,
+ /// mainly for debugging or logging.
external String toString();
- /**
- * Invoked when a non-existent method or property is accessed.
- *
- * Classes can override [noSuchMethod] to provide custom behavior.
- *
- * If a value is returned, it becomes the result of the original invocation.
- *
- * The default behavior is to throw a [NoSuchMethodError].
- */
+ /// Invoked when a non-existent method or property is accessed.
+ ///
+ /// A dynamic member invocation can attempt to call a member which
+ /// doesn't exist on the receiving object. Example:
+ /// ```dart
+ /// dynamic object = 1;
+ /// object.add(42); // Statically allowed, run-time error
+ /// ```
+ /// This invalid code will invoke the `noSuchMethod` memthod
+ /// of the integer `1` with an [Invocation] representing the
+ /// `.add(42)` call and arguments (which then throws).
+ ///
+ /// Classes can override [noSuchMethod] to provide custom behavior
+ /// for such invalid dynamic invocations.
+ ///
+ /// A class with a non-default [noSuchMethod] invocation can also
+ /// omit implementations for members of its interface.
+ /// Example:
+ /// ```dart
+ /// class MockList<T> implements List<T> {
+ /// noSuchMethod(Invocation invocation) {
+ /// log(invocation);
+ /// super.noSuchMethod(invocation); // Will throw.
+ /// }
+ /// }
+ /// void main() {
+ /// MockList().add(42);
+ /// }
+ /// ```
+ /// This code has no compile-time warnings or errors even though
+ /// the `MockList` class has no concrete implementation of
+ /// any of the `List` interface methods.
+ /// Calls to `List` methods are forwarded to `noSuchMethod`,
+ /// so this code will `log` an invocation similar to
+ /// `Invocation.method(#add, [42])` and then throw.
+ ///
+ /// If a value is returned from `noSuchMethod`,
+ /// it becomes the result of the original invocation.
+ /// If the value is not of a type that can be returned by the original
+ /// invocation, a type error occurs at the invocation.
+ ///
+ /// The default behavior is to throw a [NoSuchMethodError].
@pragma("vm:entry-point")
external dynamic noSuchMethod(Invocation invocation);
- /**
- * A representation of the runtime type of the object.
- */
+ /// A representation of the runtime type of the object.
external Type get runtimeType;
}
diff --git a/sdk/lib/core/pattern.dart b/sdk/lib/core/pattern.dart
index 7a3d933..94c8980 100644
--- a/sdk/lib/core/pattern.dart
+++ b/sdk/lib/core/pattern.dart
@@ -4,124 +4,99 @@
part of dart.core;
-/**
- * An interface for basic searches within strings.
- */
+/// An interface for basic searches within strings.
abstract class Pattern {
- /**
- * Match this pattern against the string repeatedly.
- *
- * If [start] is provided, matching will start at that index.
- *
- * The returned iterable lazily computes all the non-overlapping matches
- * of the pattern on the string, ordered by start index.
- * If a user only requests the first
- * match, this function should not compute all possible matches.
- *
- * The matches are found by repeatedly finding the first match
- * of the pattern on the string, starting from the end of the previous
- * match, and initially starting from index zero.
- *
- * If the pattern matches the empty string at some point, the next
- * match is found by starting at the previous match's end plus one.
- */
+ /// Matches this pattern against the string repeatedly.
+ ///
+ /// If [start] is provided, matching will start at that index.
+ ///
+ /// The returned iterable lazily finds non-overlapping matches
+ /// of the pattern in the [string].
+ /// If a user only requests the first match,
+ /// this function should not compute all possible matches.
+ ///
+ /// The matches are found by repeatedly finding the first match
+ /// of the pattern in the string, initially starting from [start],
+ /// and then from the end of the previous match (but always
+ /// at least one position later than the *start* of the previous
+ /// match, in case the patter matches an empty substring).
Iterable<Match> allMatches(String string, [int start = 0]);
- /**
- * Match this pattern against the start of `string`.
- *
- * If [start] is provided, it must be an integer in the range `0` ..
- * `string.length`. In that case, this patten is tested against the
- * string at the [start] position. That is, a [Match] is returned if the
- * pattern can match a part of the string starting from position [start].
- * Returns `null` if the pattern doesn't match.
- */
+ /// Matches this pattern against the start of `string`.
+ ///
+ /// Returns a match if the pattern matches a substring of [string]
+ /// starting at [start], and `null` if the pattern doesn't match
+ /// a that point.
+ ///
+ /// The [start] must be non-negative and no greater than `string.length`.
Match? matchAsPrefix(String string, [int start = 0]);
}
-/**
- * A result from searching within a string.
- *
- * A Match or an [Iterable] of Match objects is returned from [Pattern]
- * matching methods.
- *
- * The following example finds all matches of a [RegExp] in a [String]
- * and iterates through the returned iterable of Match objects.
- *
- * RegExp exp = new RegExp(r"(\w+)");
- * String str = "Parse my string";
- * Iterable<Match> matches = exp.allMatches(str);
- * for (Match m in matches) {
- * String match = m.group(0);
- * print(match);
- * }
- *
- * The output of the example is:
- *
- * Parse
- * my
- * string
- *
- * Some patterns, regular expressions in particular, may record substrings
- * that were part of the matching. These are called _groups_ in the Match
- * object. Some patterns may never have any groups, and their matches always
- * have zero [groupCount].
- */
+/// A result from searching within a string.
+///
+/// A `Match` or an [Iterable] of `Match` objects is returned from
+/// the [Pattern] matching methods
+/// ([Pattern.allMatches] and [Pattern.matchAsPrefix]).
+///
+/// The following example finds all matches of a [RegExp] in a [String]
+/// and iterates through the returned iterable of `Match` objects.
+/// ```dart
+/// RegExp exp = RegExp(r"(\w+)");
+/// String str = "Parse my string";
+/// Iterable<Match> matches = exp.allMatches(str);
+/// for (Match m in matches) {
+/// String match = m[0]!;
+/// print(match);
+/// }
+/// ```
+/// The output of the example is:
+/// ```dart
+/// Parse
+/// my
+/// string
+/// ```
+/// Some patterns, regular expressions in particular, may record substrings
+/// that were part of the matching. These are called _groups_ in the `Match`
+/// object. Some patterns may never have any groups, and their matches always
+/// have zero [groupCount].
abstract class Match {
- /**
- * Returns the index in the string where the match starts.
- */
+ /// The index in the string where the match starts.
int get start;
- /**
- * Returns the index in the string after the last character of the
- * match.
- */
+ /// The index in the string after the last character of the match.
int get end;
- /**
- * Returns the string matched by the given [group].
- *
- * If [group] is 0, returns the match of the pattern.
- *
- * The result may be `null` if the pattern didn't assign a value to it
- * as part of this match.
- */
+ /// The string matched by the given [group].
+ ///
+ /// If [group] is 0, returns the entire match of the pattern.
+ ///
+ /// The result may be `null` if the pattern didn't assign a value to it
+ /// as part of this match.
String? group(int group);
- /**
- * Returns the string matched by the given [group].
- *
- * If [group] is 0, returns the match of the pattern.
- *
- * Short alias for [Match.group].
- */
+ /// The string matched by the given [group].
+ ///
+ /// If [group] is 0, returns the match of the pattern.
+ ///
+ /// Short alias for [Match.group].
String? operator [](int group);
- /**
- * Returns a list of the groups with the given indices.
- *
- * The list contains the strings returned by [group] for each index in
- * [groupIndices].
- */
+ /// A list of the groups with the given indices.
+ ///
+ /// The list contains the strings returned by [group] for each index in
+ /// [groupIndices].
List<String?> groups(List<int> groupIndices);
- /**
- * Returns the number of captured groups in the match.
- *
- * Some patterns may capture parts of the input that was used to
- * compute the full match. This is the number of captured groups,
- * which is also the maximal allowed argument to the [group] method.
- */
+ /// Returns the number of captured groups in the match.
+ ///
+ /// Some patterns may capture parts of the input that was used to
+ /// compute the full match. This is the number of captured groups,
+ /// which is also the maximal allowed argument to the [group] method.
int get groupCount;
- /**
- * The string on which this match was computed.
- */
+ /// The string on which this match was computed.
String get input;
- /**
- * The pattern used to search in [input].
- */
+ /// The pattern used to search in [input].
Pattern get pattern;
}
diff --git a/sdk/lib/core/regexp.dart b/sdk/lib/core/regexp.dart
index ca5309f..993da0a5 100644
--- a/sdk/lib/core/regexp.dart
+++ b/sdk/lib/core/regexp.dart
@@ -4,186 +4,160 @@
part of dart.core;
-/**
- * A regular expression pattern.
- *
- * Regular expressions are [Pattern]s, and can as such be used to match strings
- * or parts of strings.
- *
- * Dart regular expressions have the same syntax and semantics as
- * JavaScript regular expressions. See
- * <https://ecma-international.org/ecma-262/9.0/#sec-regexp-regular-expression-objects>
- * for the specification of JavaScript regular expressions.
- *
- * [firstMatch] is the main implementation method that applies a regular
- * expression to a string and returns the first [RegExpMatch]. All
- * other methods in [RegExp] can build on it.
- *
- * Use [allMatches] to look for all matches of a regular expression in
- * a string.
- *
- * The following example finds all matches of a regular expression in
- * a string.
- * ```dart
- * RegExp exp = new RegExp(r"(\w+)");
- * String str = "Parse my string";
- * Iterable<RegExpMatch> matches = exp.allMatches(str);
- * ```
- *
- * Note the use of a _raw string_ (a string prefixed with `r`)
- * in the example above. Use a raw string to treat each character in a string
- * as a literal character.
- */
+/// A regular expression pattern.
+///
+/// Regular expressions are [Pattern]s, and can as such be used to match strings
+/// or parts of strings.
+///
+/// Dart regular expressions have the same syntax and semantics as
+/// JavaScript regular expressions. See
+/// <https://ecma-international.org/ecma-262/9.0/#sec-regexp-regular-expression-objects>
+/// for the specification of JavaScript regular expressions.
+///
+/// The [firstMatch] method is the main implementation method
+/// that applies a regular expression to a string
+/// and returns the first [RegExpMatch].
+/// All other methods in [RegExp] can be build from that.
+///
+/// Use [allMatches] to look for all matches of a regular expression in
+/// a string.
+///
+/// The following example finds all matches of a regular expression in
+/// a string.
+/// ```dart
+/// RegExp exp = RegExp(r"(\w+)");
+/// String str = "Parse my string";
+/// Iterable<RegExpMatch> matches = exp.allMatches(str);
+/// ```
+///
+/// Note the use of a _raw string_ (a string prefixed with `r`)
+/// in the example above. Use a raw string to treat each character in a string
+/// as a literal character.
abstract class RegExp implements Pattern {
- /**
- * Constructs a regular expression.
- *
- * Throws a [FormatException] if [source] is not valid regular
- * expression syntax.
- *
- * If `multiLine` is enabled, then `^` and `$` will match the beginning and
- * end of a _line_, in addition to matching beginning and end of input,
- * respectively.
- *
- * If `caseSensitive` is disabled, then case is ignored.
- *
- * If `unicode` is enabled, then the pattern is treated as a Unicode
- * pattern as described by the ECMAScript standard.
- *
- * If `dotAll` is enabled, then the `.` pattern will match _all_ characters,
- * including line terminators.
- *
- * Example:
- *
- * ```dart
- * var wordPattern = RegExp(r"(\w+)");
- * var bracketedNumberValue = RegExp("$key: \\[\\d+\\]");
- * ```
- *
- * Notice the use of a _raw string_ in the first example, and a regular
- * string in the second. Because of the many character classes used in
- * regular expressions, it is common to use a raw string here, unless string
- * interpolation is required.
- */
+ /// Constructs a regular expression.
+ ///
+ /// Throws a [FormatException] if [source] is not valid regular
+ /// expression syntax.
+ ///
+ /// If `multiLine` is enabled, then `^` and `$` will match the beginning and
+ /// end of a _line_, in addition to matching beginning and end of input,
+ /// respectively.
+ ///
+ /// If `caseSensitive` is disabled, then case is ignored.
+ ///
+ /// If `unicode` is enabled, then the pattern is treated as a Unicode
+ /// pattern as described by the ECMAScript standard.
+ ///
+ /// If `dotAll` is enabled, then the `.` pattern will match _all_ characters,
+ /// including line terminators.
+ ///
+ /// Example:
+ ///
+ /// ```dart
+ /// var wordPattern = RegExp(r"(\w+)");
+ /// var bracketedNumberValue = RegExp("$key: \\[\\d+\\]");
+ /// ```
+ ///
+ /// Notice the use of a _raw string_ in the first example, and a regular
+ /// string in the second. Because of the many escapes, like `\d`, used in
+ /// regular expressions, it is common to use a raw string here, unless string
+ /// interpolation is required.
external factory RegExp(String source,
{bool multiLine = false,
bool caseSensitive = true,
@Since("2.4") bool unicode = false,
@Since("2.4") bool dotAll = false});
- /**
- * Returns a regular expression that matches [text].
- *
- * If [text] contains characters that are meaningful in regular expressions,
- * the resulting regular expression will match those characters literally.
- * If [text] contains no characters that have special meaning in a regular
- * expression, it is returned unmodified.
- *
- * The characters that have special meaning in regular expressions are:
- * `(`, `)`, `[`, `]`, `{`, `}`, `*`, `+`, `?`, `.`, `^`, `$`, `|` and `\`.
- */
+ /// Creates regular expression syntax that matches [text].
+ ///
+ /// If [text] contains characters that are meaningful in regular expressions,
+ /// the resulting regular expression will match those characters literally.
+ /// If [text] contains no characters that have special meaning in a regular
+ /// expression, it is returned unmodified.
+ ///
+ /// The characters that have special meaning in regular expressions are:
+ /// `(`, `)`, `[`, `]`, `{`, `}`, `*`, `+`, `?`, `.`, `^`, `$`, `|` and `\`.
+ ///
+ /// This method is mainly used to create a pattern to be included in a
+ /// larger regular expression. Since a [String] is itself a [Pattern]
+ /// which matches itself, converting the string to a regular expression
+ /// isn't needed in order to search for just that string.
external static String escape(String text);
- /**
- * Searches for the first match of the regular expression
- * in the string [input]. Returns `null` if there is no match.
- */
+ /// Finds the first match of the regular expression in the string [input].
+ ///
+ /// Returns `null` if there is no match.
RegExpMatch? firstMatch(String input);
- /**
- * Returns an iterable of the matches of the regular expression on [input].
- *
- * If [start] is provided, only start looking for matches at `start`.
- */
Iterable<RegExpMatch> allMatches(String input, [int start = 0]);
- /**
- * Returns whether the regular expression has a match in the string [input].
- */
+ /// Whether the regular expression has a match in the string [input].
bool hasMatch(String input);
- /**
- * Returns the first substring match of this regular expression in [input].
- */
+ /// The substring of the first match of this regular expression in [input].
String? stringMatch(String input);
- /**
- * The source regular expression string used to create this `RegExp`.
- */
+ /// The source regular expression string used to create this `RegExp`.
String get pattern;
- /**
- * Whether this regular expression matches multiple lines.
- *
- * If the regexp does match multiple lines, the "^" and "$" characters
- * match the beginning and end of lines. If not, the character match the
- * beginning and end of the input.
- */
+ /// Whether this regular expression matches multiple lines.
+ ///
+ /// If the regexp does match multiple lines, the "^" and "$" characters
+ /// match the beginning and end of lines. If not, the characters match the
+ /// beginning and end of the input.
bool get isMultiLine;
- /**
- * Whether this regular expression is case sensitive.
- *
- * If the regular expression is not case sensitive, it will match an input
- * letter with a pattern letter even if the two letters are different case
- * versions of the same letter.
- */
+ /// Whether this regular expression is case sensitive.
+ ///
+ /// If the regular expression is not case sensitive, it will match an input
+ /// letter with a pattern letter even if the two letters are different case
+ /// versions of the same letter.
bool get isCaseSensitive;
- /**
- * Whether this regular expression is in Unicode mode.
- *
- * In Unicode mode, UTF-16 surrogate pairs in the original string will be
- * treated as a single code point and will not match separately. Otherwise,
- * the target string will be treated purely as a sequence of individual code
- * units and surrogates will not be treated specially.
- *
- * In Unicode mode, the syntax of the RegExp pattern is more restricted, but
- * some pattern features, like Unicode property escapes, are only available in
- * this mode.
- */
+ /// Whether this regular expression is in Unicode mode.
+ ///
+ /// In Unicode mode, UTF-16 surrogate pairs in the original string will be
+ /// treated as a single code point and will not match separately. Otherwise,
+ /// the target string will be treated purely as a sequence of individual code
+ /// units and surrogates will not be treated specially.
+ ///
+ /// In Unicode mode, the syntax of the RegExp pattern is more restricted, but
+ /// some pattern features, like Unicode property escapes, are only available in
+ /// this mode.
@Since("2.4")
bool get isUnicode;
- /**
- * Whether "." in this regular expression matches line terminators.
- *
- * When false, the "." character matches a single character, unless that
- * character is a line terminator. When true, then the "." character will
- * match any single character including line terminators.
- *
- * This feature is distinct from [isMultiLine], as they affect the behavior
- * of different pattern characters, and so they can be used together or
- * separately.
- */
+ /// Whether "." in this regular expression matches line terminators.
+ ///
+ /// When false, the "." character matches a single character, unless that
+ /// character is a line terminator. When true, then the "." character will
+ /// match any single character including line terminators.
+ ///
+ /// This feature is distinct from [isMultiLine], as they affect the behavior
+ /// of different pattern characters, and so they can be used together or
+ /// separately.
@Since("2.4")
bool get isDotAll;
}
-/**
- * A regular expression match.
- *
- * Regular expression matches are [Match]es, but also include the ability
- * to retrieve the names for any named capture groups and to retrieve
- * matches for named capture groups by name instead of their index.
- */
+/// A regular expression match.
+///
+/// Regular expression matches are [Match]es, but also include the ability
+/// to retrieve the names for any named capture groups and to retrieve
+/// matches for named capture groups by name instead of their index.
@Since("2.3")
abstract class RegExpMatch implements Match {
- /**
- * The string matched by the group named [name].
- *
- * Returns the string matched by the capture group named [name], or
- * `null` if no string was matched by that capture group as part of
- * this match.
- *
- * The [name] must be the name of a named capture group in the regular
- * expression creating this match (that is, the name must be in
- * [groupNames]).
- */
+ /// The string matched by the group named [name].
+ ///
+ /// Returns the string matched by the capture group named [name], or
+ /// `null` if no string was matched by that capture group as part of
+ /// this match.
+ ///
+ /// The [name] must be the name of a named capture group in the regular
+ /// expression creating this match (that is, the name must be in
+ /// [groupNames]).
String? namedGroup(String name);
- /**
- * The names of the captured groups in the match.
- */
+ /// The names of the captured groups in the match.
Iterable<String> get groupNames;
}
diff --git a/sdk/lib/core/set.dart b/sdk/lib/core/set.dart
index 3683920..eb86364 100644
--- a/sdk/lib/core/set.dart
+++ b/sdk/lib/core/set.dart
@@ -4,273 +4,227 @@
part of dart.core;
-/**
- * A collection of objects in which each object can occur only once.
- *
- * That is, for each object of the element type, the object is either considered
- * to be in the set, or to _not_ be in the set.
- *
- * Set implementations may consider some elements indistinguishable. These
- * elements are treated as being the same for any operation on the set.
- *
- * The default [Set] implementation, [LinkedHashSet], considers objects
- * indistinguishable if they are equal with regard to
- * operator [Object.==].
- *
- * Iterating over elements of a set may be either unordered
- * or ordered in some way. Examples:
- *
- * * A [HashSet] is unordered, which means that its iteration order is
- * unspecified,
- * * [LinkedHashSet] iterates in the insertion order of its elements, and
- * * a sorted set like [SplayTreeSet] iterates the elements in sorted order.
- *
- * It is generally not allowed to modify the set (add or remove elements) while
- * an operation on the set is being performed, for example during a call to
- * [forEach] or [containsAll]. Nor is it allowed to modify the set while
- * iterating either the set itself or any [Iterable] that is backed by the set,
- * such as the ones returned by methods like [where] and [map].
- *
- * It is generally not allowed to modify the equality of elements (and thus not
- * their hashcode) while they are in the set. Some specialized subtypes may be
- * more permissive, in which case they should document this behavior.
- */
+/// A collection of objects in which each object can occur only once.
+///
+/// That is, for each object of the element type, the object is either considered
+/// to be in the set, or to _not_ be in the set.
+///
+/// Set implementations may consider some elements indistinguishable. These
+/// elements are treated as being the same for any operation on the set.
+///
+/// The default [Set] implementation, [LinkedHashSet], considers objects
+/// indistinguishable if they are equal with regard to
+/// operator [Object.==].
+///
+/// Iterating over elements of a set may be either unordered
+/// or ordered in some way. Examples:
+///
+/// * A [HashSet] is unordered, which means that its iteration order is
+/// unspecified,
+/// * [LinkedHashSet] iterates in the insertion order of its elements, and
+/// * a sorted set like [SplayTreeSet] iterates the elements in sorted order.
+///
+/// It is generally not allowed to modify the set (add or remove elements) while
+/// an operation on the set is being performed, for example during a call to
+/// [forEach] or [containsAll]. Nor is it allowed to modify the set while
+/// iterating either the set itself or any [Iterable] that is backed by the set,
+/// such as the ones returned by methods like [where] and [map].
+///
+/// It is generally not allowed to modify the equality of elements (and thus not
+/// their hashcode) while they are in the set. Some specialized subtypes may be
+/// more permissive, in which case they should document this behavior.
abstract class Set<E> extends EfficientLengthIterable<E> {
- /**
- * Creates an empty [Set].
- *
- * The created [Set] is a plain [LinkedHashSet].
- * As such, it considers elements that are equal (using [operator ==]) to be
- * indistinguishable, and requires them to have a compatible
- * [Object.hashCode] implementation.
- *
- * The set is equivalent to one created by `new LinkedHashSet<E>()`.
- */
+ /// Creates an empty [Set].
+ ///
+ /// The created [Set] is a plain [LinkedHashSet].
+ /// As such, it considers elements that are equal (using [operator ==]) to be
+ /// indistinguishable, and requires them to have a compatible
+ /// [Object.hashCode] implementation.
+ ///
+ /// The set is equivalent to one created by `LinkedHashSet<E>()`.
factory Set() = LinkedHashSet<E>;
- /**
- * Creates an empty identity [Set].
- *
- * The created [Set] is a [LinkedHashSet] that uses identity as equality
- * relation.
- *
- * The set is equivalent to one created by `new LinkedHashSet<E>.identity()`.
- */
+ /// Creates an empty identity [Set].
+ ///
+ /// The created [Set] is a [LinkedHashSet] that uses identity as equality
+ /// relation.
+ ///
+ /// The set is equivalent to one created by `LinkedHashSet<E>.identity()`.
factory Set.identity() = LinkedHashSet<E>.identity;
- /**
- * Creates a [Set] that contains all [elements].
- *
- * All the [elements] should be instances of [E].
- * The `elements` iterable itself can have any type,
- * so this constructor can be used to down-cast a `Set`, for example as:
- *
- * Set<SuperType> superSet = ...;
- * Set<SubType> subSet =
- * new Set<SubType>.from(superSet.where((e) => e is SubType));
- *
- * The created [Set] is a [LinkedHashSet]. As such, it considers elements that
- * are equal (using [operator ==]) to be indistinguishable, and requires them to
- * have a compatible [Object.hashCode] implementation.
- *
- * The set is equivalent to one created by
- * `new LinkedHashSet<E>.from(elements)`.
- */
+ /// Creates a [Set] that contains all [elements].
+ ///
+ /// All the [elements] should be instances of [E].
+ /// The `elements` iterable itself can have any type,
+ /// so this constructor can be used to down-cast a `Set`, for example as:
+ /// ```dart
+ /// Set<SuperType> superSet = ...;
+ /// Set<SubType> subSet =
+ /// Set<SubType>.from(superSet.where((e) => e is SubType));
+ /// ```
+ /// The created [Set] is a [LinkedHashSet]. As such, it considers elements that
+ /// are equal (using [operator ==]) to be indistinguishable, and requires them to
+ /// have a compatible [Object.hashCode] implementation.
+ ///
+ /// The set is equivalent to one created by
+ /// `LinkedHashSet<E>.from(elements)`.
factory Set.from(Iterable elements) = LinkedHashSet<E>.from;
- /**
- * Creates a [Set] from [elements].
- *
- * The created [Set] is a [LinkedHashSet]. As such, it considers elements that
- * are equal (using [operator ==]) to be indistinguishable, and requires them to
- * have a compatible [Object.hashCode] implementation.
- *
- * The set is equivalent to one created by
- * `new LinkedHashSet<E>.of(elements)`.
- */
+ /// Creates a [Set] from [elements].
+ ///
+ /// The created [Set] is a [LinkedHashSet]. As such, it considers elements that
+ /// are equal (using [operator ==]) to be indistinguishable, and requires them to
+ /// have a compatible [Object.hashCode] implementation.
+ ///
+ /// The set is equivalent to one created by
+ /// `LinkedHashSet<E>.of(elements)`.
factory Set.of(Iterable<E> elements) = LinkedHashSet<E>.of;
- /**
- * Creates an unmodifiable [Set] from [elements].
- *
- * The new set behaves like the result of [Set.of],
- * except that the set returned by this constructor is not modifiable.
- */
+ /// Creates an unmodifiable [Set] from [elements].
+ ///
+ /// The new set behaves like the result of [Set.of],
+ /// except that the set returned by this constructor is not modifiable.
@Since("2.12")
factory Set.unmodifiable(Iterable<E> elements) =>
UnmodifiableSetView<E>(<E>{...elements});
- /**
- * Adapts [source] to be a `Set<T>`.
- *
- * If [newSet] is provided, it is used to create the new sets returned
- * by [toSet], [union], and is also used for [intersection] and [difference].
- * If [newSet] is omitted, it defaults to creating a new set using the
- * default [Set] constructor, and [intersection] and [difference]
- * returns an adapted version of calling the same method on the source.
- *
- * Any time the set would produce an element that is not a [T],
- * the element access will throw.
- *
- * Any time a [T] value is attempted added into the adapted set,
- * the store will throw unless the value is also an instance of [S].
- *
- * If all accessed elements of [source] are actually instances of [T],
- * and if all elements added to the returned set are actually instance
- * of [S],
- * then the returned set can be used as a `Set<T>`.
- */
+ /// Adapts [source] to be a `Set<T>`.
+ ///
+ /// If [newSet] is provided, it is used to create the new sets returned
+ /// by [toSet], [union], and is also used for [intersection] and [difference].
+ /// If [newSet] is omitted, it defaults to creating a new set using the
+ /// default [Set] constructor, and [intersection] and [difference]
+ /// returns an adapted version of calling the same method on the source.
+ ///
+ /// Any time the set would produce an element that is not a [T],
+ /// the element access will throw.
+ ///
+ /// Any time a [T] value is attempted added into the adapted set,
+ /// the store will throw unless the value is also an instance of [S].
+ ///
+ /// If all accessed elements of [source] are actually instances of [T],
+ /// and if all elements added to the returned set are actually instance
+ /// of [S],
+ /// then the returned set can be used as a `Set<T>`.
static Set<T> castFrom<S, T>(Set<S> source, {Set<R> Function<R>()? newSet}) =>
CastSet<S, T>(source, newSet);
- /**
- * Provides a view of this set as a set of [R] instances.
- *
- * If this set contains only instances of [R], all read operations
- * will work correctly. If any operation tries to access an element
- * that is not an instance of [R], the access will throw instead.
- *
- * Elements added to the set (e.g., by using [add] or [addAll])
- * must be instance of [R] to be valid arguments to the adding function,
- * and they must be instances of [E] as well to be accepted by
- * this set as well.
- */
+ /// Provides a view of this set as a set of [R] instances.
+ ///
+ /// If this set contains only instances of [R], all read operations
+ /// will work correctly. If any operation tries to access an element
+ /// that is not an instance of [R], the access will throw instead.
+ ///
+ /// Elements added to the set (e.g., by using [add] or [addAll])
+ /// must be instance of [R] to be valid arguments to the adding function,
+ /// and they must be instances of [E] as well to be accepted by
+ /// this set as well.
Set<R> cast<R>();
- /**
- * Provides an iterator that iterates over the elements of this set.
- *
- * The order of iteration is defined by the individual `Set` implementation,
- * but must be consistent between changes to the set.
- */
+ /// An iterator that iterates over the elements of this set.
+ ///
+ /// The order of iteration is defined by the individual `Set` implementation,
+ /// but must be consistent between changes to the set.
Iterator<E> get iterator;
- /**
- * Returns `true` if [value] is in the set.
- */
+ /// Whether [value] is in the set.
bool contains(Object? value);
- /**
- * Adds [value] to the set.
- *
- * Returns `true` if [value] (or an equal value) was not yet in the set.
- * Otherwise returns `false` and the set is not changed.
- *
- * Example:
- *
- * var set = new Set();
- * var time1 = new DateTime.fromMillisecondsSinceEpoch(0);
- * var time2 = new DateTime.fromMillisecondsSinceEpoch(0);
- * // time1 and time2 are equal, but not identical.
- * Expect.isTrue(time1 == time2);
- * Expect.isFalse(identical(time1, time2));
- * set.add(time1); // => true.
- * // A value equal to time2 exists already in the set, and the call to
- * // add doesn't change the set.
- * set.add(time2); // => false.
- * Expect.isTrue(set.length == 1);
- * Expect.isTrue(identical(time1, set.first));
- */
+ /// Adds [value] to the set.
+ ///
+ /// Returns `true` if [value] (or an equal value) was not yet in the set.
+ /// Otherwise returns `false` and the set is not changed.
+ ///
+ /// Example:
+ /// ```dart
+ /// var set = Set();
+ /// var time1 = DateTime.fromMillisecondsSinceEpoch(0);
+ /// var time2 = DateTime.fromMillisecondsSinceEpoch(0);
+ /// // time1 and time2 are equal, but not identical.
+ /// assert(time1 == time2);
+ /// assert(!identical(time1, time2));
+ /// set.add(time1); // => true.
+ /// // A value equal to time2 exists already in the set, and the call to
+ /// // add doesn't change the set.
+ /// set.add(time2); // => false.
+ /// assert(set.length == 1);
+ /// assert(identical(time1, set.first));
+ /// ```
bool add(E value);
- /**
- * Adds all [elements] to this Set.
- *
- * Equivalent to adding each element in [elements] using [add],
- * but some collections may be able to optimize it.
- */
+ /// Adds all [elements] to this set.
+ ///
+ /// Equivalent to adding each element in [elements] using [add],
+ /// but some collections may be able to optimize it.
void addAll(Iterable<E> elements);
- /**
- * Removes [value] from the set. Returns `true` if [value] was
- * in the set. Returns `false` otherwise. The method has no effect
- * if [value] was not in the set.
- */
+ /// Removes [value] from the set.
+ ///
+ /// Returns `true` if [value] was in the set, and `false` if not.
+ /// The method has no effect if [value] was not in the set.
bool remove(Object? value);
- /**
- * If an object equal to [object] is in the set, return it.
- *
- * Checks whether [object] is in the set, like [contains], and if so,
- * returns the object in the set, otherwise returns `null`.
- *
- * If the equality relation used by the set is not identity,
- * then the returned object may not be *identical* to [object].
- * Some set implementations may not be able to implement this method.
- * If the [contains] method is computed,
- * rather than being based on an actual object instance,
- * then there may not be a specific object instance representing the
- * set element.
- */
+ /// If an object equal to [object] is in the set, return it.
+ ///
+ /// Checks whether [object] is in the set, like [contains], and if so,
+ /// returns the object in the set, otherwise returns `null`.
+ ///
+ /// If the equality relation used by the set is not identity,
+ /// then the returned object may not be *identical* to [object].
+ /// Some set implementations may not be able to implement this method.
+ /// If the [contains] method is computed,
+ /// rather than being based on an actual object instance,
+ /// then there may not be a specific object instance representing the
+ /// set element.
E? lookup(Object? object);
- /**
- * Removes each element of [elements] from this set.
- */
+ /// Removes each element of [elements] from this set.
void removeAll(Iterable<Object?> elements);
- /**
- * Removes all elements of this set that are not elements in [elements].
- *
- * Checks for each element of [elements] whether there is an element in this
- * set that is equal to it (according to `this.contains`), and if so, the
- * equal element in this set is retained, and elements that are not equal
- * to any element in [elements] are removed.
- */
+ /// Removes all elements of this set that are not elements in [elements].
+ ///
+ /// Checks for each element of [elements] whether there is an element in this
+ /// set that is equal to it (according to `this.contains`), and if so, the
+ /// equal element in this set is retained, and elements that are not equal
+ /// to any element in [elements] are removed.
void retainAll(Iterable<Object?> elements);
- /**
- * Removes all elements of this set that satisfy [test].
- */
+ /// Removes all elements of this set that satisfy [test].
void removeWhere(bool test(E element));
- /**
- * Removes all elements of this set that fail to satisfy [test].
- */
+ /// Removes all elements of this set that fail to satisfy [test].
void retainWhere(bool test(E element));
- /**
- * Returns whether this Set contains all the elements of [other].
- */
+ /// Whether this set contains all the elements of [other].
bool containsAll(Iterable<Object?> other);
- /**
- * Returns a new set which is the intersection between this set and [other].
- *
- * That is, the returned set contains all the elements of this [Set] that
- * are also elements of [other] according to `other.contains`.
- */
+ /// Creates a new set which is the intersection between this set and [other].
+ ///
+ /// That is, the returned set contains all the elements of this [Set] that
+ /// are also elements of [other] according to `other.contains`.
Set<E> intersection(Set<Object?> other);
- /**
- * Returns a new set which contains all the elements of this set and [other].
- *
- * That is, the returned set contains all the elements of this [Set] and
- * all the elements of [other].
- */
+ /// Creates a new set which contains all the elements of this set and [other].
+ ///
+ /// That is, the returned set contains all the elements of this [Set] and
+ /// all the elements of [other].
Set<E> union(Set<E> other);
- /**
- * Returns a new set with the elements of this that are not in [other].
- *
- * That is, the returned set contains all the elements of this [Set] that
- * are not elements of [other] according to `other.contains`.
- */
+ /// Creates a new set with the elements of this that are not in [other].
+ ///
+ /// That is, the returned set contains all the elements of this [Set] that
+ /// are not elements of [other] according to `other.contains`.
Set<E> difference(Set<Object?> other);
- /**
- * Removes all elements in the set.
- */
+ /// Removes all elements from the set.
void clear();
- /**
- * Creates a [Set] with the same elements and behavior as this `Set`.
- *
- * The returned set behaves the same as this set
- * with regard to adding and removing elements.
- * It initially contains the same elements.
- * If this set specifies an ordering of the elements,
- * the returned set will have the same order.
- */
+ /// Creates a [Set] with the same elements and behavior as this `Set`.
+ ///
+ /// The returned set behaves the same as this set
+ /// with regard to adding and removing elements.
+ /// It initially contains the same elements.
+ /// If this set specifies an ordering of the elements,
+ /// the returned set will have the same order.
Set<E> toSet();
}
diff --git a/sdk/lib/core/sink.dart b/sdk/lib/core/sink.dart
index c79214b..565ec8f 100644
--- a/sdk/lib/core/sink.dart
+++ b/sdk/lib/core/sink.dart
@@ -4,28 +4,22 @@
part of dart.core;
-/**
- * A generic destination for data.
- *
- * Multiple data values can be put into a sink, and when no more data is
- * available, the sink should be closed.
- *
- * This is a generic interface that other data receivers can implement.
- */
+/// A generic destination for data.
+///
+/// Multiple data values can be put into a sink, and when no more data is
+/// available, the sink should be closed.
+///
+/// This is a generic interface that other data receivers can implement.
abstract class Sink<T> {
- /**
- * Adds [data] to the sink.
- *
- * Must not be called after a call to [close].
- */
+ /// Adds [data] to the sink.
+ ///
+ /// Must not be called after a call to [close].
void add(T data);
- /**
- * Closes the sink.
- *
- * The [add] method must not be called after this method.
- *
- * Calling this method more than once is allowed, but does nothing.
- */
+ /// Closes the sink.
+ ///
+ /// The [add] method must not be called after this method.
+ ///
+ /// Calling this method more than once is allowed, but does nothing.
void close();
}
diff --git a/sdk/lib/core/stacktrace.dart b/sdk/lib/core/stacktrace.dart
index ef08f71..dbba199 100644
--- a/sdk/lib/core/stacktrace.dart
+++ b/sdk/lib/core/stacktrace.dart
@@ -4,15 +4,13 @@
part of dart.core;
-/**
- * An interface implemented by all stack trace objects.
- *
- * A [StackTrace] is intended to convey information to the user about the call
- * sequence that triggered an exception.
- *
- * These objects are created by the runtime, it is not possible to create
- * them programmatically.
- */
+/// An interface implemented by all stack trace objects.
+///
+/// A [StackTrace] is intended to convey information to the user about the call
+/// sequence that triggered an exception.
+///
+/// These objects are created by the runtime, it is not possible to create
+/// them programmatically.
abstract class StackTrace {
/// A stack trace object with no information.
///
@@ -23,40 +21,33 @@
StackTrace(); // In case existing classes extend StackTrace.
- /**
- * Create a `StackTrace` object from [stackTraceString].
- *
- * The created stack trace will have a `toString` method returning
- * `stackTraceString`.
- *
- * The `stackTraceString` can be a string returned by some other
- * stack trace, or it can be any string at all.
- * If the string doesn't look like a stack trace, code that interprets
- * stack traces is likely to fail, so fake stack traces should be used
- * with care.
- */
+ /// Create a `StackTrace` object from [stackTraceString].
+ ///
+ /// The created stack trace will have a `toString` method returning
+ /// `stackTraceString`.
+ ///
+ /// The `stackTraceString` can be a string returned by some other
+ /// stack trace, or it can be any string at all.
+ /// If the string doesn't look like a stack trace, code that interprets
+ /// stack traces is likely to fail, so fake stack traces should be used
+ /// with care.
factory StackTrace.fromString(String stackTraceString) = _StringStackTrace;
- /**
- * Returns a representation of the current stack trace.
- *
- * This is similar to what can be achieved by doing:
- *
- * try { throw 0; } catch (_, stack) { return stack; }
- *
- * The getter achieves this without throwing, except on platforms that
- * have no other way to get a stack trace.
- */
+ /// Returns a representation of the current stack trace.
+ ///
+ /// This is similar to what can be achieved by doing:
+ /// ```dart
+ /// try { throw 0; } catch (_, stack) { return stack; }
+ /// ```
+ /// The getter achieves this without throwing if possible.
external static StackTrace get current;
- /**
- * Returns a [String] representation of the stack trace.
- *
- * The string represents the full stack trace starting from
- * the point where a throw occurred to the top of the current call sequence.
- *
- * The exact format of the string representation is not final.
- */
+ /// Returns a [String] representation of the stack trace.
+ ///
+ /// The string represents the full stack trace starting from
+ /// the point where a throw occurred to the top of the current call sequence.
+ ///
+ /// The exact format of the string representation is not final.
String toString();
}
diff --git a/sdk/lib/core/stopwatch.dart b/sdk/lib/core/stopwatch.dart
index 311db3d..024c28f 100644
--- a/sdk/lib/core/stopwatch.dart
+++ b/sdk/lib/core/stopwatch.dart
@@ -4,15 +4,11 @@
part of dart.core;
-/**
- * A simple stopwatch interface to measure elapsed time.
- */
+/// A simple stopwatch interface to measure elapsed time.
class Stopwatch {
- /**
- * Cached frequency of the system in Hz (ticks per second).
- *
- * Value must be returned by [_initTicker], which is called only once.
- */
+ /// Cached frequency of the system in Hz (ticks per second).
+ ///
+ /// Value must be returned by [_initTicker], which is called only once.
static final int _frequency = _initTicker();
// The _start and _stop fields capture the time when [start] and [stop]
@@ -21,33 +17,27 @@
int _start = 0;
int? _stop = 0;
- /**
- * Creates a [Stopwatch] in stopped state with a zero elapsed count.
- *
- * The following example shows how to start a [Stopwatch]
- * immediately after allocation.
- * ```
- * var stopwatch = new Stopwatch()..start();
- * ```
- */
+ /// Creates a [Stopwatch] in stopped state with a zero elapsed count.
+ ///
+ /// The following example shows how to start a [Stopwatch]
+ /// immediately after allocation.
+ /// ```
+ /// var stopwatch = Stopwatch()..start();
+ /// ```
Stopwatch() {
_frequency; // Ensures initialization before using any method.
}
- /**
- * Frequency of the elapsed counter in Hz.
- */
+ /// Frequency of the elapsed counter in Hz.
int get frequency => _frequency;
- /**
- * Starts the [Stopwatch].
- *
- * The [elapsed] count is increasing monotonically. If the [Stopwatch] has
- * been stopped, then calling start again restarts it without resetting the
- * [elapsed] count.
- *
- * If the [Stopwatch] is currently running, then calling start does nothing.
- */
+ /// Starts the [Stopwatch].
+ ///
+ /// The [elapsed] count is increasing monotonically. If the [Stopwatch] has
+ /// been stopped, then calling start again restarts it without resetting the
+ /// [elapsed] count.
+ ///
+ /// If the [Stopwatch] is currently running, then calling start does nothing.
void start() {
int? stop = _stop;
if (stop != null) {
@@ -58,67 +48,51 @@
}
}
- /**
- * Stops the [Stopwatch].
- *
- * The [elapsedTicks] count stops increasing after this call. If the
- * [Stopwatch] is currently not running, then calling this method has no
- * effect.
- */
+ /// Stops the [Stopwatch].
+ ///
+ /// The [elapsedTicks] count stops increasing after this call. If the
+ /// [Stopwatch] is currently not running, then calling this method has no
+ /// effect.
void stop() {
_stop ??= _now();
}
- /**
- * Resets the [elapsed] count to zero.
- *
- * This method does not stop or start the [Stopwatch].
- */
+ /// Resets the [elapsed] count to zero.
+ ///
+ /// This method does not stop or start the [Stopwatch].
void reset() {
_start = _stop ?? _now();
}
- /**
- * The elapsed number of clock ticks since calling [start] while the
- * [Stopwatch] is running.
- *
- * This is the elapsed number of clock ticks between calling [start] and
- * calling [stop].
- *
- * Is 0 if the [Stopwatch] has never been started.
- *
- * The elapsed number of clock ticks increases by [frequency] every second.
- */
+ /// The elapsed number of clock ticks since calling [start] while the
+ /// [Stopwatch] is running.
+ ///
+ /// This is the elapsed number of clock ticks between calling [start] and
+ /// calling [stop].
+ ///
+ /// Is 0 if the [Stopwatch] has never been started.
+ ///
+ /// The elapsed number of clock ticks increases by [frequency] every second.
int get elapsedTicks {
return (_stop ?? _now()) - _start;
}
- /**
- * The [elapsedTicks] counter converted to a [Duration].
- */
+ /// The [elapsedTicks] counter converted to a [Duration].
Duration get elapsed {
return Duration(microseconds: elapsedMicroseconds);
}
- /**
- * The [elapsedTicks] counter converted to microseconds.
- */
+ /// The [elapsedTicks] counter converted to microseconds.
external int get elapsedMicroseconds;
- /**
- * The [elapsedTicks] counter converted to milliseconds.
- */
+ /// The [elapsedTicks] counter converted to milliseconds.
external int get elapsedMilliseconds;
- /**
- * Whether the [Stopwatch] is currently running.
- */
+ /// Whether the [Stopwatch] is currently running.
bool get isRunning => _stop == null;
- /**
- * Initializes the time-measuring system. *Must* return the [_frequency]
- * variable. May do other necessary initialization.
- */
+ /// Initializes the time-measuring system. *Must* return the [_frequency]
+ /// variable. May do other necessary initialization.
external static int _initTicker();
external static int _now();
}
diff --git a/sdk/lib/core/string.dart b/sdk/lib/core/string.dart
index 7bef81c..27aba63 100644
--- a/sdk/lib/core/string.dart
+++ b/sdk/lib/core/string.dart
@@ -4,156 +4,148 @@
part of dart.core;
-/**
- * A sequence of UTF-16 code units.
- *
- * Strings are mainly used to represent text. A character may be represented by
- * multiple code points, each code point consisting of one or two code
- * units. For example the Papua New Guinea flag character requires four code
- * units to represent two code points, but should be treated like a single
- * character: "🇵🇬". Platforms that do not support the flag character may show
- * the letters "PG" instead. If the code points are swapped, it instead becomes
- * the Guadeloupe flag "🇬🇵" ("GP").
- *
- * A string can be either single or multiline. Single line strings are
- * written using matching single or double quotes, and multiline strings are
- * written using triple quotes. The following are all valid Dart strings:
- *
- * 'Single quotes';
- * "Double quotes";
- * 'Double quotes in "single" quotes';
- * "Single quotes in 'double' quotes";
- *
- * '''A
- * multiline
- * string''';
- *
- * """
- * Another
- * multiline
- * string""";
- *
- * Strings are immutable. Although you cannot change a string, you can perform
- * an operation on a string and assign the result to a new string:
- *
- * var string = 'Dart is fun';
- * var newString = string.substring(0, 5);
- *
- * You can use the plus (`+`) operator to concatenate strings:
- *
- * 'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'
- *
- * You can also use adjacent string literals for concatenation:
- *
- * 'Dart ' 'is ' 'fun!'; // 'Dart is fun!'
- *
- * You can use `${}` to interpolate the value of Dart expressions
- * within strings. The curly braces can be omitted when evaluating identifiers:
- *
- * string = 'dartlang';
- * '$string has ${string.length} letters'; // 'dartlang has 8 letters'
- *
- * A string is represented by a sequence of Unicode UTF-16 code units
- * accessible through the [codeUnitAt] or the [codeUnits] members:
- *
- * string = 'Dart';
- * string.codeUnitAt(0); // 68
- * string.codeUnits; // [68, 97, 114, 116]
- *
- * The string representation of code units is accessible through the index
- * operator:
- *
- * string[0]; // 'D'
- *
- * The characters of a string are encoded in UTF-16. Decoding UTF-16, which
- * combines surrogate pairs, yields Unicode code points. Following a similar
- * terminology to Go, we use the name 'rune' for an integer representing a
- * Unicode code point. Use the [runes] property to get the runes of a string:
- *
- * string.runes.toList(); // [68, 97, 114, 116]
- *
- * For a character outside the Basic Multilingual Plane (plane 0) that is
- * composed of a surrogate pair, [runes] combines the pair and returns a
- * single integer. For example, the Unicode character for a
- * musical G-clef ('𝄞') with rune value 0x1D11E consists of a UTF-16 surrogate
- * pair: `0xD834` and `0xDD1E`. Using [codeUnits] returns the surrogate pair,
- * and using `runes` returns their combined value:
- *
- * var clef = '\u{1D11E}';
- * clef.codeUnits; // [0xD834, 0xDD1E]
- * clef.runes.toList(); // [0x1D11E]
- *
- * The String class can not be extended or implemented. Attempting to do so
- * yields a compile-time error.
- *
- * ## Other resources
- *
- * See [StringBuffer] to efficiently build a string incrementally. See
- * [RegExp] to work with regular expressions.
- *
- * Also see:
- *
- * * [Strings and regular expressions](https://dart.dev/guides/libraries/library-tour#strings-and-regular-expressions)
- */
+/// A sequence of UTF-16 code units.
+///
+/// Strings are mainly used to represent text. A character may be represented by
+/// multiple code points, each code point consisting of one or two code
+/// units. For example the Papua New Guinea flag character requires four code
+/// units to represent two code points, but should be treated like a single
+/// character: "🇵🇬". Platforms that do not support the flag character may show
+/// the letters "PG" instead. If the code points are swapped, it instead becomes
+/// the Guadeloupe flag "🇬🇵" ("GP").
+///
+/// A string can be either single or multiline. Single line strings are
+/// written using matching single or double quotes, and multiline strings are
+/// written using triple quotes. The following are all valid Dart strings:
+/// ```dart
+/// 'Single quotes';
+/// "Double quotes";
+/// 'Double quotes in "single" quotes';
+/// "Single quotes in 'double' quotes";
+///
+/// '''A
+/// multiline
+/// string''';
+///
+/// """
+/// Another
+/// multiline
+/// string""";
+/// ```
+/// Strings are immutable. Although you cannot change a string, you can perform
+/// an operation on a string which creates a new string:
+/// ```dart
+/// var string = 'Dart is fun';
+/// var newString = string.substring(0, 5);
+/// ```
+/// You can use the plus (`+`) operator to concatenate strings:
+/// ```dart
+/// 'Dart ' + 'is ' + 'fun!'; // 'Dart is fun!'
+/// ```
+/// Adjacent string literals are concatenated automatically:
+/// ```dart
+/// 'Dart ' 'is ' 'fun!'; // 'Dart is fun!'
+/// ```
+/// You can use `${}` to interpolate the value of Dart expressions
+/// within strings. The curly braces can be omitted when evaluating identifiers:
+/// ```dart
+/// string = 'dartlang';
+/// '$string has ${string.length} letters'; // 'dartlang has 8 letters'
+/// ```
+/// A string is represented by a sequence of Unicode UTF-16 code units
+/// accessible through the [codeUnitAt] or the [codeUnits] members:
+/// ```dart
+/// string = 'Dart';
+/// string.codeUnitAt(0); // 68
+/// string.codeUnits; // [68, 97, 114, 116]
+/// ```
+/// The string representation of code units is accessible through the index
+/// operator:
+/// ```dart
+/// string[0]; // 'D'
+/// ```
+/// The characters of a string are encoded in UTF-16. Decoding UTF-16, which
+/// combines surrogate pairs, yields Unicode code points. Following a similar
+/// terminology to Go, we use the name 'rune' for an integer representing a
+/// Unicode code point. Use the [runes] property to get the runes of a string:
+/// ```dart
+/// string.runes.toList(); // [68, 97, 114, 116]
+/// ```
+/// For a character outside the Basic Multilingual Plane (plane 0) that is
+/// composed of a surrogate pair, [runes] combines the pair and returns a
+/// single integer. For example, the Unicode character for a
+/// musical G-clef ('𝄞') with rune value 0x1D11E consists of a UTF-16 surrogate
+/// pair: `0xD834` and `0xDD1E`. Using [codeUnits] returns the surrogate pair,
+/// and using `runes` returns their combined value:
+/// ```dart
+/// var clef = '\u{1D11E}';
+/// clef.codeUnits; // [0xD834, 0xDD1E]
+/// clef.runes.toList(); // [0x1D11E]
+/// ```
+/// The `String` class cannot be extended or implemented. Attempting to do so
+/// yields a compile-time error.
+///
+/// ## Other resources
+///
+/// See [StringBuffer] to efficiently build a string incrementally. See
+/// [RegExp] to work with regular expressions.
+///
+/// Also see:
+///
+/// * [Strings and regular expressions](https://dart.dev/guides/libraries/library-tour#strings-and-regular-expressions)
@pragma('vm:entry-point')
abstract class String implements Comparable<String>, Pattern {
- /**
- * Allocates a new String for the specified [charCodes].
- *
- * The [charCodes] can be UTF-16 code units or runes. If a char-code value is
- * 16-bit, it is copied verbatim:
- *
- * new String.fromCharCodes([68]); // 'D'
- *
- * If a char-code value is greater than 16-bits, it is decomposed into a
- * surrogate pair:
- *
- * var clef = new String.fromCharCodes([0x1D11E]);
- * clef.codeUnitAt(0); // 0xD834
- * clef.codeUnitAt(1); // 0xDD1E
- *
- * If [start] and [end] is provided, only the values of [charCodes]
- * at positions from `start` to, but not including, `end`, are used.
- * The `start` and `end` values must satisfy
- * `0 <= start <= end <= charCodes.length`.
- */
+ /// Allocates a new string containing the specified [charCodes].
+ ///
+ /// The [charCodes] can be both UTF-16 code units or runes.
+ /// If a char-code value is 16-bit, it is used as a code unit:
+ /// ```dart
+ /// String.fromCharCodes([68]); // 'D'
+ /// ```
+ /// If a char-code value is greater than 16-bits, it is decomposed into a
+ /// surrogate pair:
+ /// ```dart
+ /// var clef = String.fromCharCodes([0x1D11E]);
+ /// clef.codeUnitAt(0); // 0xD834
+ /// clef.codeUnitAt(1); // 0xDD1E
+ /// ```
+ /// If [start] and [end] are provided, only the values of [charCodes]
+ /// at positions from `start` to, but not including, `end`, are used.
+ /// The `start` and `end` values must satisfy
+ /// `0 <= start <= end <= charCodes.length`.
external factory String.fromCharCodes(Iterable<int> charCodes,
[int start = 0, int? end]);
- /**
- * Allocates a new String for the specified [charCode].
- *
- * If the [charCode] can be represented by a single UTF-16 code unit, the new
- * string contains a single code unit. Otherwise, the [length] is 2 and
- * the code units form a surrogate pair. See documentation for
- * [fromCharCodes].
- *
- * Creating a [String] with one half of a surrogate pair is allowed.
- */
+ /// Allocates a new string containing the specified [charCode].
+ ///
+ /// If the [charCode] can be represented by a single UTF-16 code unit, the new
+ /// string contains a single code unit. Otherwise, the [length] is 2 and
+ /// the code units form a surrogate pair. See documentation for
+ /// [fromCharCodes].
+ ///
+ /// Creating a [String] with one half of a surrogate pair is allowed.
external factory String.fromCharCode(int charCode);
- /**
- * Returns the string value of the environment declaration [name].
- *
- * Environment declarations are provided by the surrounding system compiling
- * or running the Dart program. Declarations map a string key to a string
- * value.
- *
- * If [name] is not declared in the environment, the result is instead
- * [defaultValue].
- *
- * Example of getting a value:
- * ```
- * const String.fromEnvironment("defaultFloo", defaultValue: "no floo")
- * ```
- * In order to check whether a declaration is there at all, use
- * [bool.hasEnvironment]. Example:
- * ```
- * const maybeDeclared = bool.hasEnvironment("maybeDeclared")
- * ? String.fromEnvironment("maybeDeclared")
- * : null;
- * ```
- */
+ /// The string value of the environment declaration [name].
+ ///
+ /// Environment declarations are provided by the surrounding system compiling
+ /// or running the Dart program. Declarations map a string key to a string
+ /// value.
+ ///
+ /// If [name] is not declared in the environment, the result is instead
+ /// [defaultValue].
+ ///
+ /// Example of getting a value:
+ /// ```
+ /// const String.fromEnvironment("defaultFloo", defaultValue: "no floo")
+ /// ```
+ /// In order to check whether a declaration is there at all, use
+ /// [bool.hasEnvironment]. Example:
+ /// ```
+ /// const maybeDeclared = bool.hasEnvironment("maybeDeclared")
+ /// ? String.fromEnvironment("maybeDeclared")
+ /// : null;
+ /// ```
// The .fromEnvironment() constructors are special in that we do not want
// users to call them using "new". We prohibit that by giving them bodies
// that throw, even though const constructors are not allowed to have bodies.
@@ -163,484 +155,447 @@
external const factory String.fromEnvironment(String name,
{String defaultValue = ""});
- /**
- * Gets the character (as a single-code-unit [String]) at the given [index].
- *
- * The returned string represents exactly one UTF-16 code unit, which may be
- * half of a surrogate pair. A single member of a surrogate pair is an
- * invalid UTF-16 string:
- *
- * var clef = '\u{1D11E}';
- * // These represent invalid UTF-16 strings.
- * clef[0].codeUnits; // [0xD834]
- * clef[1].codeUnits; // [0xDD1E]
- *
- * This method is equivalent to
- * `new String.fromCharCode(this.codeUnitAt(index))`.
- */
+ /// The character (as a single-code-unit [String]) at the given [index].
+ ///
+ /// The returned string represents exactly one UTF-16 code unit, which may be
+ /// half of a surrogate pair. A single member of a surrogate pair is an
+ /// invalid UTF-16 string:
+ /// ```dart
+ /// var clef = '\u{1D11E}';
+ /// // These represent invalid UTF-16 strings.
+ /// clef[0].codeUnits; // [0xD834]
+ /// clef[1].codeUnits; // [0xDD1E]
+ /// ```
+ /// This method is equivalent to
+ /// `String.fromCharCode(this.codeUnitAt(index))`.
String operator [](int index);
- /**
- * Returns the 16-bit UTF-16 code unit at the given [index].
- */
+ /// Returns the 16-bit UTF-16 code unit at the given [index].
int codeUnitAt(int index);
- /**
- * The length of the string.
- *
- * Returns the number of UTF-16 code units in this string. The number
- * of [runes] might be fewer, if the string contains characters outside
- * the Basic Multilingual Plane (plane 0):
- *
- * 'Dart'.length; // 4
- * 'Dart'.runes.length; // 4
- *
- * var clef = '\u{1D11E}';
- * clef.length; // 2
- * clef.runes.length; // 1
- */
+ /// The length of the string.
+ ///
+ /// Returns the number of UTF-16 code units in this string. The number
+ /// of [runes] might be fewer, if the string contains characters outside
+ /// the Basic Multilingual Plane (plane 0):
+ /// ```dart
+ /// 'Dart'.length; // 4
+ /// 'Dart'.runes.length; // 4
+ ///
+ /// var clef = '\u{1D11E}';
+ /// clef.length; // 2
+ /// clef.runes.length; // 1
+ /// ```
int get length;
- /**
- * Returns a hash code derived from the code units of the string.
- *
- * This is compatible with [operator ==]. Strings with the same sequence
- * of code units have the same hash code.
- */
+ /// A hash code derived from the code units of the string.
+ ///
+ /// This is compatible with [operator ==]. Strings with the same sequence
+ /// of code units have the same hash code.
int get hashCode;
- /**
- * Returns true if other is a `String` with the same sequence of code units.
- *
- * This method compares each individual code unit of the strings.
- * It does not check for Unicode equivalence.
- * For example, both the following strings represent the string 'Amélie',
- * but due to their different encoding, are not equal:
- *
- * 'Am\xe9lie' == 'Ame\u{301}lie'; // false
- *
- * The first string encodes 'é' as a single unicode code unit (also
- * a single rune), whereas the second string encodes it as 'e' with the
- * combining accent character '◌́'.
- */
+ /// Whether [other] is a `String` with the same sequence of code units.
+ ///
+ /// This method compares each individual code unit of the strings.
+ /// It does not check for Unicode equivalence.
+ /// For example, both the following strings represent the string 'Amélie',
+ /// but due to their different encoding, are not equal:
+ /// ```dart
+ /// 'Am\xe9lie' == 'Ame\u{301}lie'; // false
+ /// ```
+ /// The first string encodes 'é' as a single unicode code unit (also
+ /// a single rune), whereas the second string encodes it as 'e' with the
+ /// combining accent character '◌́'.
bool operator ==(Object other);
- /**
- * Compares this string to [other].
- *
- * Returns a negative value if `this` is ordered before `other`,
- * a positive value if `this` is ordered after `other`,
- * or zero if `this` and `other` are equivalent.
- *
- * The ordering is the same as the ordering of the code points at the first
- * position where the two strings differ.
- * If one string is a prefix of the other,
- * then the shorter string is ordered before the longer string.
- * If the strings have exactly the same content, they are equivalent with
- * regard to the ordering.
- * Ordering does not check for Unicode equivalence.
- * The comparison is case sensitive.
- */
+ /// Compares this string to [other].
+ ///
+ /// Returns a negative value if `this` is ordered before `other`,
+ /// a positive value if `this` is ordered after `other`,
+ /// or zero if `this` and `other` are equivalent.
+ ///
+ /// The ordering is the same as the ordering of the code points at the first
+ /// position where the two strings differ.
+ /// If one string is a prefix of the other,
+ /// then the shorter string is ordered before the longer string.
+ /// If the strings have exactly the same content, they are equivalent with
+ /// regard to the ordering.
+ /// Ordering does not check for Unicode equivalence.
+ /// The comparison is case sensitive.
int compareTo(String other);
- /**
- * Returns true if this string ends with [other]. For example:
- *
- * 'Dart'.endsWith('t'); // true
- */
+ /// Whether this string ends with [other].
+ ///
+ /// For example:
+ /// ```dart
+ /// 'Dart'.endsWith('t'); // true
+ /// ```
bool endsWith(String other);
- /**
- * Returns true if this string starts with a match of [pattern].
- *
- * var string = 'Dart';
- * string.startsWith('D'); // true
- * string.startsWith(new RegExp(r'[A-Z][a-z]')); // true
- *
- * If [index] is provided, this method checks if the substring starting
- * at that index starts with a match of [pattern]:
- *
- * string.startsWith('art', 1); // true
- * string.startsWith(new RegExp(r'\w{3}')); // true
- *
- * [index] must not be negative or greater than [length].
- *
- * A [RegExp] containing '^' does not match if the [index] is greater than
- * zero. The pattern works on the string as a whole, and does not extract
- * a substring starting at [index] first:
- *
- * string.startsWith(new RegExp(r'^art'), 1); // false
- * string.startsWith(new RegExp(r'art'), 1); // true
- */
+ /// Whether this string starts with a match of [pattern].
+ ///
+ /// ```dart
+ /// var string = 'Dart';
+ /// string.startsWith('D'); // true
+ /// string.startsWith(RegExp(r'[A-Z][a-z]')); // true
+ /// ```
+ /// If [index] is provided, this method checks if the substring starting
+ /// at that index starts with a match of [pattern]:
+ /// ```dart
+ /// string.startsWith('art', 1); // true
+ /// string.startsWith(RegExp(r'\w{3}')); // true
+ /// ```
+ /// [index] must not be negative or greater than [length].
+ ///
+ /// A [RegExp] containing '^' does not match if the [index] is greater than
+ /// zero and the regexp is not multi-line.
+ /// The pattern works on the string as a whole, and does not extract
+ /// a substring starting at [index] first:
+ /// ```dart
+ /// string.startsWith(RegExp(r'^art'), 1); // false
+ /// string.startsWith(RegExp(r'art'), 1); // true
+ /// ```
bool startsWith(Pattern pattern, [int index = 0]);
- /**
- * Returns the position of the first match of [pattern] in this string,
- * starting at [start], inclusive:
- *
- * var string = 'Dartisans';
- * string.indexOf('art'); // 1
- * string.indexOf(new RegExp(r'[A-Z][a-z]')); // 0
- *
- * Returns -1 if no match is found:
- *
- * string.indexOf(new RegExp(r'dart')); // -1
- *
- * [start] must be non-negative and not greater than [length].
- */
+ /// Returns the position of the first match of [pattern] in this string,
+ /// starting at [start], inclusive:
+ /// ```dart
+ /// var string = 'Dartisans';
+ /// string.indexOf('art'); // 1
+ /// string.indexOf(RegExp(r'[A-Z][a-z]')); // 0
+ /// ```
+ /// Returns -1 if no match is found:
+ /// ```dart
+ /// string.indexOf(RegExp(r'dart')); // -1
+ /// ```
+ /// The [start] must be non-negative and not greater than [length].
int indexOf(Pattern pattern, [int start = 0]);
- /**
- * Returns the starting position of the last match [pattern] in this string,
- * searching backward starting at [start], inclusive:
- *
- * var string = 'Dartisans';
- * string.lastIndexOf('a'); // 6
- * string.lastIndexOf(RegExp(r'a(r|n)')); // 6
- *
- * Returns -1 if [pattern] could not be found in this string.
- *
- * string.lastIndexOf(RegExp(r'DART')); // -1
- *
- * If [start] is omitted, search starts from the end of the string.
- * If supplied, [start] must be non-negative and not greater than [length].
- */
+ /// The starting position of the last match [pattern] in this string.
+ ///
+ /// Finds a match of pattern by searching backward starting at [start]:
+ /// ```dart
+ /// var string = 'Dartisans';
+ /// string.lastIndexOf('a'); // 6
+ /// string.lastIndexOf(RegExp(r'a(r|n)')); // 6
+ /// ```
+ /// Returns -1 if [pattern] could not be found in this string.
+ /// ```dart
+ /// string.lastIndexOf(RegExp(r'DART')); // -1
+ /// ```
+ /// If [start] is omitted, search starts from the end of the string.
+ /// If supplied, [start] must be non-negative and not greater than [length].
int lastIndexOf(Pattern pattern, [int? start]);
- /**
- * Returns true if this string is empty.
- */
+ /// Whether this string is empty.
bool get isEmpty;
- /**
- * Returns true if this string is not empty.
- */
+ /// Whether this string is not empty.
bool get isNotEmpty;
- /**
- * Creates a new string by concatenating this string with [other].
- *
- * 'dart' + 'lang'; // 'dartlang'
- */
+ /// Creates a new string by concatenating this string with [other].
+ ///
+ /// Example:
+ /// ```dart
+ /// 'dart' + 'lang'; // 'dartlang'
+ /// ```
String operator +(String other);
- /**
- * Returns the substring of this string that extends from [startIndex],
- * inclusive, to [endIndex], exclusive.
- *
- * var string = 'dartlang';
- * string.substring(1); // 'artlang'
- * string.substring(1, 4); // 'art'
- */
- String substring(int startIndex, [int? endIndex]);
+ /// The substring of this string from [start],inclusive, to [end], exclusive.
+ ///
+ /// Example:
+ /// ```dart
+ /// var string = 'dartlang';
+ /// string.substring(1); // 'artlang'
+ /// string.substring(1, 4); // 'art'
+ /// ```
+ String substring(int start, [int? end]);
- /**
- * Returns the string without any leading and trailing whitespace.
- *
- * If the string contains leading or trailing whitespace, a new string with no
- * leading and no trailing whitespace is returned:
- * ```dart
- * '\tDart is fun\n'.trim(); // 'Dart is fun'
- * ```
- * Otherwise, the original string itself is returned:
- * ```dart
- * var str1 = 'Dart';
- * var str2 = str1.trim();
- * identical(str1, str2); // true
- * ```
- * Whitespace is defined by the Unicode White_Space property (as defined in
- * version 6.2 or later) and the BOM character, 0xFEFF.
- *
- * Here is the list of trimmed characters according to Unicode version 6.3:
- * ```
- * 0009..000D ; White_Space # Cc <control-0009>..<control-000D>
- * 0020 ; White_Space # Zs SPACE
- * 0085 ; White_Space # Cc <control-0085>
- * 00A0 ; White_Space # Zs NO-BREAK SPACE
- * 1680 ; White_Space # Zs OGHAM SPACE MARK
- * 2000..200A ; White_Space # Zs EN QUAD..HAIR SPACE
- * 2028 ; White_Space # Zl LINE SEPARATOR
- * 2029 ; White_Space # Zp PARAGRAPH SEPARATOR
- * 202F ; White_Space # Zs NARROW NO-BREAK SPACE
- * 205F ; White_Space # Zs MEDIUM MATHEMATICAL SPACE
- * 3000 ; White_Space # Zs IDEOGRAPHIC SPACE
- *
- * FEFF ; BOM ZERO WIDTH NO_BREAK SPACE
- * ```
- * Some later versions of Unicode do not include U+0085 as a whitespace
- * character. Whether it is trimmed depends on the Unicode version
- * used by the system.
- */
+ /// The string without any leading and trailing whitespace.
+ ///
+ /// If the string contains leading or trailing whitespace, a new string with no
+ /// leading and no trailing whitespace is returned:
+ /// ```dart
+ /// '\tDart is fun\n'.trim(); // 'Dart is fun'
+ /// ```
+ /// Otherwise, the original string itself is returned:
+ /// ```dart
+ /// var str1 = 'Dart';
+ /// var str2 = str1.trim();
+ /// identical(str1, str2); // true
+ /// ```
+ /// Whitespace is defined by the Unicode White_Space property (as defined in
+ /// version 6.2 or later) and the BOM character, 0xFEFF.
+ ///
+ /// Here is the list of trimmed characters according to Unicode version 6.3:
+ /// ```
+ /// 0009..000D ; White_Space # Cc <control-0009>..<control-000D>
+ /// 0020 ; White_Space # Zs SPACE
+ /// 0085 ; White_Space # Cc <control-0085>
+ /// 00A0 ; White_Space # Zs NO-BREAK SPACE
+ /// 1680 ; White_Space # Zs OGHAM SPACE MARK
+ /// 2000..200A ; White_Space # Zs EN QUAD..HAIR SPACE
+ /// 2028 ; White_Space # Zl LINE SEPARATOR
+ /// 2029 ; White_Space # Zp PARAGRAPH SEPARATOR
+ /// 202F ; White_Space # Zs NARROW NO-BREAK SPACE
+ /// 205F ; White_Space # Zs MEDIUM MATHEMATICAL SPACE
+ /// 3000 ; White_Space # Zs IDEOGRAPHIC SPACE
+ ///
+ /// FEFF ; BOM ZERO WIDTH NO_BREAK SPACE
+ /// ```
+ /// Some later versions of Unicode do not include U+0085 as a whitespace
+ /// character. Whether it is trimmed depends on the Unicode version
+ /// used by the system.
String trim();
- /**
- * Returns the string without any leading whitespace.
- *
- * As [trim], but only removes leading whitespace.
- */
+ /// The string without any leading whitespace.
+ ///
+ /// As [trim], but only removes leading whitespace.
String trimLeft();
- /**
- * Returns the string without any trailing whitespace.
- *
- * As [trim], but only removes trailing whitespace.
- */
+ /// The string without any trailing whitespace.
+ ///
+ /// As [trim], but only removes trailing whitespace.
String trimRight();
- /**
- * Creates a new string by concatenating this string with itself a number
- * of times.
- *
- * The result of `str * n` is equivalent to
- * `str + str + ...`(n times)`... + str`.
- *
- * Returns an empty string if [times] is zero or negative.
- */
+ /// Creates a new string by concatenating this string with itself a number
+ /// of times.
+ ///
+ /// The result of `str * n` is equivalent to
+ /// `str + str + ...`(n times)`... + str`.
+ ///
+ /// Returns an empty string if [times] is zero or negative.
String operator *(int times);
- /**
- * Pads this string on the left if it is shorter than [width].
- *
- * Return a new string that prepends [padding] onto this string
- * one time for each position the length is less than [width].
- *
- * If [width] is already smaller than or equal to `this.length`,
- * no padding is added. A negative `width` is treated as zero.
- *
- * If [padding] has length different from 1, the result will not
- * have length `width`. This may be useful for cases where the
- * padding is a longer string representing a single character, like
- * `" "` or `"\u{10002}`".
- * In that case, the user should make sure that `this.length` is
- * the correct measure of the strings length.
- */
+ /// Pads this string on the left if it is shorter than [width].
+ ///
+ /// Returns a new string that prepends [padding] onto this string
+ /// one time for each position the length is less than [width].
+ ///
+ /// If [width] is already smaller than or equal to `this.length`,
+ /// no padding is added. A negative `width` is treated as zero.
+ ///
+ /// If [padding] has length different from 1, the result will not
+ /// have length `width`. This may be useful for cases where the
+ /// padding is a longer string representing a single character, like
+ /// `" "` or `"\u{10002}`".
+ /// In that case, the user should make sure that `this.length` is
+ /// the correct measure of the strings length.
String padLeft(int width, [String padding = ' ']);
- /**
- * Pads this string on the right if it is shorter than [width].
- *
- * Return a new string that appends [padding] after this string
- * one time for each position the length is less than [width].
- *
- * If [width] is already smaller than or equal to `this.length`,
- * no padding is added. A negative `width` is treated as zero.
- *
- * If [padding] has length different from 1, the result will not
- * have length `width`. This may be useful for cases where the
- * padding is a longer string representing a single character, like
- * `" "` or `"\u{10002}`".
- * In that case, the user should make sure that `this.length` is
- * the correct measure of the strings length.
- */
+ /// Pads this string on the right if it is shorter than [width].
+ ///
+ /// Returns a new string that appends [padding] after this string
+ /// one time for each position the length is less than [width].
+ ///
+ /// If [width] is already smaller than or equal to `this.length`,
+ /// no padding is added. A negative `width` is treated as zero.
+ ///
+ /// If [padding] has length different from 1, the result will not
+ /// have length `width`. This may be useful for cases where the
+ /// padding is a longer string representing a single character, like
+ /// `" "` or `"\u{10002}`".
+ /// In that case, the user should make sure that `this.length` is
+ /// the correct measure of the strings length.
String padRight(int width, [String padding = ' ']);
- /**
- * Returns true if this string contains a match of [other]:
- *
- * var string = 'Dart strings';
- * string.contains('D'); // true
- * string.contains(new RegExp(r'[A-Z]')); // true
- *
- * If [startIndex] is provided, this method matches only at or after that
- * index:
- *
- * string.contains('X', 1); // false
- * string.contains(new RegExp(r'[A-Z]'), 1); // false
- *
- * [startIndex] must not be negative or greater than [length].
- */
+ /// Whether this string contains a match of [other].
+ ///
+ /// Example:
+ /// ```dart
+ /// var string = 'Dart strings';
+ /// string.contains('D'); // true
+ /// string.contains(RegExp(r'[A-Z]')); // true
+ /// ```
+ /// If [startIndex] is provided, this method matches only at or after that
+ /// index:
+ /// ```dart
+ /// string.contains('D', 1); // false
+ /// string.contains(RegExp(r'[A-Z]'), 1); // false
+ /// ```
+ /// The [startIndex] must not be negative or greater than [length].
bool contains(Pattern other, [int startIndex = 0]);
- /**
- * Returns a new string in which the first occurrence of [from] in this string
- * is replaced with [to], starting from [startIndex]:
- *
- * '0.0001'.replaceFirst(new RegExp(r'0'), ''); // '.0001'
- * '0.0001'.replaceFirst(new RegExp(r'0'), '7', 1); // '0.7001'
- */
+ /// Creates a new string with the first occurrence of [from] replaced by [to].
+ ///
+ /// Finds the first match of [from] in this string, starting from [startIndex],
+ /// and creates a new string where that match is replaced with the [to] string.
+ ///
+ /// Example:
+ /// ```dart
+ /// '0.0001'.replaceFirst(RegExp(r'0'), ''); // '.0001'
+ /// '0.0001'.replaceFirst(RegExp(r'0'), '7', 1); // '0.7001'
+ /// ```
String replaceFirst(Pattern from, String to, [int startIndex = 0]);
- /**
- * Replace the first occurrence of [from] in this string.
- *
- * Returns a new string, which is this string
- * except that the first match of [from], starting from [startIndex],
- * is replaced by the result of calling [replace] with the match object.
- *
- * The optional [startIndex] is by default set to 0. If provided, it must be
- * an integer in the range `[0 .. len]`, where `len` is this string's length.
- */
+ /// Replace the first occurrence of [from] in this string.
+ ///
+ /// Returns a new string, which is this string
+ /// except that the first match of [from], starting from [startIndex],
+ /// is replaced by the result of calling [replace] with the match object.
+ ///
+ /// The [startIndex] must be non-negative and no greater than [length].
String replaceFirstMapped(Pattern from, String replace(Match match),
[int startIndex = 0]);
- /**
- * Replaces all substrings that match [from] with [replace].
- *
- * Returns a new string in which the non-overlapping substrings matching
- * [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
- * by the literal string [replace].
- *
- * 'resume'.replaceAll(new RegExp(r'e'), 'é'); // 'résumé'
- *
- * Notice that the [replace] string is not interpreted. If the replacement
- * depends on the match (for example on a [RegExp]'s capture groups), use
- * the [replaceAllMapped] method instead.
- */
+ /// Replaces all substrings that match [from] with [replace].
+ ///
+ /// Creates a new string in which the non-overlapping substrings matching
+ /// [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
+ /// by the literal string [replace].
+ /// ```dart
+ /// 'resume'.replaceAll(RegExp(r'e'), 'é'); // 'résumé'
+ /// ```
+ /// Notice that the [replace] string is not interpreted. If the replacement
+ /// depends on the match (for example on a [RegExp]'s capture groups), use
+ /// the [replaceAllMapped] method instead.
String replaceAll(Pattern from, String replace);
- /**
- * Replace all substrings that match [from] by a string computed from the
- * match.
- *
- * Returns a new string in which the non-overlapping substrings that match
- * [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
- * by the result of calling [replace] on the corresponding [Match] object.
- *
- * This can be used to replace matches with new content that depends on the
- * match, unlike [replaceAll] where the replacement string is always the same.
- *
- * The [replace] function is called with the [Match] generated
- * by the pattern, and its result is used as replacement.
- *
- * The function defined below converts each word in a string to simplified
- * 'pig latin' using [replaceAllMapped]:
- *
- * pigLatin(String words) => words.replaceAllMapped(
- * new RegExp(r'\b(\w*?)([aeiou]\w*)', caseSensitive: false),
- * (Match m) => "${m[2]}${m[1]}${m[1].isEmpty ? 'way' : 'ay'}");
- *
- * pigLatin('I have a secret now!'); // 'Iway avehay away ecretsay ownay!'
- */
+ /// Replace all substrings that match [from] by a computed string.
+ ///
+ /// Creates a new string in which the non-overlapping substrings that match
+ /// [from] (the ones iterated by `from.allMatches(thisString)`) are replaced
+ /// by the result of calling [replace] on the corresponding [Match] object.
+ ///
+ /// This can be used to replace matches with new content that depends on the
+ /// match, unlike [replaceAll] where the replacement string is always the same.
+ ///
+ /// The [replace] function is called with the [Match] generated
+ /// by the pattern, and its result is used as replacement.
+ ///
+ /// The function defined below converts each word in a string to simplified
+ /// 'pig latin' using [replaceAllMapped]:
+ /// ```dart
+ /// pigLatin(String words) => words.replaceAllMapped(
+ /// RegExp(r'\b(\w*?)([aeiou]\w*)', caseSensitive: false),
+ /// (Match m) => "${m[2]}${m[1]}${m[1]!.isEmpty ? 'way' : 'ay'}");
+ ///
+ /// pigLatin('I have a secret now!'); // 'Iway avehay away ecretsay ownay!'
+ /// ```
String replaceAllMapped(Pattern from, String Function(Match match) replace);
- /**
- * Replaces the substring from [start] to [end] with [replacement].
- *
- * Returns a new string equivalent to:
- *
- * this.substring(0, start) + replacement + this.substring(end)
- *
- * The [start] and [end] indices must specify a valid range of this string.
- * That is `0 <= start <= end <= this.length`.
- * If [end] is `null`, it defaults to [length].
- */
+ /// Replaces the substring from [start] to [end] with [replacement].
+ ///
+ /// Creates a new string equivalent to:
+ /// ```dart
+ /// this.substring(0, start) + replacement + this.substring(end)
+ /// ```
+ /// The [start] and [end] indices must specify a valid range of this string.
+ /// That is `0 <= start <= end <= this.length`.
+ /// If [end] is `null`, it defaults to [length].
String replaceRange(int start, int? end, String replacement);
- /**
- * Splits the string at matches of [pattern] and returns a list of substrings.
- *
- * Finds all the matches of `pattern` in this string,
- * and returns the list of the substrings between the matches.
- *
- * var string = "Hello world!";
- * string.split(" "); // ['Hello', 'world!'];
- *
- * Empty matches at the beginning and end of the strings are ignored,
- * and so are empty matches right after another match.
- *
- * var string = "abba";
- * string.split(new RegExp(r"b*")); // ['a', 'a']
- * // not ['', 'a', 'a', '']
- *
- * If this string is empty, the result is an empty list if `pattern` matches
- * the empty string, and it is `[""]` if the pattern doesn't match.
- *
- * var string = '';
- * string.split(''); // []
- * string.split("a"); // ['']
- *
- * Splitting with an empty pattern splits the string into single-code unit
- * strings.
- *
- * var string = 'Pub';
- * string.split(''); // ['P', 'u', 'b']
- *
- * string.codeUnits.map((unit) {
- * return new String.fromCharCode(unit);
- * }).toList(); // ['P', 'u', 'b']
- *
- * Splitting happens at UTF-16 code unit boundaries,
- * and not at rune boundaries:
- *
- * // String made up of two code units, but one rune.
- * string = '\u{1D11E}';
- * string.split('').length; // 2 surrogate values
- *
- * To get a list of strings containing the individual runes of a string,
- * you should not use split. You can instead map each rune to a string
- * as follows:
- *
- * string.runes.map((rune) => new String.fromCharCode(rune)).toList();
- */
+ /// Splits the string at matches of [pattern] and returns a list of substrings.
+ ///
+ /// Finds all the matches of `pattern` in this string,
+ /// and returns the list of the substrings between the matches.
+ /// ```dart
+ /// var string = "Hello world!";
+ /// string.split(" "); // ['Hello', 'world!'];
+ /// ```
+ /// Empty matches at the beginning and end of the strings are ignored,
+ /// and so are empty matches right after another match.
+ /// ```dart
+ /// var string = "abba";
+ /// // Matches: ^^ ^^
+ /// string.split(RegExp(r"b*")); // ['a', 'a']
+ /// // not ['', 'a', 'a', '']
+ /// // not ['a', '', 'a']
+ /// ```
+ /// If this string is empty, the result is an empty list if `pattern` matches
+ /// the empty string, and it is `[""]` if the pattern doesn't match.
+ /// ```dart
+ /// var string = '';
+ /// string.split(''); // []
+ /// string.split("a"); // ['']
+ /// ```
+ /// Splitting with an empty pattern splits the string into single-code unit
+ /// strings.
+ /// ```dart
+ /// var string = 'Pub';
+ /// string.split(''); // ['P', 'u', 'b']
+ ///
+ /// string.codeUnits.map((unit) {
+ /// return String.fromCharCode(unit);
+ /// }).toList(); // ['P', 'u', 'b']
+ /// ```
+ /// Splitting happens at UTF-16 code unit boundaries,
+ /// and not at rune boundaries:
+ /// ```dart
+ /// // String made up of two code units, but one rune.
+ /// string = '\u{1D11E}';
+ /// string.split('').length; // 2 surrogate values
+ /// ```
+ /// To get a list of strings containing the individual runes of a string,
+ /// you should not use split. You can instead map each rune to a string
+ /// as follows:
+ /// ```dart
+ /// string.runes.map((rune) => String.fromCharCode(rune)).toList();
+ /// ```
List<String> split(Pattern pattern);
- /**
- * Splits the string, converts its parts, and combines them into a new
- * string.
- *
- * [pattern] is used to split the string into parts and separating matches.
- *
- * Each match is converted to a string by calling [onMatch]. If [onMatch]
- * is omitted, the matched string is used.
- *
- * Each non-matched part is converted by a call to [onNonMatch]. If
- * [onNonMatch] is omitted, the non-matching part is used.
- *
- * Then all the converted parts are combined into the resulting string.
- *
- * 'Eats shoots leaves'.splitMapJoin((new RegExp(r'shoots')),
- * onMatch: (m) => '${m.group(0)}',
- * onNonMatch: (n) => '*'); // *shoots*
- */
+ /// Splits the string, converts its parts, and combines them into a new
+ /// string.
+ ///
+ /// The [pattern] is used to split the string
+ /// into parts and separating matches.
+ ///
+ /// Each match is converted to a string by calling [onMatch]. If [onMatch]
+ /// is omitted, the matched substring is used.
+ ///
+ /// Each non-matched part is converted by a call to [onNonMatch]. If
+ /// [onNonMatch] is omitted, the non-matching substring is used.
+ ///
+ /// Then all the converted parts are combined into the resulting string.
+ /// ```dart
+ /// 'Eats shoots leaves'.splitMapJoin((RegExp(r'shoots')),
+ /// onMatch: (m) => '${m[0]!}', // or no onMatch at all
+ /// onNonMatch: (n) => '*'); // *shoots*
+ /// ```
String splitMapJoin(Pattern pattern,
{String Function(Match)? onMatch, String Function(String)? onNonMatch});
- /**
- * Returns an unmodifiable list of the UTF-16 code units of this string.
- */
+ /// An unmodifiable list of the UTF-16 code units of this string.
List<int> get codeUnits;
- /**
- * Returns an [Iterable] of Unicode code-points of this string.
- *
- * If the string contains surrogate pairs, they are combined and returned
- * as one integer by this iterator. Unmatched surrogate halves are treated
- * like valid 16-bit code-units.
- */
+ /// An [Iterable] of Unicode code-points of this string.
+ ///
+ /// If the string contains surrogate pairs, they are combined and returned
+ /// as one integer by this iterator. Unmatched surrogate halves are treated
+ /// like valid 16-bit code-units.
Runes get runes;
- /**
- * Converts all characters in this string to lower case.
- * If the string is already in all lower case, this method returns `this`.
- *
- * 'ALPHABET'.toLowerCase(); // 'alphabet'
- * 'abc'.toLowerCase(); // 'abc'
- *
- * This function uses the language independent Unicode mapping and thus only
- * works in some languages.
- */
+ /// Converts all characters in this string to lower case.
+ ///
+ /// If the string is already in all lower case, this method returns `this`.
+ /// ```dart
+ /// 'ALPHABET'.toLowerCase(); // 'alphabet'
+ /// 'abc'.toLowerCase(); // 'abc'
+ /// ```
+ /// This function uses the language independent Unicode mapping and thus only
+ /// works in some languages.
// TODO(floitsch): document better. (See EcmaScript for description).
String toLowerCase();
- /**
- * Converts all characters in this string to upper case.
- * If the string is already in all upper case, this method returns `this`.
- *
- * 'alphabet'.toUpperCase(); // 'ALPHABET'
- * 'ABC'.toUpperCase(); // 'ABC'
- *
- * This function uses the language independent Unicode mapping and thus only
- * works in some languages.
- */
+ /// Converts all characters in this string to upper case.
+ ///
+ /// If the string is already in all upper case, this method returns `this`.
+ /// ```dart
+ /// 'alphabet'.toUpperCase(); // 'ALPHABET'
+ /// 'ABC'.toUpperCase(); // 'ABC'
+ /// ```
+ /// This function uses the language independent Unicode mapping and thus only
+ /// works in some languages.
// TODO(floitsch): document better. (See EcmaScript for description).
String toUpperCase();
}
-/**
- * The runes (integer Unicode code points) of a [String].
- */
+/// The runes (integer Unicode code points) of a [String].
class Runes extends Iterable<int> {
+ /// The string that this is the runes of.
final String string;
+
+ /// Creates a [Runes] iterator for [string].
Runes(this.string);
RuneIterator get iterator => RuneIterator(string);
@@ -672,40 +627,37 @@
return 0x10000 + ((start & 0x3FF) << 10) + (end & 0x3FF);
}
-/**
- * [Iterator] for reading runes (integer Unicode code points) of a Dart string.
- */
+/// [Iterator] for reading runes (integer Unicode code points) of a Dart string.
class RuneIterator implements BidirectionalIterator<int> {
- /** String being iterated. */
+ /// String being iterated.
final String string;
- /** Position before the current code point. */
+
+ /// Position before the current code point.
int _position;
- /** Position after the current code point. */
+
+ /// Position after the current code point.
int _nextPosition;
- /**
- * Current code point.
- *
- * If the iterator has hit either end, the [_currentCodePoint] is -1
- * and `_position == _nextPosition`.
- */
+
+ /// Current code point.
+ ///
+ /// If the iterator has hit either end, the [_currentCodePoint] is -1
+ /// and `_position == _nextPosition`.
int _currentCodePoint = -1;
- /** Create an iterator positioned at the beginning of the string. */
+ /// Create an iterator positioned at the beginning of the string.
RuneIterator(String string)
: this.string = string,
_position = 0,
_nextPosition = 0;
- /**
- * Create an iterator positioned before the [index]th code unit of the string.
- *
- * When created, there is no [current] value.
- * A [moveNext] will use the rune starting at [index] the current value,
- * and a [movePrevious] will use the rune ending just before [index] as the
- * the current value.
- *
- * The [index] position must not be in the middle of a surrogate pair.
- */
+ /// Create an iterator positioned before the [index]th code unit of the string.
+ ///
+ /// When created, there is no [current] value.
+ /// A [moveNext] will use the rune starting at [index] the current value,
+ /// and a [movePrevious] will use the rune ending just before [index] as the
+ /// the current value.
+ ///
+ /// The [index] position must not be in the middle of a surrogate pair.
RuneIterator.at(String string, int index)
: string = string,
_position = index,
@@ -714,7 +666,7 @@
_checkSplitSurrogate(index);
}
- /** Throw an error if the index is in the middle of a surrogate pair. */
+ /// Throw an error if the index is in the middle of a surrogate pair.
void _checkSplitSurrogate(int index) {
if (index > 0 &&
index < string.length &&
@@ -724,40 +676,34 @@
}
}
- /**
- * The starting position of the current rune in the string.
- *
- * Returns -1 if there is no current rune ([current] is -1).
- */
+ /// The starting position of the current rune in the string.
+ ///
+ /// Returns -1 if there is no current rune ([current] is -1).
int get rawIndex => (_position != _nextPosition) ? _position : -1;
- /**
- * Resets the iterator to the rune at the specified index of the string.
- *
- * Setting a negative [rawIndex], or one greater than or equal to
- * `string.length`, is an error. So is setting it in the middle of a surrogate
- * pair.
- *
- * Setting the position to the end of then string means that there is no
- * current rune.
- */
+ /// Resets the iterator to the rune at the specified index of the string.
+ ///
+ /// Setting a negative [rawIndex], or one greater than or equal to
+ /// `string.length`, is an error. So is setting it in the middle of a surrogate
+ /// pair.
+ ///
+ /// Setting the position to the end of the string means that there is no
+ /// current rune.
void set rawIndex(int rawIndex) {
RangeError.checkValidIndex(rawIndex, string, "rawIndex");
reset(rawIndex);
moveNext();
}
- /**
- * Resets the iterator to the given index into the string.
- *
- * After this the [current] value is unset.
- * You must call [moveNext] make the rune at the position current,
- * or [movePrevious] for the last rune before the position.
- *
- * The [rawIndex] must be non-negative and no greater than `string.length`.
- * It must also not be the index of the trailing surrogate of a surrogate
- * pair.
- */
+ /// Resets the iterator to the given index into the string.
+ ///
+ /// After this the [current] value is unset.
+ /// You must call [moveNext] make the rune at the position current,
+ /// or [movePrevious] for the last rune before the position.
+ ///
+ /// The [rawIndex] must be non-negative and no greater than `string.length`.
+ /// It must also not be the index of the trailing surrogate of a surrogate
+ /// pair.
void reset([int rawIndex = 0]) {
RangeError.checkValueInInterval(rawIndex, 0, string.length, "rawIndex");
_checkSplitSurrogate(rawIndex);
@@ -765,29 +711,23 @@
_currentCodePoint = -1;
}
- /**
- * The rune (integer Unicode code point) starting at the current position in
- * the string.
- *
- * The value is -1 if there is no current code point.
- */
+ /// The rune (integer Unicode code point) starting at the current position in
+ /// the string.
+ ///
+ /// The value is -1 if there is no current code point.
int get current => _currentCodePoint;
- /**
- * The number of code units comprising the current rune.
- *
- * Returns zero if there is no current rune ([current] is -1).
- */
+ /// The number of code units comprising the current rune.
+ ///
+ /// Returns zero if there is no current rune ([current] is -1).
int get currentSize => _nextPosition - _position;
- /**
- * A string containing the current rune.
- *
- * For runes outside the basic multilingual plane, this will be
- * a String of length 2, containing two code units.
- *
- * Returns an empty string if there is no [current] value.
- */
+ /// A string containing the current rune.
+ ///
+ /// For runes outside the basic multilingual plane, this will be
+ /// a String of length 2, containing two code units.
+ ///
+ /// Returns an empty string if there is no [current] value.
String get currentAsString {
if (_position == _nextPosition) return "";
if (_position + 1 == _nextPosition) return string[_position];
diff --git a/sdk/lib/core/string_buffer.dart b/sdk/lib/core/string_buffer.dart
index d664101..6826e06 100644
--- a/sdk/lib/core/string_buffer.dart
+++ b/sdk/lib/core/string_buffer.dart
@@ -4,47 +4,45 @@
part of dart.core;
-/**
- * A class for concatenating strings efficiently.
- *
- * Allows for the incremental building of a string using write*() methods.
- * The strings are concatenated to a single string only when [toString] is
- * called.
- */
+/// A class for concatenating strings efficiently.
+///
+/// Allows for the incremental building of a string using `write*()` methods.
+/// The strings are concatenated to a single string only when [toString] is
+/// called.
class StringBuffer implements StringSink {
- /** Creates the string buffer with an initial content. */
+ /// Creates the string buffer with an initial content.
external StringBuffer([Object content = ""]);
- /**
- * Returns the length of the content that has been accumulated so far.
- * This is a constant-time operation.
- */
+ /// Returns the length of the content that has been accumulated so far.
+ /// This is a constant-time operation.
external int get length;
- /** Returns whether the buffer is empty. This is a constant-time operation. */
+ /// Returns whether the buffer is empty. This is a constant-time operation.
bool get isEmpty => length == 0;
- /**
- * Returns whether the buffer is not empty. This is a constant-time
- * operation.
- */
+ /// Returns whether the buffer is not empty. This is a constant-time
+ /// operation.
bool get isNotEmpty => !isEmpty;
- /// Adds the contents of [obj], converted to a string, to the buffer.
- external void write(Object? obj);
+ /// Adds the string representatoon of [object] to the buffer.
+ external void write(Object? object);
/// Adds the string representation of [charCode] to the buffer.
+ ///
+ /// Equivalent to `write(String.fromCharCode(charCode))`.
external void writeCharCode(int charCode);
+ /// Writes all [objects] separated by [separator].
+ ///
+ /// Writes each individual object in [objects] in iteration order,
+ /// and writes [separtor] between any two objects.
external void writeAll(Iterable<dynamic> objects, [String separator = ""]);
external void writeln([Object? obj = ""]);
- /**
- * Clears the string buffer.
- */
+ /// Clears the string buffer.
external void clear();
- /// Returns the contents of buffer as a concatenated string.
+ /// Returns the contents of buffer as a single string.
external String toString();
}
diff --git a/sdk/lib/core/string_sink.dart b/sdk/lib/core/string_sink.dart
index c507424..565ce56 100644
--- a/sdk/lib/core/string_sink.dart
+++ b/sdk/lib/core/string_sink.dart
@@ -5,27 +5,22 @@
part of dart.core;
abstract class StringSink {
- /**
- * Converts [obj] to a String by invoking [Object.toString] and
- * adds the result to `this`.
- */
- void write(Object? obj);
+ /// Writes the string representation of [object].
+ ///
+ /// Converts [object] to a string using `object.toString()`.
+ void write(Object? object);
- /**
- * Iterates over the given [objects] and [write]s them in sequence.
- */
+ /// Iterates over the given [objects] and [write]s them in sequence.
void writeAll(Iterable<dynamic> objects, [String separator = ""]);
- /**
- * Converts [obj] to a String by invoking [Object.toString] and
- * adds the result to `this`, followed by a newline.
- */
- void writeln([Object? obj = ""]);
+ /// Writes [object] followed by a newline, `"\n"`.
+ ///
+ /// Calling `writeln(null)` will write the `"null"` string before the
+ /// newline.
+ void writeln([Object? object = ""]);
- /**
- * Writes the [charCode] to `this`.
- *
- * This method is equivalent to `write(new String.fromCharCode(charCode))`.
- */
+ /// Writes the character represented by [charCode].
+ ///
+ /// Equivalent to `write(String.fromCharCode(charCode))`.
void writeCharCode(int charCode);
}
diff --git a/sdk/lib/core/symbol.dart b/sdk/lib/core/symbol.dart
index d64890a..d9e2540 100644
--- a/sdk/lib/core/symbol.dart
+++ b/sdk/lib/core/symbol.dart
@@ -6,92 +6,84 @@
/// Opaque name used by mirrors, invocations and [Function.apply].
abstract class Symbol {
- /** The symbol corresponding to the name of the unary minus operator. */
+ /// The symbol corresponding to the name of the unary minus operator.
static const Symbol unaryMinus = Symbol("unary-");
- /**
- * The empty symbol.
- *
- * The empty symbol is the name of libraries with no library declaration,
- * and the base-name of the unnamed constructor.
- */
+ /// The empty symbol.
+ ///
+ /// The empty symbol is the name of libraries with no library declaration,
+ /// and the base-name of the unnamed constructor.
static const Symbol empty = Symbol("");
- /**
- * Constructs a new [Symbol] representing the provided name.
- *
- * The name must be a valid public Dart member name,
- * public constructor name, or library name, optionally qualified.
- *
- * A qualified name is a valid name preceded by a public identifier name
- * and a '`.`', e.g., `foo.bar.baz=` is a qualified version of `baz=`.
- * That means that the content of the [name] String must be either
- *
- * * a valid public Dart identifier
- * (that is, an identifier not starting with "`_`"),
- * * such an identifier followed by "=" (a setter name),
- * * the name of a declarable operator
- * (one of "`+`", "`-`", "`*`", "`/`", "`%`", "`~/`", "`&`", "`|`",
- * "`^`", "`~`", "`<<`", "`>>`", "`<`", "`<=`", "`>`", "`>=`", "`==`",
- * "`[]`", "`[]=`", or "`unary-`"),
- * * any of the above preceded by any number of qualifiers,
- * where a qualifier is a non-private identifier followed by '`.`',
- * * or the empty string (the default name of a library with no library
- * name declaration).
- *
- * Symbol instances created from the same [name] are equal,
- * but not necessarily identical, but symbols created as compile-time
- * constants are canonicalized, as all other constant object creations.
- *
- * ```dart
- * assert(new Symbol("foo") == new Symbol("foo"));
- * assert(identical(const Symbol("foo"), const Symbol("foo")));
- * ```
- *
- * If [name] is a single identifier that does not start with an underscore,
- * or it is a qualified identifier,
- * or it is an operator name different from `unary-`,
- * then the result of `const Symbol(name)` is the same instance that
- * the symbol literal created by prefixing `#` to the content of [name]
- * would evaluate to.
- *
- * ```dart
- * assert(new Symbol("foo") == #foo);
- * assert(new Symbol("[]=") == #[]=]);
- * assert(new Symbol("foo.bar") == #foo.bar);
- * assert(identical(const Symbol("foo"), #foo));
- * assert(identical(const Symbol("[]="), #[]=));
- * assert(identical(const Symbol("foo.bar"), #foo.bar));
- * ```
- *
- * This constructor cannot create a [Symbol] instance that is equal to
- * a private symbol literal like `#_foo`.
- * ```dart
- * const Symbol("_foo") // Invalid
- * ```
- *
- * The created instance overrides [Object.==].
- *
- * The following text is non-normative:
- *
- * Creating non-const Symbol instances may result in larger output. If
- * possible, use `MirrorsUsed` from "dart:mirrors" to specify which names
- * might be passed to this constructor.
- */
+ /// Constructs a new [Symbol] representing the provided name.
+ ///
+ /// The name must be a valid public Dart member name,
+ /// public constructor name, or library name, optionally qualified.
+ ///
+ /// A qualified name is a valid name preceded by a public identifier name
+ /// and a '`.`', e.g., `foo.bar.baz=` is a qualified version of `baz=`.
+ /// That means that the content of the [name] String must be either
+ ///
+ /// * a valid public Dart identifier
+ /// (that is, an identifier not starting with "`_`"),
+ /// * such an identifier followed by "=" (a setter name),
+ /// * the name of a declarable operator
+ /// (one of "`+`", "`-`", "`*`", "`/`", "`%`", "`~/`", "`&`", "`|`",
+ /// "`^`", "`~`", "`<<`", "`>>`", "`<`", "`<=`", "`>`", "`>=`", "`==`",
+ /// "`[]`", "`[]=`", or "`unary-`"),
+ /// * any of the above preceded by any number of qualifiers,
+ /// where a qualifier is a non-private identifier followed by '`.`',
+ /// * or the empty string (the default name of a library with no library
+ /// name declaration).
+ ///
+ /// Symbol instances created from the same [name] are equal,
+ /// but not necessarily identical, but symbols created as compile-time
+ /// constants are canonicalized, as all other constant object creations.
+ ///
+ /// ```dart
+ /// assert(Symbol("foo") == Symbol("foo"));
+ /// assert(identical(const Symbol("foo"), const Symbol("foo")));
+ /// ```
+ ///
+ /// If [name] is a single identifier that does not start with an underscore,
+ /// or it is a qualified identifier,
+ /// or it is an operator name different from `unary-`,
+ /// then the result of `const Symbol(name)` is the same instance that
+ /// the symbol literal created by prefixing `#` to the content of [name]
+ /// would evaluate to.
+ ///
+ /// ```dart
+ /// assert(Symbol("foo") == #foo);
+ /// assert(Symbol("[]=") == #[]=]);
+ /// assert(Symbol("foo.bar") == #foo.bar);
+ /// assert(identical(const Symbol("foo"), #foo));
+ /// assert(identical(const Symbol("[]="), #[]=));
+ /// assert(identical(const Symbol("foo.bar"), #foo.bar));
+ /// ```
+ ///
+ /// This constructor cannot create a [Symbol] instance that is equal to
+ /// a private symbol literal like `#_foo`.
+ /// ```dart
+ /// const Symbol("_foo") // Invalid
+ /// ```
+ ///
+ /// The created instance overrides [Object.==].
+ ///
+ /// The following text is non-normative:
+ ///
+ /// Creating non-const Symbol instances may result in larger output. If
+ /// possible, use `MirrorsUsed` from "dart:mirrors" to specify which names
+ /// might be passed to this constructor.
const factory Symbol(String name) = internal.Symbol;
- /**
- * Returns a hash code compatible with [operator==].
- *
- * Equal symbols have the same hash code.
- */
+ /// Returns a hash code compatible with [operator==].
+ ///
+ /// Equal symbols have the same hash code.
int get hashCode;
- /**
- * Symbols are equal to other symbols that correspond to the same member name.
- *
- * Qualified member names, like `#foo.bar` are equal only if they have the
- * same identifiers before the same final member name.
- */
+ /// Symbols are equal to other symbols that correspond to the same member name.
+ ///
+ /// Qualified member names, like `#foo.bar` are equal only if they have the
+ /// same identifiers before the same final member name.
bool operator ==(Object other);
}
diff --git a/sdk/lib/core/type.dart b/sdk/lib/core/type.dart
index 65cef39..ebb9a5b 100644
--- a/sdk/lib/core/type.dart
+++ b/sdk/lib/core/type.dart
@@ -4,55 +4,47 @@
part of dart.core;
-/**
- * Runtime representation of a type.
- *
- * Type objects represent types.
- * A type object can be created in several ways:
- * * By a *type literal*, a type name occurring as an expression,
- * like `Type type = int;`,
- * or a type variable occurring as an expression, like `Type type = T;`.
- * * By reading the run-time type of an object,
- * like `Type type = o.runtimeType;`.
- * * Through `dart:mirrors`.
- *
- * A type object is intended as an entry point for using `dart:mirrors`.
- * The only operations supported are comparing to other type objects
- * for equality, and converting it to a string for debugging.
- */
+/// Runtime representation of a type.
+///
+/// Type objects represent types.
+/// A type object can be created in several ways:
+/// * By a *type literal*, a type name occurring as an expression,
+/// like `Type type = int;`,
+/// or a type variable occurring as an expression, like `Type type = T;`.
+/// * By reading the run-time type of an object,
+/// like `Type type = o.runtimeType;`.
+/// * Through `dart:mirrors`.
+///
+/// A type object is intended as an entry point for using `dart:mirrors`.
+/// The only operations supported are comparing to other type objects
+/// for equality, and converting it to a string for debugging.
abstract class Type {
- /**
- * A hash code for the type which is compatible with [operator==].
- */
+ /// A hash code for the type which is compatible with [operator==].
int get hashCode;
- /**
- * Whether [other] is a [Type] instance representing an equivalent type.
- *
- * The language specification dictates which types are considered
- * to be the equivalent.
- * If two types are equivalent, it's guaranteed that they are subtypes
- * of each other,
- * but there are also types which are subtypes of each other,
- * and which are not equivalent (for example `dynamic` and `void`,
- * or `FutureOr<Object>` and `Object`).
- */
+ /// Whether [other] is a [Type] instance representing an equivalent type.
+ ///
+ /// The language specification dictates which types are considered
+ /// to be the equivalent.
+ /// If two types are equivalent, it's guaranteed that they are subtypes
+ /// of each other,
+ /// but there are also types which are subtypes of each other,
+ /// and which are not equivalent (for example `dynamic` and `void`,
+ /// or `FutureOr<Object>` and `Object`).
bool operator ==(Object other);
- /**
- * Returns a string which represents the underlying type.
- *
- * The string is only intended for providing information to a reader
- * while debugging.
- * There is no guaranteed format,
- * the string value returned for a [Type] instances is entirely
- * implementation dependent.
- *
- * The string should be consistent, so a `Type` object for the *same* type
- * returns the same string throughout a program execution.
- * The string may or may not contain parts corresponding to the
- * source name of declaration of the type, if the type has a source name
- * at all (some types reachable through `dart:mirrors` may not).
- */
+ /// Returns a string which represents the underlying type.
+ ///
+ /// The string is only intended for providing information to a reader
+ /// while debugging.
+ /// There is no guaranteed format,
+ /// the string value returned for a [Type] instances is entirely
+ /// implementation dependent.
+ ///
+ /// The string should be consistent, so a `Type` object for the *same* type
+ /// returns the same string throughout a program execution.
+ /// The string may or may not contain parts corresponding to the
+ /// source name of declaration of the type, if the type has a source name
+ /// at all (some types reachable through `dart:mirrors` may not).
String toString();
}
diff --git a/sdk/lib/core/uri.dart b/sdk/lib/core/uri.dart
index daf7f67..5bae256 100644
--- a/sdk/lib/core/uri.dart
+++ b/sdk/lib/core/uri.dart
@@ -24,100 +24,94 @@
const String _hexDigits = "0123456789ABCDEF";
-/**
- * A parsed URI, such as a URL.
- *
- * **See also:**
- *
- * * [URIs][uris] in the [library tour][libtour]
- * * [RFC-3986](http://tools.ietf.org/html/rfc3986)
- *
- * [uris]: https://dart.dev/guides/libraries/library-tour#uris
- * [libtour]: https://dart.dev/guides/libraries/library-tour
- */
+/// A parsed URI, such as a URL.
+///
+/// **See also:**
+///
+/// * [URIs][uris] in the [library tour][libtour]
+/// * [RFC-3986](http://tools.ietf.org/html/rfc3986)
+///
+/// [uris]: https://dart.dev/guides/libraries/library-tour#uris
+/// [libtour]: https://dart.dev/guides/libraries/library-tour
abstract class Uri {
- /**
- * Returns the natural base URI for the current platform.
- *
- * When running in a browser this is the current URL of the current page
- * (from `window.location.href`).
- *
- * When not running in a browser this is the file URI referencing
- * the current working directory.
- */
+ /// The natural base URI for the current platform.
+ ///
+ /// When running in a browser this is the current URL of the current page
+ /// (from `window.location.href`).
+ ///
+ /// When not running in a browser this is the file URI referencing
+ /// the current working directory.
external static Uri get base;
- /**
- * Creates a new URI from its components.
- *
- * Each component is set through a named argument. Any number of
- * components can be provided. The [path] and [query] components can be set
- * using either of two different named arguments.
- *
- * The scheme component is set through [scheme]. The scheme is
- * normalized to all lowercase letters. If the scheme is omitted or empty,
- * the URI will not have a scheme part.
- *
- * The user info part of the authority component is set through
- * [userInfo]. It defaults to the empty string, which will be omitted
- * from the string representation of the URI.
- *
- * The host part of the authority component is set through
- * [host]. The host can either be a hostname, an IPv4 address or an
- * IPv6 address, contained in '[' and ']'. If the host contains a
- * ':' character, the '[' and ']' are added if not already provided.
- * The host is normalized to all lowercase letters.
- *
- * The port part of the authority component is set through
- * [port].
- * If [port] is omitted or `null`, it implies the default port for
- * the URI's scheme, and is equivalent to passing that port explicitly.
- * The recognized schemes, and their default ports, are "http" (80) and
- * "https" (443). All other schemes are considered as having zero as the
- * default port.
- *
- * If any of `userInfo`, `host` or `port` are provided,
- * the URI has an authority according to [hasAuthority].
- *
- * The path component is set through either [path] or
- * [pathSegments].
- * When [path] is used, it should be a valid URI path,
- * but invalid characters, except the general delimiters ':/@[]?#',
- * will be escaped if necessary.
- * When [pathSegments] is used, each of the provided segments
- * is first percent-encoded and then joined using the forward slash
- * separator.
- *
- * The percent-encoding of the path segments encodes all
- * characters except for the unreserved characters and the following
- * list of characters: `!$&'()*+,;=:@`. If the other components
- * necessitate an absolute path, a leading slash `/` is prepended if
- * not already there.
- *
- * The query component is set through either [query] or [queryParameters].
- * When [query] is used, the provided string should be a valid URI query,
- * but invalid characters, other than general delimiters,
- * will be escaped if necessary.
- * When [queryParameters] is used the query is built from the
- * provided map. Each key and value in the map is percent-encoded
- * and joined using equal and ampersand characters.
- * A value in the map must be either a string, or an [Iterable] of strings,
- * where the latter corresponds to multiple values for the same key.
- *
- * The percent-encoding of the keys and values encodes all characters
- * except for the unreserved characters, and replaces spaces with `+`.
- * If `query` is the empty string, it is equivalent to omitting it.
- * To have an actual empty query part,
- * use an empty map for `queryParameters`.
- *
- * If both `query` and `queryParameters` are omitted or `null`,
- * the URI has no query part.
- *
- * The fragment component is set through [fragment].
- * It should be a valid URI fragment, but invalid characters other than
- * general delimiters, are escaped if necessary.
- * If `fragment` is omitted or `null`, the URI has no fragment part.
- */
+ /// Creates a new URI from its components.
+ ///
+ /// Each component is set through a named argument. Any number of
+ /// components can be provided. The [path] and [query] components can be set
+ /// using either of two different named arguments.
+ ///
+ /// The scheme component is set through [scheme]. The scheme is
+ /// normalized to all lowercase letters. If the scheme is omitted or empty,
+ /// the URI will not have a scheme part.
+ ///
+ /// The user info part of the authority component is set through
+ /// [userInfo]. It defaults to the empty string, which will be omitted
+ /// from the string representation of the URI.
+ ///
+ /// The host part of the authority component is set through
+ /// [host]. The host can either be a hostname, an IPv4 address or an
+ /// IPv6 address, contained in '[' and ']'. If the host contains a
+ /// ':' character, the '[' and ']' are added if not already provided.
+ /// The host is normalized to all lowercase letters.
+ ///
+ /// The port part of the authority component is set through
+ /// [port].
+ /// If [port] is omitted or `null`, it implies the default port for
+ /// the URI's scheme, and is equivalent to passing that port explicitly.
+ /// The recognized schemes, and their default ports, are "http" (80) and
+ /// "https" (443). All other schemes are considered as having zero as the
+ /// default port.
+ ///
+ /// If any of `userInfo`, `host` or `port` are provided,
+ /// the URI has an authority according to [hasAuthority].
+ ///
+ /// The path component is set through either [path] or
+ /// [pathSegments].
+ /// When [path] is used, it should be a valid URI path,
+ /// but invalid characters, except the general delimiters ':/@[]?#',
+ /// will be escaped if necessary.
+ /// When [pathSegments] is used, each of the provided segments
+ /// is first percent-encoded and then joined using the forward slash
+ /// separator.
+ ///
+ /// The percent-encoding of the path segments encodes all
+ /// characters except for the unreserved characters and the following
+ /// list of characters: `!$&'()*+,;=:@`. If the other components
+ /// necessitate an absolute path, a leading slash `/` is prepended if
+ /// not already there.
+ ///
+ /// The query component is set through either [query] or [queryParameters].
+ /// When [query] is used, the provided string should be a valid URI query,
+ /// but invalid characters, other than general delimiters,
+ /// will be escaped if necessary.
+ /// When [queryParameters] is used the query is built from the
+ /// provided map. Each key and value in the map is percent-encoded
+ /// and joined using equal and ampersand characters.
+ /// A value in the map must be either a string, or an [Iterable] of strings,
+ /// where the latter corresponds to multiple values for the same key.
+ ///
+ /// The percent-encoding of the keys and values encodes all characters
+ /// except for the unreserved characters, and replaces spaces with `+`.
+ /// If `query` is the empty string, it is equivalent to omitting it.
+ /// To have an actual empty query part,
+ /// use an empty map for `queryParameters`.
+ ///
+ /// If both `query` and `queryParameters` are omitted or `null`,
+ /// the URI has no query part.
+ ///
+ /// The fragment component is set through [fragment].
+ /// It should be a valid URI fragment, but invalid characters other than
+ /// general delimiters, are escaped if necessary.
+ /// If `fragment` is omitted or `null`, the URI has no fragment part.
factory Uri(
{String? scheme,
String? userInfo,
@@ -129,173 +123,163 @@
Map<String, dynamic /*String|Iterable<String>*/ >? queryParameters,
String? fragment}) = _Uri;
- /**
- * Creates a new `http` URI from authority, path and query.
- *
- * Examples:
- *
- * ```
- * // http://example.org/path?q=dart.
- * new Uri.http("example.org", "/path", { "q" : "dart" });
- *
- * // http://user:pass@localhost:8080
- * new Uri.http("user:pass@localhost:8080", "");
- *
- * // http://example.org/a%20b
- * new Uri.http("example.org", "a b");
- *
- * // http://example.org/a%252F
- * new Uri.http("example.org", "/a%2F");
- * ```
- *
- * The `scheme` is always set to `http`.
- *
- * The `userInfo`, `host` and `port` components are set from the
- * [authority] argument. If `authority` is `null` or empty,
- * the created `Uri` has no authority, and isn't directly usable
- * as an HTTP URL, which must have a non-empty host.
- *
- * The `path` component is set from the [unencodedPath]
- * argument. The path passed must not be encoded as this constructor
- * encodes the path.
- *
- * The `query` component is set from the optional [queryParameters]
- * argument.
- */
+ /// Creates a new `http` URI from authority, path and query.
+ ///
+ /// Examples:
+ ///
+ /// ```
+ /// // http://example.org/path?q=dart.
+ /// Uri.http("example.org", "/path", { "q" : "dart" });
+ ///
+ /// // http://user:pass@localhost:8080
+ /// Uri.http("user:pass@localhost:8080", "");
+ ///
+ /// // http://example.org/a%20b
+ /// Uri.http("example.org", "a b");
+ ///
+ /// // http://example.org/a%252F
+ /// Uri.http("example.org", "/a%2F");
+ /// ```
+ ///
+ /// The `scheme` is always set to `http`.
+ ///
+ /// The `userInfo`, `host` and `port` components are set from the
+ /// [authority] argument. If `authority` is `null` or empty,
+ /// the created `Uri` has no authority, and isn't directly usable
+ /// as an HTTP URL, which must have a non-empty host.
+ ///
+ /// The `path` component is set from the [unencodedPath]
+ /// argument. The path passed must not be encoded as this constructor
+ /// encodes the path.
+ ///
+ /// The `query` component is set from the optional [queryParameters]
+ /// argument.
factory Uri.http(String authority, String unencodedPath,
[Map<String, dynamic>? queryParameters]) = _Uri.http;
- /**
- * Creates a new `https` URI from authority, path and query.
- *
- * This constructor is the same as [Uri.http] except for the scheme
- * which is set to `https`.
- */
+ /// Creates a new `https` URI from authority, path and query.
+ ///
+ /// This constructor is the same as [Uri.http] except for the scheme
+ /// which is set to `https`.
factory Uri.https(String authority, String unencodedPath,
[Map<String, dynamic>? queryParameters]) = _Uri.https;
- /**
- * Creates a new file URI from an absolute or relative file path.
- *
- * The file path is passed in [path].
- *
- * This path is interpreted using either Windows or non-Windows
- * semantics.
- *
- * With non-Windows semantics the slash (`/`) is used to separate
- * path segments in the input [path].
- *
- * With Windows semantics, backslash (`\`) and forward-slash (`/`)
- * are used to separate path segments in the input [path],
- * except if the path starts with `\\?\` in which case
- * only backslash (`\`) separates path segments in [path].
- *
- * If the path starts with a path separator, an absolute URI (with the
- * `file` scheme and an empty authority) is created.
- * Otherwise a relative URI reference with no scheme or authority is created.
- * One exception from this rule is that when Windows semantics is used
- * and the path starts with a drive letter followed by a colon (":") and a
- * path separator, then an absolute URI is created.
- *
- * The default for whether to use Windows or non-Windows semantics
- * determined from the platform Dart is running on. When running in
- * the standalone VM, this is detected by the VM based on the
- * operating system. When running in a browser non-Windows semantics
- * is always used.
- *
- * To override the automatic detection of which semantics to use pass
- * a value for [windows]. Passing `true` will use Windows
- * semantics and passing `false` will use non-Windows semantics.
- *
- * Examples using non-Windows semantics:
- *
- * ```
- * // xxx/yyy
- * new Uri.file("xxx/yyy", windows: false);
- *
- * // xxx/yyy/
- * new Uri.file("xxx/yyy/", windows: false);
- *
- * // file:///xxx/yyy
- * new Uri.file("/xxx/yyy", windows: false);
- *
- * // file:///xxx/yyy/
- * new Uri.file("/xxx/yyy/", windows: false);
- *
- * // C%3A
- * new Uri.file("C:", windows: false);
- * ```
- *
- * Examples using Windows semantics:
- *
- * ```
- * // xxx/yyy
- * new Uri.file(r"xxx\yyy", windows: true);
- *
- * // xxx/yyy/
- * new Uri.file(r"xxx\yyy\", windows: true);
- *
- * file:///xxx/yyy
- * new Uri.file(r"\xxx\yyy", windows: true);
- *
- * file:///xxx/yyy/
- * new Uri.file(r"\xxx\yyy/", windows: true);
- *
- * // file:///C:/xxx/yyy
- * new Uri.file(r"C:\xxx\yyy", windows: true);
- *
- * // This throws an error. A path with a drive letter, but no following
- * // path, is not allowed.
- * new Uri.file(r"C:", windows: true);
- *
- * // This throws an error. A path with a drive letter is not absolute.
- * new Uri.file(r"C:xxx\yyy", windows: true);
- *
- * // file://server/share/file
- * new Uri.file(r"\\server\share\file", windows: true);
- * ```
- *
- * If the path passed is not a valid file path, an error is thrown.
- */
+ /// Creates a new file URI from an absolute or relative file path.
+ ///
+ /// The file path is passed in [path].
+ ///
+ /// This path is interpreted using either Windows or non-Windows
+ /// semantics.
+ ///
+ /// With non-Windows semantics the slash (`/`) is used to separate
+ /// path segments in the input [path].
+ ///
+ /// With Windows semantics, backslash (`\`) and forward-slash (`/`)
+ /// are used to separate path segments in the input [path],
+ /// except if the path starts with `\\?\` in which case
+ /// only backslash (`\`) separates path segments in [path].
+ ///
+ /// If the path starts with a path separator, an absolute URI (with the
+ /// `file` scheme and an empty authority) is created.
+ /// Otherwise a relative URI reference with no scheme or authority is created.
+ /// One exception from this rule is that when Windows semantics is used
+ /// and the path starts with a drive letter followed by a colon (":") and a
+ /// path separator, then an absolute URI is created.
+ ///
+ /// The default for whether to use Windows or non-Windows semantics
+ /// determined from the platform Dart is running on. When running in
+ /// the standalone VM, this is detected by the VM based on the
+ /// operating system. When running in a browser non-Windows semantics
+ /// is always used.
+ ///
+ /// To override the automatic detection of which semantics to use pass
+ /// a value for [windows]. Passing `true` will use Windows
+ /// semantics and passing `false` will use non-Windows semantics.
+ ///
+ /// Examples using non-Windows semantics:
+ ///
+ /// ```
+ /// // xxx/yyy
+ /// Uri.file("xxx/yyy", windows: false);
+ ///
+ /// // xxx/yyy/
+ /// Uri.file("xxx/yyy/", windows: false);
+ ///
+ /// // file:///xxx/yyy
+ /// Uri.file("/xxx/yyy", windows: false);
+ ///
+ /// // file:///xxx/yyy/
+ /// Uri.file("/xxx/yyy/", windows: false);
+ ///
+ /// // C%3A
+ /// Uri.file("C:", windows: false);
+ /// ```
+ ///
+ /// Examples using Windows semantics:
+ ///
+ /// ```
+ /// // xxx/yyy
+ /// Uri.file(r"xxx\yyy", windows: true);
+ ///
+ /// // xxx/yyy/
+ /// Uri.file(r"xxx\yyy\", windows: true);
+ ///
+ /// file:///xxx/yyy
+ /// Uri.file(r"\xxx\yyy", windows: true);
+ ///
+ /// file:///xxx/yyy/
+ /// Uri.file(r"\xxx\yyy/", windows: true);
+ ///
+ /// // file:///C:/xxx/yyy
+ /// Uri.file(r"C:\xxx\yyy", windows: true);
+ ///
+ /// // This throws an error. A path with a drive letter, but no following
+ /// // path, is not allowed.
+ /// Uri.file(r"C:", windows: true);
+ ///
+ /// // This throws an error. A path with a drive letter is not absolute.
+ /// Uri.file(r"C:xxx\yyy", windows: true);
+ ///
+ /// // file://server/share/file
+ /// Uri.file(r"\\server\share\file", windows: true);
+ /// ```
+ ///
+ /// If the path passed is not a valid file path, an error is thrown.
factory Uri.file(String path, {bool? windows}) = _Uri.file;
- /**
- * Like [Uri.file] except that a non-empty URI path ends in a slash.
- *
- * If [path] is not empty, and it doesn't end in a directory separator,
- * then a slash is added to the returned URI's path.
- * In all other cases, the result is the same as returned by `Uri.file`.
- */
+ /// Like [Uri.file] except that a non-empty URI path ends in a slash.
+ ///
+ /// If [path] is not empty, and it doesn't end in a directory separator,
+ /// then a slash is added to the returned URI's path.
+ /// In all other cases, the result is the same as returned by `Uri.file`.
factory Uri.directory(String path, {bool? windows}) = _Uri.directory;
- /**
- * Creates a `data:` URI containing the [content] string.
- *
- * Converts the content to a bytes using [encoding] or the charset specified
- * in [parameters] (defaulting to US-ASCII if not specified or unrecognized),
- * then encodes the bytes into the resulting data URI.
- *
- * Defaults to encoding using percent-encoding (any non-ASCII or non-URI-valid
- * bytes is replaced by a percent encoding). If [base64] is true, the bytes
- * are instead encoded using [base64].
- *
- * If [encoding] is not provided and [parameters] has a `charset` entry,
- * that name is looked up using [Encoding.getByName],
- * and if the lookup returns an encoding, that encoding is used to convert
- * [content] to bytes.
- * If providing both an [encoding] and a charset in [parameters], they should
- * agree, otherwise decoding won't be able to use the charset parameter
- * to determine the encoding.
- *
- * If [mimeType] and/or [parameters] are supplied, they are added to the
- * created URI. If any of these contain characters that are not allowed
- * in the data URI, the character is percent-escaped. If the character is
- * non-ASCII, it is first UTF-8 encoded and then the bytes are percent
- * encoded. An omitted [mimeType] in a data URI means `text/plain`, just
- * as an omitted `charset` parameter defaults to meaning `US-ASCII`.
- *
- * To read the content back, use [UriData.contentAsString].
- */
+ /// Creates a `data:` URI containing the [content] string.
+ ///
+ /// Converts the content to a bytes using [encoding] or the charset specified
+ /// in [parameters] (defaulting to US-ASCII if not specified or unrecognized),
+ /// then encodes the bytes into the resulting data URI.
+ ///
+ /// Defaults to encoding using percent-encoding (any non-ASCII or non-URI-valid
+ /// bytes is replaced by a percent encoding). If [base64] is true, the bytes
+ /// are instead encoded using [base64].
+ ///
+ /// If [encoding] is not provided and [parameters] has a `charset` entry,
+ /// that name is looked up using [Encoding.getByName],
+ /// and if the lookup returns an encoding, that encoding is used to convert
+ /// [content] to bytes.
+ /// If providing both an [encoding] and a charset in [parameters], they should
+ /// agree, otherwise decoding won't be able to use the charset parameter
+ /// to determine the encoding.
+ ///
+ /// If [mimeType] and/or [parameters] are supplied, they are added to the
+ /// created URI. If any of these contain characters that are not allowed
+ /// in the data URI, the character is percent-escaped. If the character is
+ /// non-ASCII, it is first UTF-8 encoded and then the bytes are percent
+ /// encoded. An omitted [mimeType] in a data URI means `text/plain`, just
+ /// as an omitted `charset` parameter defaults to meaning `US-ASCII`.
+ ///
+ /// To read the content back, use [UriData.contentAsString].
factory Uri.dataFromString(String content,
{String? mimeType,
Encoding? encoding,
@@ -309,22 +293,20 @@
return data.uri;
}
- /**
- * Creates a `data:` URI containing an encoding of [bytes].
- *
- * Defaults to Base64 encoding the bytes, but if [percentEncoded]
- * is `true`, the bytes will instead be percent encoded (any non-ASCII
- * or non-valid-ASCII-character byte is replaced by a percent encoding).
- *
- * To read the bytes back, use [UriData.contentAsBytes].
- *
- * It defaults to having the mime-type `application/octet-stream`.
- * The [mimeType] and [parameters] are added to the created URI.
- * If any of these contain characters that are not allowed
- * in the data URI, the character is percent-escaped. If the character is
- * non-ASCII, it is first UTF-8 encoded and then the bytes are percent
- * encoded.
- */
+ /// Creates a `data:` URI containing an encoding of [bytes].
+ ///
+ /// Defaults to Base64 encoding the bytes, but if [percentEncoded]
+ /// is `true`, the bytes will instead be percent encoded (any non-ASCII
+ /// or non-valid-ASCII-character byte is replaced by a percent encoding).
+ ///
+ /// To read the bytes back, use [UriData.contentAsBytes].
+ ///
+ /// It defaults to having the mime-type `application/octet-stream`.
+ /// The [mimeType] and [parameters] are added to the created URI.
+ /// If any of these contain characters that are not allowed
+ /// in the data URI, the character is percent-escaped. If the character is
+ /// non-ASCII, it is first UTF-8 encoded and then the bytes are percent
+ /// encoded.
factory Uri.dataFromBytes(List<int> bytes,
{String mimeType = "application/octet-stream",
Map<String, String>? parameters,
@@ -336,183 +318,151 @@
return data.uri;
}
- /**
- * The scheme component of the URI.
- *
- * Returns the empty string if there is no scheme component.
- *
- * A URI scheme is case insensitive.
- * The returned scheme is canonicalized to lowercase letters.
- */
+ /// The scheme component of the URI.
+ ///
+ /// The value is the empty string if there is no scheme component.
+ ///
+ /// A URI scheme is case insensitive.
+ /// The returned scheme is canonicalized to lowercase letters.
String get scheme;
- /**
- * Returns the authority component.
- *
- * The authority is formatted from the [userInfo], [host] and [port]
- * parts.
- *
- * Returns the empty string if there is no authority component.
- */
+ /// The authority component.
+ ///
+ /// The authority is formatted from the [userInfo], [host] and [port]
+ /// parts.
+ ///
+ /// The valie is the empty string if there is no authority component.
String get authority;
- /**
- * Returns the user info part of the authority component.
- *
- * Returns the empty string if there is no user info in the
- * authority component.
- */
+ /// The user info part of the authority component.
+ ///
+ /// Th value is the empty string if there is no user info in the
+ /// authority component.
String get userInfo;
- /**
- * Returns the host part of the authority component.
- *
- * Returns the empty string if there is no authority component and
- * hence no host.
- *
- * If the host is an IP version 6 address, the surrounding `[` and `]` is
- * removed.
- *
- * The host string is case-insensitive.
- * The returned host name is canonicalized to lower-case
- * with upper-case percent-escapes.
- */
+ /// The host part of the authority component.
+ ///
+ /// The value is the empty string if there is no authority component and
+ /// hence no host.
+ ///
+ /// If the host is an IP version 6 address, the surrounding `[` and `]` is
+ /// removed.
+ ///
+ /// The host string is case-insensitive.
+ /// The returned host name is canonicalized to lower-case
+ /// with upper-case percent-escapes.
String get host;
- /**
- * Returns the port part of the authority component.
- *
- * Returns the default port if there is no port number in the authority
- * component. That's 80 for http, 443 for https, and 0 for everything else.
- */
+ /// The port part of the authority component.
+ ///
+ /// The value is the default port if there is no port number in the authority
+ /// component. That's 80 for http, 443 for https, and 0 for everything else.
int get port;
- /**
- * Returns the path component.
- *
- * The returned path is encoded. To get direct access to the decoded
- * path use [pathSegments].
- *
- * Returns the empty string if there is no path component.
- */
+ /// The path component.
+ ///
+ /// The path is the actual substring of the URI representing the path,
+ /// and it is encoded where necessary. To get direct access to the decoded
+ /// path use [pathSegments].
+ ///
+ /// The path value is the empty string if there is no path component.
String get path;
- /**
- * Returns the query component. The returned query is encoded. To get
- * direct access to the decoded query use [queryParameters].
- *
- * Returns the empty string if there is no query component.
- */
+ /// The query component.
+ ///
+ /// The value is the actual substring of the URI representing the query part,
+ /// and it is encoded where necessary.
+ /// To get direct access to the decoded query use [queryParameters].
+ ///
+ /// The value is the empty string if there is no query component.
String get query;
- /**
- * Returns the fragment identifier component.
- *
- * Returns the empty string if there is no fragment identifier
- * component.
- */
+ /// The fragment identifier component.
+ ///
+ /// The value is the empty string if there is no fragment identifier
+ /// component.
String get fragment;
- /**
- * Returns the URI path split into its segments. Each of the segments in the
- * returned list have been decoded. If the path is empty the empty list will
- * be returned. A leading slash `/` does not affect the segments returned.
- *
- * The returned list is unmodifiable and will throw [UnsupportedError] on any
- * calls that would mutate it.
- */
+ /// The URI path split into its segments.
+ ///
+ /// Each of the segments in the list have been decoded.
+ /// If the path is empty the empty list will
+ /// be returned. A leading slash `/` does not affect the segments returned.
+ ///
+ /// The list is unmodifiable and will throw [UnsupportedError] on any
+ /// calls that would mutate it.
List<String> get pathSegments;
- /**
- * Returns the URI query split into a map according to the rules
- * specified for FORM post in the [HTML 4.01 specification section
- * 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
- * Each key and value in the returned map has been decoded.
- * If there is no query the empty map is returned.
- *
- * Keys in the query string that have no value are mapped to the
- * empty string.
- * If a key occurs more than once in the query string, it is mapped to
- * an arbitrary choice of possible value.
- * The [queryParametersAll] getter can provide a map
- * that maps keys to all of their values.
- *
- * The returned map is unmodifiable.
- */
+ /// The URI query split into a map according to the rules
+ /// specified for FORM post in the [HTML 4.01 specification section
+ /// 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
+ ///
+ /// Each key and value in the resulting map has been decoded.
+ /// If there is no query the empty map is returned.
+ ///
+ /// Keys in the query string that have no value are mapped to the
+ /// empty string.
+ /// If a key occurs more than once in the query string, it is mapped to
+ /// an arbitrary choice of possible value.
+ /// The [queryParametersAll] getter can provide a map
+ /// that maps keys to all of their values.
+ ///
+ /// The map is unmodifiable.
Map<String, String> get queryParameters;
- /**
- * Returns the URI query split into a map according to the rules
- * specified for FORM post in the [HTML 4.01 specification section
- * 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
- * Each key and value in the returned map has been decoded. If there is no
- * query the empty map is returned.
- *
- * Keys are mapped to lists of their values. If a key occurs only once,
- * its value is a singleton list. If a key occurs with no value, the
- * empty string is used as the value for that occurrence.
- *
- * The returned map and the lists it contains are unmodifiable.
- */
+ /// Returns the URI query split into a map according to the rules
+ /// specified for FORM post in the [HTML 4.01 specification section
+ /// 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
+ ///
+ /// Each key and value in the reulting map has been decoded. If there is no
+ /// query the map is empty.
+ ///
+ /// Keys are mapped to lists of their values. If a key occurs only once,
+ /// its value is a singleton list. If a key occurs with no value, the
+ /// empty string is used as the value for that occurrence.
+ ///
+ /// The map and the lists it contains are unmodifiable.
Map<String, List<String>> get queryParametersAll;
- /**
- * Returns whether the URI is absolute.
- *
- * A URI is an absolute URI in the sense of RFC 3986 if it has a scheme
- * and no fragment.
- */
+ /// Whether the URI is absolute.
+ ///
+ /// A URI is an absolute URI in the sense of RFC 3986 if it has a scheme
+ /// and no fragment.
bool get isAbsolute;
- /**
- * Returns whether the URI has a [scheme] component.
- */
+ /// Whether the URI has a [scheme] component.
bool get hasScheme => scheme.isNotEmpty;
- /**
- * Returns whether the URI has an [authority] component.
- */
+ /// Whether the URI has an [authority] component.
bool get hasAuthority;
- /**
- * Returns whether the URI has an explicit port.
- *
- * If the port number is the default port number
- * (zero for unrecognized schemes, with http (80) and https (443) being
- * recognized),
- * then the port is made implicit and omitted from the URI.
- */
+ /// Whether the URI has an explicit port.
+ ///
+ /// If the port number is the default port number
+ /// (zero for unrecognized schemes, with http (80) and https (443) being
+ /// recognized),
+ /// then the port is made implicit and omitted from the URI.
bool get hasPort;
- /**
- * Returns whether the URI has a query part.
- */
+ /// Whether the URI has a query part.
bool get hasQuery;
- /**
- * Returns whether the URI has a fragment part.
- */
+ /// Whether the URI has a fragment part.
bool get hasFragment;
- /**
- * Returns whether the URI has an empty path.
- */
+ /// Whether the URI has an empty path.
bool get hasEmptyPath;
- /**
- * Returns whether the URI has an absolute path (starting with '/').
- */
+ /// Whether the URI has an absolute path (starting with '/').
bool get hasAbsolutePath;
- /**
- * Returns the origin of the URI in the form scheme://host:port for the
- * schemes http and https.
- *
- * It is an error if the scheme is not "http" or "https", or if the host name
- * is missing or empty.
- *
- * See: http://www.w3.org/TR/2011/WD-html5-20110405/origin-0.html#origin
- */
+ /// Returns the origin of the URI in the form scheme://host:port for the
+ /// schemes http and https.
+ ///
+ /// It is an error if the scheme is not "http" or "https", or if the host name
+ /// is missing or empty.
+ ///
+ /// See: http://www.w3.org/TR/2011/WD-html5-20110405/origin-0.html#origin
String get origin;
/// Whether the scheme of this [Uri] is [scheme].
@@ -526,85 +476,81 @@
/// print(uri.isScheme("HTTP")); // Prints true.
/// ```
///
- /// A `null` or empty [scheme] string matches a URI with no scheme
+ /// An empty [scheme] string matches a URI with no scheme
/// (one where [hasScheme] returns false).
bool isScheme(String scheme);
- /**
- * Returns the file path from a file URI.
- *
- * The returned path has either Windows or non-Windows
- * semantics.
- *
- * For non-Windows semantics the slash ("/") is used to separate
- * path segments.
- *
- * For Windows semantics the backslash ("\\") separator is used to
- * separate path segments.
- *
- * If the URI is absolute the path starts with a path separator
- * unless Windows semantics is used and the first path segment is a
- * drive letter. When Windows semantics is used a host component in
- * the uri in interpreted as a file server and a UNC path is
- * returned.
- *
- * The default for whether to use Windows or non-Windows semantics
- * determined from the platform Dart is running on. When running in
- * the standalone VM this is detected by the VM based on the
- * operating system. When running in a browser non-Windows semantics
- * is always used.
- *
- * To override the automatic detection of which semantics to use pass
- * a value for [windows]. Passing `true` will use Windows
- * semantics and passing `false` will use non-Windows semantics.
- *
- * If the URI ends with a slash (i.e. the last path component is
- * empty) the returned file path will also end with a slash.
- *
- * With Windows semantics URIs starting with a drive letter cannot
- * be relative to the current drive on the designated drive. That is
- * for the URI `file:///c:abc` calling `toFilePath` will throw as a
- * path segment cannot contain colon on Windows.
- *
- * Examples using non-Windows semantics (resulting of calling
- * toFilePath in comment):
- *
- * Uri.parse("xxx/yyy"); // xxx/yyy
- * Uri.parse("xxx/yyy/"); // xxx/yyy/
- * Uri.parse("file:///xxx/yyy"); // /xxx/yyy
- * Uri.parse("file:///xxx/yyy/"); // /xxx/yyy/
- * Uri.parse("file:///C:"); // /C:
- * Uri.parse("file:///C:a"); // /C:a
- *
- * Examples using Windows semantics (resulting URI in comment):
- *
- * Uri.parse("xxx/yyy"); // xxx\yyy
- * Uri.parse("xxx/yyy/"); // xxx\yyy\
- * Uri.parse("file:///xxx/yyy"); // \xxx\yyy
- * Uri.parse("file:///xxx/yyy/"); // \xxx\yyy\
- * Uri.parse("file:///C:/xxx/yyy"); // C:\xxx\yyy
- * Uri.parse("file:C:xxx/yyy"); // Throws as a path segment
- * // cannot contain colon on Windows.
- * Uri.parse("file://server/share/file"); // \\server\share\file
- *
- * If the URI is not a file URI calling this throws
- * [UnsupportedError].
- *
- * If the URI cannot be converted to a file path calling this throws
- * [UnsupportedError].
- */
+ /// Creates a file path from a file URI.
+ ///
+ /// The returned path has either Windows or non-Windows
+ /// semantics.
+ ///
+ /// For non-Windows semantics the slash ("/") is used to separate
+ /// path segments.
+ ///
+ /// For Windows semantics the backslash ("\\") separator is used to
+ /// separate path segments.
+ ///
+ /// If the URI is absolute the path starts with a path separator
+ /// unless Windows semantics is used and the first path segment is a
+ /// drive letter. When Windows semantics is used a host component in
+ /// the uri in interpreted as a file server and a UNC path is
+ /// returned.
+ ///
+ /// The default for whether to use Windows or non-Windows semantics
+ /// determined from the platform Dart is running on. When running in
+ /// the standalone VM this is detected by the VM based on the
+ /// operating system. When running in a browser non-Windows semantics
+ /// is always used.
+ ///
+ /// To override the automatic detection of which semantics to use pass
+ /// a value for [windows]. Passing `true` will use Windows
+ /// semantics and passing `false` will use non-Windows semantics.
+ ///
+ /// If the URI ends with a slash (i.e. the last path component is
+ /// empty) the returned file path will also end with a slash.
+ ///
+ /// With Windows semantics URIs starting with a drive letter cannot
+ /// be relative to the current drive on the designated drive. That is
+ /// for the URI `file:///c:abc` calling `toFilePath` will throw as a
+ /// path segment cannot contain colon on Windows.
+ ///
+ /// Examples using non-Windows semantics (resulting of calling
+ /// toFilePath in comment):
+ /// ```dart
+ /// Uri.parse("xxx/yyy"); // xxx/yyy
+ /// Uri.parse("xxx/yyy/"); // xxx/yyy/
+ /// Uri.parse("file:///xxx/yyy"); // /xxx/yyy
+ /// Uri.parse("file:///xxx/yyy/"); // /xxx/yyy/
+ /// Uri.parse("file:///C:"); // /C:
+ /// Uri.parse("file:///C:a"); // /C:a
+ /// ```
+ /// Examples using Windows semantics (resulting URI in comment):
+ /// ```dart
+ /// Uri.parse("xxx/yyy"); // xxx\yyy
+ /// Uri.parse("xxx/yyy/"); // xxx\yyy\
+ /// Uri.parse("file:///xxx/yyy"); // \xxx\yyy
+ /// Uri.parse("file:///xxx/yyy/"); // \xxx\yyy\
+ /// Uri.parse("file:///C:/xxx/yyy"); // C:\xxx\yyy
+ /// Uri.parse("file:C:xxx/yyy"); // Throws as a path segment
+ /// // cannot contain colon on Windows.
+ /// Uri.parse("file://server/share/file"); // \\server\share\file
+ /// ```
+ /// If the URI is not a file URI calling this throws
+ /// [UnsupportedError].
+ ///
+ /// If the URI cannot be converted to a file path calling this throws
+ /// [UnsupportedError].
// TODO(lrn): Deprecate and move functionality to File class or similar.
// The core libraries should not worry about the platform.
String toFilePath({bool? windows});
- /**
- * Access the structure of a `data:` URI.
- *
- * Returns a [UriData] object for `data:` URIs and `null` for all other
- * URIs.
- * The [UriData] object can be used to access the media type and data
- * of a `data:` URI.
- */
+ /// Access the structure of a `data:` URI.
+ ///
+ /// Returns a [UriData] object for `data:` URIs and `null` for all other
+ /// URIs.
+ /// The [UriData] object can be used to access the media type and data
+ /// of a `data:` URI.
UriData? get data;
/// Returns a hash code computed as `toString().hashCode`.
@@ -616,49 +562,47 @@
/// A URI is equal to another URI with the same normalized representation.
bool operator ==(Object other);
- /// Returns the normalized string representation of the URI.
+ /// The normalized string representation of the URI.
String toString();
- /**
- * Returns a new `Uri` based on this one, but with some parts replaced.
- *
- * This method takes the same parameters as the [new Uri] constructor,
- * and they have the same meaning.
- *
- * At most one of [path] and [pathSegments] must be provided.
- * Likewise, at most one of [query] and [queryParameters] must be provided.
- *
- * Each part that is not provided will default to the corresponding
- * value from this `Uri` instead.
- *
- * This method is different from [Uri.resolve] which overrides in a
- * hierarchical manner,
- * and can instead replace each part of a `Uri` individually.
- *
- * Example:
- *
- * Uri uri1 = Uri.parse("a://b@c:4/d/e?f#g");
- * Uri uri2 = uri1.replace(scheme: "A", path: "D/E/E", fragment: "G");
- * print(uri2); // prints "a://b@c:4/D/E/E?f#G"
- *
- * This method acts similarly to using the `new Uri` constructor with
- * some of the arguments taken from this `Uri`. Example:
- *
- * Uri uri3 = new Uri(
- * scheme: "A",
- * userInfo: uri1.userInfo,
- * host: uri1.host,
- * port: uri1.port,
- * path: "D/E/E",
- * query: uri1.query,
- * fragment: "G");
- * print(uri3); // prints "a://b@c:4/D/E/E?f#G"
- * print(uri2 == uri3); // prints true.
- *
- * Using this method can be seen as a shorthand for the `Uri` constructor
- * call above, but may also be slightly faster because the parts taken
- * from this `Uri` need not be checked for validity again.
- */
+ /// Creates a new `Uri` based on this one, but with some parts replaced.
+ ///
+ /// This method takes the same parameters as the [Uri] constructor,
+ /// and they have the same meaning.
+ ///
+ /// At most one of [path] and [pathSegments] must be provided.
+ /// Likewise, at most one of [query] and [queryParameters] must be provided.
+ ///
+ /// Each part that is not provided will default to the corresponding
+ /// value from this `Uri` instead.
+ ///
+ /// This method is different from [Uri.resolve] which overrides in a
+ /// hierarchical manner,
+ /// and can instead replace each part of a `Uri` individually.
+ ///
+ /// Example:
+ /// ```dart
+ /// Uri uri1 = Uri.parse("a://b@c:4/d/e?f#g");
+ /// Uri uri2 = uri1.replace(scheme: "A", path: "D/E/E", fragment: "G");
+ /// print(uri2); // prints "a://b@c:4/D/E/E?f#G"
+ /// ```
+ /// This method acts similarly to using the `Uri` constructor with
+ /// some of the arguments taken from this `Uri`. Example:
+ /// ```dart
+ /// Uri uri3 = Uri(
+ /// scheme: "A",
+ /// userInfo: uri1.userInfo,
+ /// host: uri1.host,
+ /// port: uri1.port,
+ /// path: "D/E/E",
+ /// query: uri1.query,
+ /// fragment: "G");
+ /// print(uri3); // prints "a://b@c:4/D/E/E?f#G"
+ /// print(uri2 == uri3); // prints true.
+ /// ```
+ /// Using this method can be seen as a shorthand for the `Uri` constructor
+ /// call above, but may also be slightly faster because the parts taken
+ /// from this `Uri` need not be checked for validity again.
Uri replace(
{String? scheme,
String? userInfo,
@@ -670,69 +614,58 @@
Map<String, dynamic /*String|Iterable<String>*/ >? queryParameters,
String? fragment});
- /**
- * Returns a `Uri` that differs from this only in not having a fragment.
- *
- * If this `Uri` does not have a fragment, it is itself returned.
- */
+ /// Creates a `Uri` that differs from this only in not having a fragment.
+ ///
+ /// If this `Uri` does not have a fragment, it is itself returned.
Uri removeFragment();
- /**
- * Resolve [reference] as an URI relative to `this`.
- *
- * First turn [reference] into a URI using [Uri.parse]. Then resolve the
- * resulting URI relative to `this`.
- *
- * Returns the resolved URI.
- *
- * See [resolveUri] for details.
- */
+ /// Resolve [reference] as an URI relative to `this`.
+ ///
+ /// First turn [reference] into a URI using [Uri.parse]. Then resolve the
+ /// resulting URI relative to `this`.
+ ///
+ /// Returns the resolved URI.
+ ///
+ /// See [resolveUri] for details.
Uri resolve(String reference);
- /**
- * Resolve [reference] as an URI relative to `this`.
- *
- * Returns the resolved URI.
- *
- * The algorithm "Transform Reference" for resolving a reference is described
- * in [RFC-3986 Section 5](http://tools.ietf.org/html/rfc3986#section-5 "RFC-1123").
- *
- * Updated to handle the case where the base URI is just a relative path -
- * that is: when it has no scheme and no authority and the path does not start
- * with a slash.
- * In that case, the paths are combined without removing leading "..", and
- * an empty path is not converted to "/".
- */
+ /// Resolve [reference] as an URI relative to `this`.
+ ///
+ /// Returns the resolved URI.
+ ///
+ /// The algorithm "Transform Reference" for resolving a reference is described
+ /// in [RFC-3986 Section 5](http://tools.ietf.org/html/rfc3986#section-5 "RFC-1123").
+ ///
+ /// Updated to handle the case where the base URI is just a relative path -
+ /// that is: when it has no scheme and no authority and the path does not start
+ /// with a slash.
+ /// In that case, the paths are combined without removing leading "..", and
+ /// an empty path is not converted to "/".
Uri resolveUri(Uri reference);
- /**
- * Returns a URI where the path has been normalized.
- *
- * A normalized path does not contain `.` segments or non-leading `..`
- * segments.
- * Only a relative path with no scheme or authority may contain
- * leading `..` segments,
- * a path that starts with `/` will also drop any leading `..` segments.
- *
- * This uses the same normalization strategy as `new Uri().resolve(this)`.
- *
- * Does not change any part of the URI except the path.
- *
- * The default implementation of `Uri` always normalizes paths, so calling
- * this function has no effect.
- */
+ /// Returns a URI where the path has been normalized.
+ ///
+ /// A normalized path does not contain `.` segments or non-leading `..`
+ /// segments.
+ /// Only a relative path with no scheme or authority may contain
+ /// leading `..` segments,
+ /// a path that starts with `/` will also drop any leading `..` segments.
+ ///
+ /// This uses the same normalization strategy as `Uri().resolve(this)`.
+ ///
+ /// Does not change any part of the URI except the path.
+ ///
+ /// The default implementation of `Uri` always normalizes paths, so calling
+ /// this function has no effect.
Uri normalizePath();
- /**
- * Creates a new `Uri` object by parsing a URI string.
- *
- * If [start] and [end] are provided, they must specify a valid substring
- * of [uri], and only the substring from `start` to `end` is parsed as a URI.
- *
- * The [uri] must not be `null`.
- * If the [uri] string is not valid as a URI or URI reference,
- * a [FormatException] is thrown.
- */
+ /// Creates a new `Uri` object by parsing a URI string.
+ ///
+ /// If [start] and [end] are provided, they must specify a valid substring
+ /// of [uri], and only the substring from `start` to `end` is parsed as a URI.
+ ///
+ /// If the [uri] string is not valid as a URI or URI reference,
+ /// a [FormatException] is thrown.
static Uri parse(String uri, [int start = 0, int? end]) {
// This parsing will not validate percent-encoding, IPv6, etc.
// When done splitting into parts, it will call, e.g., [_makeFragment]
@@ -1024,15 +957,12 @@
pathStart, queryStart, fragmentStart, scheme);
}
- /**
- * Creates a new `Uri` object by parsing a URI string.
- *
- * If [start] and [end] are provided, they must specify a valid substring
- * of [uri], and only the substring from `start` to `end` is parsed as a URI.
- * The [uri] must not be `null`.
- *
- * Returns `null` if the [uri] string is not valid as a URI or URI reference.
- */
+ /// Creates a new `Uri` object by parsing a URI string.
+ ///
+ /// If [start] and [end] are provided, they must specify a valid substring
+ /// of [uri], and only the substring from `start` to `end` is parsed as a URI.
+ ///
+ /// Returns `null` if the [uri] string is not valid as a URI or URI reference.
static Uri? tryParse(String uri, [int start = 0, int? end]) {
// TODO: Optimize to avoid throwing-and-recatching.
try {
@@ -1042,32 +972,30 @@
}
}
- /**
- * Encode the string [component] using percent-encoding to make it
- * safe for literal use as a URI component.
- *
- * All characters except uppercase and lowercase letters, digits and
- * the characters `-_.!~*'()` are percent-encoded. This is the
- * set of characters specified in RFC 2396 and the which is
- * specified for the encodeUriComponent in ECMA-262 version 5.1.
- *
- * When manually encoding path segments or query components remember
- * to encode each part separately before building the path or query
- * string.
- *
- * For encoding the query part consider using
- * [encodeQueryComponent].
- *
- * To avoid the need for explicitly encoding use the [pathSegments]
- * and [queryParameters] optional named arguments when constructing
- * a [Uri].
- */
+ /// Encode the string [component] using percent-encoding to make it
+ /// safe for literal use as a URI component.
+ ///
+ /// All characters except uppercase and lowercase letters, digits and
+ /// the characters `-_.!~*'()` are percent-encoded. This is the
+ /// set of characters specified in RFC 2396 and the which is
+ /// specified for the encodeUriComponent in ECMA-262 version 5.1.
+ ///
+ /// When manually encoding path segments or query components remember
+ /// to encode each part separately before building the path or query
+ /// string.
+ ///
+ /// For encoding the query part consider using
+ /// [encodeQueryComponent].
+ ///
+ /// To avoid the need for explicitly encoding use the [pathSegments]
+ /// and [queryParameters] optional named arguments when constructing
+ /// a [Uri].
static String encodeComponent(String component) {
return _Uri._uriEncode(_Uri._unreserved2396Table, component, utf8, false);
}
/**
- * Encode the string [component] according to the HTML 4.01 rules
+ * Encodes the string [component] according to the HTML 4.01 rules
* for encoding the posting of a HTML form as a query string
* component.
*
@@ -1104,76 +1032,67 @@
return _Uri._uriEncode(_Uri._unreservedTable, component, encoding, true);
}
- /**
- * Decodes the percent-encoding in [encodedComponent].
- *
- * Note that decoding a URI component might change its meaning as
- * some of the decoded characters could be characters with are
- * delimiters for a given URI component type. Always split a URI
- * component using the delimiters for the component before decoding
- * the individual parts.
- *
- * For handling the [path] and [query] components consider using
- * [pathSegments] and [queryParameters] to get the separated and
- * decoded component.
- */
+ /// Decodes the percent-encoding in [encodedComponent].
+ ///
+ /// Note that decoding a URI component might change its meaning as
+ /// some of the decoded characters could be characters with are
+ /// delimiters for a given URI component type. Always split a URI
+ /// component using the delimiters for the component before decoding
+ /// the individual parts.
+ ///
+ /// For handling the [path] and [query] components consider using
+ /// [pathSegments] and [queryParameters] to get the separated and
+ /// decoded component.
static String decodeComponent(String encodedComponent) {
return _Uri._uriDecode(
encodedComponent, 0, encodedComponent.length, utf8, false);
}
- /**
- * Decodes the percent-encoding in [encodedComponent], converting
- * pluses to spaces.
- *
- * It will create a byte-list of the decoded characters, and then use
- * [encoding] to decode the byte-list to a String. The default encoding is
- * UTF-8.
- */
+ /// Decodes the percent-encoding in [encodedComponent], converting
+ /// pluses to spaces.
+ ///
+ /// It will create a byte-list of the decoded characters, and then use
+ /// [encoding] to decode the byte-list to a String. The default encoding is
+ /// UTF-8.
static String decodeQueryComponent(String encodedComponent,
{Encoding encoding = utf8}) {
return _Uri._uriDecode(
encodedComponent, 0, encodedComponent.length, encoding, true);
}
- /**
- * Encode the string [uri] using percent-encoding to make it
- * safe for literal use as a full URI.
- *
- * All characters except uppercase and lowercase letters, digits and
- * the characters `!#$&'()*+,-./:;=?@_~` are percent-encoded. This
- * is the set of characters specified in in ECMA-262 version 5.1 for
- * the encodeURI function .
- */
+ /// Encodes the string [uri] using percent-encoding to make it
+ /// safe for literal use as a full URI.
+ ///
+ /// All characters except uppercase and lowercase letters, digits and
+ /// the characters `!#$&'()*+,-./:;=?@_~` are percent-encoded. This
+ /// is the set of characters specified in in ECMA-262 version 5.1 for
+ /// the encodeURI function .
static String encodeFull(String uri) {
return _Uri._uriEncode(_Uri._encodeFullTable, uri, utf8, false);
}
- /**
- * Decodes the percent-encoding in [uri].
- *
- * Note that decoding a full URI might change its meaning as some of
- * the decoded characters could be reserved characters. In most
- * cases an encoded URI should be parsed into components using
- * [Uri.parse] before decoding the separate components.
- */
+ /// Decodes the percent-encoding in [uri].
+ ///
+ /// Note that decoding a full URI might change its meaning as some of
+ /// the decoded characters could be reserved characters. In most
+ /// cases an encoded URI should be parsed into components using
+ /// [Uri.parse] before decoding the separate components.
static String decodeFull(String uri) {
return _Uri._uriDecode(uri, 0, uri.length, utf8, false);
}
- /**
- * Returns the [query] split into a map according to the rules
- * specified for FORM post in the [HTML 4.01 specification section
- * 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
- * Each key and value in the returned map has been decoded. If the [query]
- * is the empty string an empty map is returned.
- *
- * Keys in the query string that have no value are mapped to the
- * empty string.
- *
- * Each query component will be decoded using [encoding]. The default encoding
- * is UTF-8.
- */
+ /// Splits the [query] into a map according to the rules
+ /// specified for FORM post in the [HTML 4.01 specification section
+ /// 17.13.4](http://www.w3.org/TR/REC-html40/interact/forms.html#h-17.13.4 "HTML 4.01 section 17.13.4").
+ ///
+ /// Each key and value in the returned map has been decoded. If the [query]
+ /// is the empty string an empty map is returned.
+ ///
+ /// Keys in the query string that have no value are mapped to the
+ /// empty string.
+ ///
+ /// Each query component will be decoded using [encoding]. The default encoding
+ /// is UTF-8.
static Map<String, String> splitQueryString(String query,
{Encoding encoding = utf8}) {
return query.split("&").fold({}, (map, element) {
@@ -1192,13 +1111,11 @@
});
}
- /**
- * Parse the [host] as an IP version 4 (IPv4) address, returning the address
- * as a list of 4 bytes in network byte order (big endian).
- *
- * Throws a [FormatException] if [host] is not a valid IPv4 address
- * representation.
- */
+ /// Parses the [host] as an IP version 4 (IPv4) address, returning the address
+ /// as a list of 4 bytes in network byte order (big endian).
+ ///
+ /// Throws a [FormatException] if [host] is not a valid IPv4 address
+ /// representation.
static List<int> parseIPv4Address(String host) =>
_parseIPv4Address(host, 0, host.length);
@@ -1244,23 +1161,23 @@
return result;
}
- /**
- * Parse the [host] as an IP version 6 (IPv6) address, returning the address
- * as a list of 16 bytes in network byte order (big endian).
- *
- * Throws a [FormatException] if [host] is not a valid IPv6 address
- * representation.
- *
- * Acts on the substring from [start] to [end]. If [end] is omitted, it
- * defaults ot the end of the string.
- *
- * Some examples of IPv6 addresses:
- * * `::1`
- * * `FEDC:BA98:7654:3210:FEDC:BA98:7654:3210`
- * * `3ffe:2a00:100:7031::1`
- * * `::FFFF:129.144.52.38`
- * * `2010:836B:4179::836B:4179`
- */
+ /// Parses the [host] as an IP version 6 (IPv6) address.
+ ///
+ /// Returns the address as a list of 16 bytes in network byte order
+ /// (big endian).
+ ///
+ /// Throws a [FormatException] if [host] is not a valid IPv6 address
+ /// representation.
+ ///
+ /// Acts on the substring from [start] to [end]. If [end] is omitted, it
+ /// defaults ot the end of the string.
+ ///
+ /// Some examples of IPv6 addresses:
+ /// * `::1`
+ /// * `FEDC:BA98:7654:3210:FEDC:BA98:7654:3210`
+ /// * `3ffe:2a00:100:7031::1`
+ /// * `::FFFF:129.144.52.38`
+ /// * `2010:836B:4179::836B:4179`
static List<int> parseIPv6Address(String host, [int start = 0, int? end]) {
end ??= host.length;
// An IPv6 address consists of exactly 8 parts of 1-4 hex digits, separated
@@ -1368,37 +1285,29 @@
// A valid scheme cannot be empty.
final String scheme;
- /**
- * The user-info part of the authority.
- *
- * Does not distinguish between an empty user-info and an absent one.
- * The value is always non-null.
- * Is considered absent if [_host] is `null`.
- */
+ /// The user-info part of the authority.
+ ///
+ /// Does not distinguish between an empty user-info and an absent one.
+ /// The value is always non-null.
+ /// Is considered absent if [_host] is `null`.
final String _userInfo;
- /**
- * The host name of the URI.
- *
- * Set to `null` if there is no authority in the URI.
- * The host name is the only mandatory part of an authority, so we use
- * it to mark whether an authority part was present or not.
- */
+ /// The host name of the URI.
+ ///
+ /// Set to `null` if there is no authority in the URI.
+ /// The host name is the only mandatory part of an authority, so we use
+ /// it to mark whether an authority part was present or not.
final String? _host;
- /**
- * The port number part of the authority.
- *
- * The port. Set to null if there is no port. Normalized to null if
- * the port is the default port for the scheme.
- */
+ /// The port number part of the authority.
+ ///
+ /// The port. Set to null if there is no port. Normalized to null if
+ /// the port is the default port for the scheme.
int? _port;
- /**
- * The path of the URI.
- *
- * Always non-null.
- */
+ /// The path of the URI.
+ ///
+ /// Always non-null.
final String path;
/// The query content, or null if there is no query.
@@ -1940,17 +1849,15 @@
return port;
}
- /**
- * Check and normalize a host name.
- *
- * If the host name starts and ends with '[' and ']', it is considered an
- * IPv6 address. If [strictIPv6] is false, the address is also considered
- * an IPv6 address if it contains any ':' character.
- *
- * If it is not an IPv6 address, it is case- and escape-normalized.
- * This escapes all characters not valid in a reg-name,
- * and converts all non-escape upper-case letters to lower-case.
- */
+ /// Check and normalize a host name.
+ ///
+ /// If the host name starts and ends with '[' and ']', it is considered an
+ /// IPv6 address. If [strictIPv6] is false, the address is also considered
+ /// an IPv6 address if it contains any ':' character.
+ ///
+ /// If it is not an IPv6 address, it is case- and escape-normalized.
+ /// This escapes all characters not valid in a reg-name,
+ /// and converts all non-escape upper-case letters to lower-case.
static String? _makeHost(String? host, int start, int end, bool strictIPv6) {
// TODO(lrn): Should we normalize IPv6 addresses according to RFC 5952?
if (host == null) return null;
@@ -2002,14 +1909,12 @@
return char < 127 && (_zoneIDTable[char >> 4] & (1 << (char & 0xf))) != 0;
}
- /**
- * Validates and does case- and percent-encoding normalization.
- *
- * The same as [_normalizeOrSubstring]
- * except this function does not convert characters to lower case.
- * The [host] must be an RFC6874 "ZoneID".
- * ZoneID = 1*(unreserved / pct-encoded)
- */
+ /// Validates and does case- and percent-encoding normalization.
+ ///
+ /// The same as [_normalizeOrSubstring]
+ /// except this function does not convert characters to lower case.
+ /// The [host] must be an RFC6874 "ZoneID".
+ /// ZoneID = 1*(unreserved / pct-encoded)
static String _normalizeZoneID(String host, int start, int end,
[String prefix = '']) {
StringBuffer? buffer;
@@ -2080,13 +1985,11 @@
return char < 127 && (_regNameTable[char >> 4] & (1 << (char & 0xf))) != 0;
}
- /**
- * Validates and does case- and percent-encoding normalization.
- *
- * The [host] must be an RFC3986 "reg-name". It is converted
- * to lower case, and percent escapes are converted to either
- * lower case unreserved characters or upper case escapes.
- */
+ /// Validates and does case- and percent-encoding normalization.
+ ///
+ /// The [host] must be an RFC3986 "reg-name". It is converted
+ /// to lower case, and percent escapes are converted to either
+ /// lower case unreserved characters or upper case escapes.
static String _normalizeRegName(String host, int start, int end) {
StringBuffer? buffer;
int sectionStart = start;
@@ -2156,11 +2059,9 @@
return buffer.toString();
}
- /**
- * Validates scheme characters and does case-normalization.
- *
- * Schemes are converted to lower case. They cannot contain escapes.
- */
+ /// Validates scheme characters and does case-normalization.
+ ///
+ /// Schemes are converted to lower case. They cannot contain escapes.
static String _makeScheme(String scheme, int start, int end) {
if (start == end) return "";
final int firstCodeUnit = scheme.codeUnitAt(start);
@@ -2278,19 +2179,17 @@
escapeDelimiters: true);
}
- /**
- * Performs RFC 3986 Percent-Encoding Normalization.
- *
- * Returns a replacement string that should be replace the original escape.
- * Returns null if no replacement is necessary because the escape is
- * not for an unreserved character and is already non-lower-case.
- *
- * Returns "%" if the escape is invalid (not two valid hex digits following
- * the percent sign). The calling code should replace the percent
- * sign with "%25", but leave the following two characters unmodified.
- *
- * If [lowerCase] is true, a single character returned is always lower case,
- */
+ /// Performs RFC 3986 Percent-Encoding Normalization.
+ ///
+ /// Returns a replacement string that should be replace the original escape.
+ /// Returns null if no replacement is necessary because the escape is
+ /// not for an unreserved character and is already non-lower-case.
+ ///
+ /// Returns "%" if the escape is invalid (not two valid hex digits following
+ /// the percent sign). The calling code should replace the percent
+ /// sign with "%25", but leave the following two characters unmodified.
+ ///
+ /// If [lowerCase] is true, a single character returned is always lower case,
static String? _normalizeEscape(String source, int index, bool lowerCase) {
assert(source.codeUnitAt(index) == _PERCENT);
if (index + 2 >= source.length) {
@@ -2354,12 +2253,10 @@
return String.fromCharCodes(codeUnits);
}
- /**
- * Normalizes using [_normalize] or returns substring of original.
- *
- * If [_normalize] returns `null` (original content is already normalized),
- * this methods returns the substring if [component] from [start] to [end].
- */
+ /// Normalizes using [_normalize] or returns substring of original.
+ ///
+ /// If [_normalize] returns `null` (original content is already normalized),
+ /// this methods returns the substring if [component] from [start] to [end].
static String _normalizeOrSubstring(
String component, int start, int end, List<int> charTable,
{bool escapeDelimiters = false}) {
@@ -2368,17 +2265,15 @@
component.substring(start, end);
}
- /**
- * Runs through component checking that each character is valid and
- * normalize percent escapes.
- *
- * Uses [charTable] to check if a non-`%` character is allowed.
- * Each `%` character must be followed by two hex digits.
- * If the hex-digits are lower case letters, they are converted to
- * upper case.
- *
- * Returns `null` if the original content was already normalized.
- */
+ /// Runs through component checking that each character is valid and
+ /// normalize percent escapes.
+ ///
+ /// Uses [charTable] to check if a non-`%` character is allowed.
+ /// Each `%` character must be followed by two hex digits.
+ /// If the hex-digits are lower case letters, they are converted to
+ /// upper case.
+ ///
+ /// Returns `null` if the original content was already normalized.
static String? _normalize(
String component, int start, int end, List<int> charTable,
{bool escapeDelimiters = false}) {
@@ -2450,9 +2345,7 @@
((_genDelimitersTable[ch >> 4] & (1 << (ch & 0x0f))) != 0);
}
- /**
- * Returns whether the URI is absolute.
- */
+ /// Whether the URI is absolute.
bool get isAbsolute => scheme != "" && fragment == "";
String _mergePaths(String base, String reference) {
@@ -2775,14 +2668,12 @@
}
}
- /**
- * Access the structure of a `data:` URI.
- *
- * Returns a [UriData] object for `data:` URIs and `null` for all other
- * URIs.
- * The [UriData] object can be used to access the media type and data
- * of a `data:` URI.
- */
+ /// Access the structure of a `data:` URI.
+ ///
+ /// Returns a [UriData] object for `data:` URIs and `null` for all other
+ /// URIs.
+ /// The [UriData] object can be used to access the media type and data
+ /// of a `data:` URI.
UriData? get data => (scheme == "data") ? UriData.fromUri(this) : null;
String toString() => _text;
@@ -2858,10 +2749,8 @@
external static String _uriEncode(List<int> canonicalTable, String text,
Encoding encoding, bool spaceToPlus);
- /**
- * Convert a byte (2 character hex sequence) in string [s] starting
- * at position [pos] to its ordinal value
- */
+ /// Convert a byte (2 character hex sequence) in string [s] starting
+ /// at position [pos] to its ordinal value
static int _hexCharPairToByte(String s, int pos) {
int byte = 0;
for (int i = 0; i < 2; i++) {
@@ -2881,18 +2770,16 @@
return byte;
}
- /**
- * Uri-decode a percent-encoded string.
- *
- * It unescapes the string [text] and returns the unescaped string.
- *
- * This function is similar to the JavaScript-function `decodeURI`.
- *
- * If [plusToSpace] is `true`, plus characters will be converted to spaces.
- *
- * The decoder will create a byte-list of the percent-encoded parts, and then
- * decode the byte-list using [encoding]. The default encodings UTF-8.
- */
+ /// Uri-decode a percent-encoded string.
+ ///
+ /// It unescapes the string [text] and returns the unescaped string.
+ ///
+ /// This function is similar to the JavaScript-function `decodeURI`.
+ ///
+ /// If [plusToSpace] is `true`, plus characters will be converted to spaces.
+ ///
+ /// The decoder will create a byte-list of the percent-encoded parts, and then
+ /// decode the byte-list using [encoding]. The default encodings UTF-8.
static String _uriDecode(
String text, int start, int end, Encoding encoding, bool plusToSpace) {
assert(0 <= start);
@@ -3191,52 +3078,45 @@
// Data URI
// --------------------------------------------------------------------
-/**
- * A way to access the structure of a `data:` URI.
- *
- * Data URIs are non-hierarchical URIs that can contain any binary data.
- * They are defined by [RFC 2397](https://tools.ietf.org/html/rfc2397).
- *
- * This class allows parsing the URI text and extracting individual parts of the
- * URI, as well as building the URI text from structured parts.
- */
+/// A way to access the structure of a `data:` URI.
+///
+/// Data URIs are non-hierarchical URIs that can contain any binary data.
+/// They are defined by [RFC 2397](https://tools.ietf.org/html/rfc2397).
+///
+/// This class allows parsing the URI text and extracting individual parts of the
+/// URI, as well as building the URI text from structured parts.
class UriData {
static const int _noScheme = -1;
- /**
- * Contains the text content of a `data:` URI, with or without a
- * leading `data:`.
- *
- * If [_separatorIndices] starts with `4` (the index of the `:`), then
- * there is a leading `data:`, otherwise [_separatorIndices] starts with
- * `-1`.
- */
+
+ /// Contains the text content of a `data:` URI, with or without a
+ /// leading `data:`.
+ ///
+ /// If [_separatorIndices] starts with `4` (the index of the `:`), then
+ /// there is a leading `data:`, otherwise [_separatorIndices] starts with
+ /// `-1`.
final String _text;
- /**
- * List of the separators (';', '=' and ',') in the text.
- *
- * Starts with the index of the `:` in `data:` of the mimeType.
- * That is always either -1 or 4, depending on whether `_text` includes the
- * `data:` scheme or not.
- *
- * The first speparator ends the mime type. We don't bother with finding
- * the '/' inside the mime type.
- *
- * Each two separators after that marks a parameter key and value.
- *
- * If there is a single separator left, it ends the "base64" marker.
- *
- * So the following separators are found for a text:
- * ```
- * data:text/plain;foo=bar;base64,ARGLEBARGLE=
- * ^ ^ ^ ^ ^
- * ```
- */
+ /// List of the separators (';', '=' and ',') in the text.
+ ///
+ /// Starts with the index of the `:` in `data:` of the mimeType.
+ /// That is always either -1 or 4, depending on whether `_text` includes the
+ /// `data:` scheme or not.
+ ///
+ /// The first speparator ends the mime type. We don't bother with finding
+ /// the '/' inside the mime type.
+ ///
+ /// Each two separators after that marks a parameter key and value.
+ ///
+ /// If there is a single separator left, it ends the "base64" marker.
+ ///
+ /// So the following separators are found for a text:
+ /// ```
+ /// data:text/plain;foo=bar;base64,ARGLEBARGLE=
+ /// ^ ^ ^ ^ ^
+ /// ```
final List<int> _separatorIndices;
- /**
- * Cache of the result returned by [uri].
- */
+ /// Cache of the result returned by [uri].
Uri? _uriCache;
UriData._(this._text, this._separatorIndices, this._uriCache);
@@ -3244,12 +3124,10 @@
// Avoid shadowing by argument.
static const Base64Codec _base64 = base64;
- /**
- * Creates a `data:` URI containing the [content] string.
- *
- * Equivalent to `new Uri.dataFromString(...).data`, but may
- * be more efficient if the [uri] itself isn't used.
- */
+ /// Creates a `data:` URI containing the [content] string.
+ ///
+ /// Equivalent to `Uri.dataFromString(...).data`, but may
+ /// be more efficient if the [uri] itself isn't used.
factory UriData.fromString(String content,
{String? mimeType,
Encoding? encoding,
@@ -3281,12 +3159,10 @@
return UriData._(buffer.toString(), indices, null);
}
- /**
- * Creates a `data:` URI containing an encoding of [bytes].
- *
- * Equivalent to `new Uri.dataFromBytes(...).data`, but may
- * be more efficient if the [uri] itself isn't used.
- */
+ /// Creates a `data:` URI containing an encoding of [bytes].
+ ///
+ /// Equivalent to `Uri.dataFromBytes(...).data`, but may
+ /// be more efficient if the [uri] itself isn't used.
factory UriData.fromBytes(List<int> bytes,
{String mimeType = "application/octet-stream",
Map<String, String>? parameters,
@@ -3309,13 +3185,11 @@
return UriData._(buffer.toString(), indices, null);
}
- /**
- * Creates a `DataUri` from a [Uri] which must have `data` as [Uri.scheme].
- *
- * The [uri] must have scheme `data` and no authority or fragment,
- * and the path (concatenated with the query, if there is one) must be valid
- * as data URI content with the same rules as [parse].
- */
+ /// Creates a `DataUri` from a [Uri] which must have `data` as [Uri.scheme].
+ ///
+ /// The [uri] must have scheme `data` and no authority or fragment,
+ /// and the path (concatenated with the query, if there is one) must be valid
+ /// as data URI content with the same rules as [parse].
factory UriData.fromUri(Uri uri) {
if (uri.scheme != "data") {
throw ArgumentError.value(uri, "uri", "Scheme must be 'data'");
@@ -3334,14 +3208,12 @@
return _parse(uri.toString(), 5, uri);
}
- /**
- * Writes the initial part of a `data:` uri, from after the "data:"
- * until just before the ',' before the data, or before a `;base64,`
- * marker.
- *
- * Of an [indices] list is passed, separator indices are stored in that
- * list.
- */
+ /// Writes the initial part of a `data:` uri, from after the "data:"
+ /// until just before the ',' before the data, or before a `;base64,`
+ /// marker.
+ ///
+ /// Of an [indices] list is passed, separator indices are stored in that
+ /// list.
static void _writeUri(
String? mimeType,
String? charsetName,
@@ -3389,15 +3261,13 @@
});
}
- /**
- * Checks mimeType is valid-ish (`token '/' token`).
- *
- * Returns the index of the slash, or -1 if the mime type is not
- * considered valid.
- *
- * Currently only looks for slashes, all other characters will be
- * percent-encoded as UTF-8 if necessary.
- */
+ /// Checks mimeType is valid-ish (`token '/' token`).
+ ///
+ /// Returns the index of the slash, or -1 if the mime type is not
+ /// considered valid.
+ ///
+ /// Currently only looks for slashes, all other characters will be
+ /// percent-encoded as UTF-8 if necessary.
static int _validateMimeType(String mimeType) {
int slashIndex = -1;
for (int i = 0; i < mimeType.length; i++) {
@@ -3412,34 +3282,32 @@
return slashIndex;
}
- /**
- * Parses a string as a `data` URI.
- *
- * The string must have the format:
- *
- * ```
- * 'data:' (type '/' subtype)? (';' attribute '=' value)* (';base64')? ',' data
- * ````
- *
- * where `type`, `subtype`, `attribute` and `value` are specified in RFC-2045,
- * and `data` is a sequence of URI-characters (RFC-2396 `uric`).
- *
- * This means that all the characters must be ASCII, but the URI may contain
- * percent-escapes for non-ASCII byte values that need an interpretation
- * to be converted to the corresponding string.
- *
- * Parsing checks that Base64 encoded data is valid, and it normalizes it
- * to use the default Base64 alphabet and to use padding.
- * Non-Base64 data is escaped using percent-escapes as necessary to make
- * it valid, and existing escapes are case normalized.
- *
- * Accessing the individual parts may fail later if they turn out to have
- * content that can't be decoded successfully as a string, for example if
- * existing percent escapes represent bytes that cannot be decoded
- * by the chosen [Encoding] (see [contentAsString]).
- *
- * A [FormatException] is thrown if [uri] is not a valid data URI.
- */
+ /// Parses a string as a `data` URI.
+ ///
+ /// The string must have the format:
+ ///
+ /// ```
+ /// 'data:' (type '/' subtype)? (';' attribute '=' value)* (';base64')? ',' data
+ /// ````
+ ///
+ /// where `type`, `subtype`, `attribute` and `value` are specified in RFC-2045,
+ /// and `data` is a sequence of URI-characters (RFC-2396 `uric`).
+ ///
+ /// This means that all the characters must be ASCII, but the URI may contain
+ /// percent-escapes for non-ASCII byte values that need an interpretation
+ /// to be converted to the corresponding string.
+ ///
+ /// Parsing checks that Base64 encoded data is valid, and it normalizes it
+ /// to use the default Base64 alphabet and to use padding.
+ /// Non-Base64 data is escaped using percent-escapes as necessary to make
+ /// it valid, and existing escapes are case normalized.
+ ///
+ /// Accessing the individual parts may fail later if they turn out to have
+ /// content that can't be decoded successfully as a string, for example if
+ /// existing percent escapes represent bytes that cannot be decoded
+ /// by the chosen [Encoding] (see [contentAsString]).
+ ///
+ /// A [FormatException] is thrown if [uri] is not a valid data URI.
static UriData parse(String uri) {
if (uri.length >= 5) {
int dataDelta = _startsWithData(uri, 0);
@@ -3456,12 +3324,10 @@
throw FormatException("Does not start with 'data:'", uri, 0);
}
- /**
- * The [Uri] that this `UriData` is giving access to.
- *
- * Returns a `Uri` with scheme `data` and the remainder of the data URI
- * as path.
- */
+ /// The [Uri] that this `UriData` is giving access to.
+ ///
+ /// Returns a `Uri` with scheme `data` and the remainder of the data URI
+ /// as path.
Uri get uri {
return _uriCache ??= _computeUri();
}
@@ -3482,26 +3348,24 @@
return _DataUri(this, path, query);
}
- /**
- * The MIME type of the data URI.
- *
- * A data URI consists of a "media type" followed by data.
- * The media type starts with a MIME type and can be followed by
- * extra parameters.
- * If the MIME type representation in the URI text contains URI escapes,
- * they are unescaped in the returned string.
- * If the value contain non-ASCII percent escapes, they are decoded as UTF-8.
- *
- * Example:
- *
- * data:text/plain;charset=utf-8,Hello%20World!
- *
- * This data URI has the media type `text/plain;charset=utf-8`, which is the
- * MIME type `text/plain` with the parameter `charset` with value `utf-8`.
- * See [RFC 2045](https://tools.ietf.org/html/rfc2045) for more detail.
- *
- * If the first part of the data URI is empty, it defaults to `text/plain`.
- */
+ /// The MIME type of the data URI.
+ ///
+ /// A data URI consists of a "media type" followed by data.
+ /// The media type starts with a MIME type and can be followed by
+ /// extra parameters.
+ /// If the MIME type representation in the URI text contains URI escapes,
+ /// they are unescaped in the returned string.
+ /// If the value contain non-ASCII percent escapes, they are decoded as UTF-8.
+ ///
+ /// Example:
+ /// ```dart
+ /// data:text/plain;charset=utf-8,Hello%20World!
+ /// ```
+ /// This data URI has the media type `text/plain;charset=utf-8`, which is the
+ /// MIME type `text/plain` with the parameter `charset` with value `utf-8`.
+ /// See [RFC 2045](https://tools.ietf.org/html/rfc2045) for more detail.
+ ///
+ /// If the first part of the data URI is empty, it defaults to `text/plain`.
String get mimeType {
int start = _separatorIndices[0] + 1;
int end = _separatorIndices[1];
@@ -3509,17 +3373,15 @@
return _Uri._uriDecode(_text, start, end, utf8, false);
}
- /**
- * The charset parameter of the media type.
- *
- * If the parameters of the media type contains a `charset` parameter
- * then this returns its value, otherwise it returns `US-ASCII`,
- * which is the default charset for data URIs.
- * If the value contain non-ASCII percent escapes, they are decoded as UTF-8.
- *
- * If the MIME type representation in the URI text contains URI escapes,
- * they are unescaped in the returned string.
- */
+ /// The charset parameter of the media type.
+ ///
+ /// If the parameters of the media type contains a `charset` parameter
+ /// then this returns its value, otherwise it returns `US-ASCII`,
+ /// which is the default charset for data URIs.
+ /// If the value contain non-ASCII percent escapes, they are decoded as UTF-8.
+ ///
+ /// If the MIME type representation in the URI text contains URI escapes,
+ /// they are unescaped in the returned string.
String get charset {
int parameterStart = 1;
int parameterEnd = _separatorIndices.length - 1; // The ',' before data.
@@ -3538,27 +3400,21 @@
return "US-ASCII";
}
- /**
- * Whether the data is Base64 encoded or not.
- */
+ /// Whether the data is Base64 encoded or not.
bool get isBase64 => _separatorIndices.length.isOdd;
- /**
- * The content part of the data URI, as its actual representation.
- *
- * This string may contain percent escapes.
- */
+ /// The content part of the data URI, as its actual representation.
+ ///
+ /// This string may contain percent escapes.
String get contentText => _text.substring(_separatorIndices.last + 1);
- /**
- * The content part of the data URI as bytes.
- *
- * If the data is Base64 encoded, it will be decoded to bytes.
- *
- * If the data is not Base64 encoded, it will be decoded by unescaping
- * percent-escaped characters and returning byte values of each unescaped
- * character. The bytes will not be, e.g., UTF-8 decoded.
- */
+ /// The content part of the data URI as bytes.
+ ///
+ /// If the data is Base64 encoded, it will be decoded to bytes.
+ ///
+ /// If the data is not Base64 encoded, it will be decoded by unescaping
+ /// percent-escaped characters and returning byte values of each unescaped
+ /// character. The bytes will not be, e.g., UTF-8 decoded.
Uint8List contentAsBytes() {
String text = _text;
int start = _separatorIndices.last + 1;
@@ -3604,20 +3460,18 @@
return result;
}
- /**
- * Returns a string created from the content of the data URI.
- *
- * If the content is Base64 encoded, it will be decoded to bytes and then
- * decoded to a string using [encoding].
- * If encoding is omitted, the value of a `charset` parameter is used
- * if it is recognized by [Encoding.getByName], otherwise it defaults to
- * the [ascii] encoding, which is the default encoding for data URIs
- * that do not specify an encoding.
- *
- * If the content is not Base64 encoded, it will first have percent-escapes
- * converted to bytes and then the character codes and byte values are
- * decoded using [encoding].
- */
+ /// Creates a string from the content of the data URI.
+ ///
+ /// If the content is Base64 encoded, it will be decoded to bytes and then
+ /// decoded to a string using [encoding].
+ /// If encoding is omitted, the value of a `charset` parameter is used
+ /// if it is recognized by [Encoding.getByName], otherwise it defaults to
+ /// the [ascii] encoding, which is the default encoding for data URIs
+ /// that do not specify an encoding.
+ ///
+ /// If the content is not Base64 encoded, it will first have percent-escapes
+ /// converted to bytes and then the character codes and byte values are
+ /// decoded using [encoding].
String contentAsString({Encoding? encoding}) {
if (encoding == null) {
var charset = this.charset; // Returns "US-ASCII" if not present.
@@ -3635,20 +3489,18 @@
return _Uri._uriDecode(text, start, text.length, encoding, false);
}
- /**
- * A map representing the parameters of the media type.
- *
- * A data URI may contain parameters between the MIME type and the
- * data. This converts these parameters to a map from parameter name
- * to parameter value.
- * The map only contains parameters that actually occur in the URI.
- * The `charset` parameter has a default value even if it doesn't occur
- * in the URI, which is reflected by the [charset] getter. This means that
- * [charset] may return a value even if `parameters["charset"]` is `null`.
- *
- * If the values contain non-ASCII values or percent escapes,
- * they are decoded as UTF-8.
- */
+ /// A map representing the parameters of the media type.
+ ///
+ /// A data URI may contain parameters between the MIME type and the
+ /// data. This converts these parameters to a map from parameter name
+ /// to parameter value.
+ /// The map only contains parameters that actually occur in the URI.
+ /// The `charset` parameter has a default value even if it doesn't occur
+ /// in the URI, which is reflected by the [charset] getter. This means that
+ /// [charset] may return a value even if `parameters["charset"]` is `null`.
+ ///
+ /// If the values contain non-ASCII values or percent escapes,
+ /// they are decoded as UTF-8.
Map<String, String> get parameters {
var result = <String, String>{};
for (int i = 3; i < _separatorIndices.length; i += 2) {
@@ -3734,11 +3586,9 @@
return UriData._(text, indices, sourceUri);
}
- /**
- * Like [Uri._uriEncode] but takes the input as bytes, not a string.
- *
- * Encodes into [buffer] instead of creating its own buffer.
- */
+ /// Like [Uri._uriEncode] but takes the input as bytes, not a string.
+ ///
+ /// Encodes into [buffer] instead of creating its own buffer.
static void _uriEncodeBytes(
List<int> canonicalTable, List<int> bytes, StringSink buffer) {
// Encode the string into bytes then generate an ASCII only string
diff --git a/tools/VERSION b/tools/VERSION
index 9974aae..52f5ed8b 100644
--- a/tools/VERSION
+++ b/tools/VERSION
@@ -27,5 +27,5 @@
MAJOR 2
MINOR 12
PATCH 0
-PRERELEASE 217
+PRERELEASE 218
PRERELEASE_PATCH 0
\ No newline at end of file