| // 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. |
| /// |
| /// 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. |
| 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. |
| bool operator ==(Object other); |
| } |