// 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);
}