languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-10-01 17:02:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update Symbol constructor documentation.

Browse source 
No longer state that it only accepts some strings as arguments.
Document the expected equality, and the relation to symbol literals.

Fixes #46521

BUG= https://github.com/dart-lang/sdk/issues/46521

Change-Id: If317beda0ac4fef380583105f0f5a3b4b456049b
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/205791
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Erik Ernst <eernst@google.com>
This commit is contained in:
Lasse R.H. Nielsen 2021-07-05 16:41:57 +00:00 committed by commit-bot@chromium.org
parent f56dd3f887
commit 3835374fb9
2 changed files with 35 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
CHANGELOG.md
View file

@ -25,6 +25,10 @@
`Object` class. These can be used to combine the hash codes of
multiple objects in a consistent way.
* The `Symbol` constructor now accepts any string as argument.
Symbols are equal if they were created from the same string.
#### `dart:ffi`
* Adds the `DynamicLibrary.providesSymbol` function to check whether a symbol

77
sdk/lib/core/symbol.dart
View file

@ -17,63 +17,48 @@ abstract class 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.
/// Symbols created from equal [name] strings are themselves equal.
/// If the symbols are created using `const`, symbols with the
/// same [name] strings are canonicalized and identical.
///
/// 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
/// Some [name] strings create symbols which can also be created using
/// a symbol literal, or be implicitly created while running Dart programs,
/// for example through [Object.noSuchMethod].
///
/// * 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 "`+`", "`-`", "`*`", "`/`", "`%`", "`~/`", "`&`", "`|`",
/// If [name] is a single Dart identifier
/// that does not start with an underscore,
/// or it is a qualified identifier (multiple identifiers separated by `.`s),
/// or it is the name of a user definable operator different from `unary-`
/// (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).
/// "`==`", "`[]`", or "`[]=`"),
/// then the result of `Symbol(name)` is equal to the symbol literal
/// created by prefixing `#` to the contents of [name],
/// and `const Symbol(name)` is identical to that symbol literal.
/// That is `#foo == Symbol("foo")` and
/// `identical(#foo, const Symbol("foo"))`.
///
/// 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.
/// If [name] is a single identifier that does not start with an underscore
/// followed by a `=`, then the symbol is a setter name, and can be equal
/// to the [Invocation.memberName] in an [Object.noSuchMethod] invocation.
///
/// Private symbol literals, like `#_foo`, cannot be created using the
/// symbol constructor.
/// A symbol like `const Symbol("_foo")` is not equal to any symbol literal,
/// or to any source name symbol introduced by `noSuchMethod`.
///
/// ```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"), const Symbol("foo")));
/// assert(identical(const Symbol("foo"), #foo));
/// assert(Symbol("[]=") == #[]=]);
/// assert(identical(const Symbol("[]="), #[]=));
/// assert(Symbol("foo.bar") == #foo.bar);
/// 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==].
@ -81,9 +66,9 @@ abstract class Symbol {
/// Equal symbols have the same hash code.
int get hashCode;
/// Symbols are equal to other symbols that correspond to the same member name.
/// Symbols are equal to other symbols with an equal (`==`) name string.
///
/// Qualified member names, like `#foo.bar` are equal only if they have the
/// same identifiers before the same final member name.
/// Symbols representing library private names also need to represent
/// names from the same library.
bool operator ==(Object other);
}