/
symbol.dart
89 lines (83 loc) · 3.59 KB
/
symbol.dart
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
// 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);
}