mirror of
https://github.com/dart-lang/sdk
synced 2024-09-16 03:36:59 +00:00
3835374fb9
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>
75 lines
3.2 KiB
Dart
75 lines
3.2 KiB
Dart
// Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file
|
|
// 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.
|
|
|
|
part of dart.core;
|
|
|
|
/// Opaque name used by mirrors, invocations and [Function.apply].
|
|
abstract class Symbol {
|
|
/// 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.
|
|
static const Symbol empty = Symbol("");
|
|
|
|
/// Constructs a new [Symbol] representing the provided name.
|
|
///
|
|
/// 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.
|
|
///
|
|
/// 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].
|
|
///
|
|
/// 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 "`[]=`"),
|
|
/// 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"))`.
|
|
///
|
|
/// 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(Symbol("foo") == #foo);
|
|
/// 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));
|
|
/// ```
|
|
///
|
|
/// The created instance overrides [Object.==].
|
|
const factory Symbol(String name) = internal.Symbol;
|
|
|
|
/// Returns a hash code compatible with [operator==].
|
|
///
|
|
/// Equal symbols have the same hash code.
|
|
int get hashCode;
|
|
|
|
/// Symbols are equal to other symbols with an equal (`==`) name string.
|
|
///
|
|
/// Symbols representing library private names also need to represent
|
|
/// names from the same library.
|
|
bool operator ==(Object other);
|
|
}
|