Symbol abstract

abstract class Symbol

Opaque name used by mirrors, invocations and Function.apply.

Constructors

Symbol() factory const

const factory Symbol(String name)

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.

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.==.

Implementation

const factory Symbol(String name) = internal.Symbol;

Properties

hashCode no setter override

int get hashCode

Returns a hash code compatible with operator==.

Equal symbols have the same hash code.

Implementation

int get hashCode;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

Implementation

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

toString() inherited

String toString()

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

Implementation

external String toString();

Operators

operator ==() override

bool operator ==(Object other)

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.

Implementation

bool operator ==(Object other);

Constants

empty

const Symbol empty

The empty symbol.

The empty symbol is the name of libraries with no library declaration, and the base-name of the unnamed constructor.

Implementation

static const Symbol empty = Symbol("");

unaryMinus

const Symbol unaryMinus

The symbol corresponding to the name of the unary minus operator.

Implementation

static const Symbol unaryMinus = Symbol("unary-");