mirror of
https://github.com/dart-lang/sdk
synced 2024-10-01 19:29:09 +00:00
Update Symbol constructor documentation.
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:
parent
f56dd3f887
commit
3835374fb9
|
@ -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
|
||||
|
|
|
@ -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);
|
||||
}
|
||||
|
|
Loading…
Reference in a new issue