sdk/lib/core/type.dart

// Copyright (c) 2012, 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;

/// Runtime representation of a type.
///
/// Type objects represent types.
/// A type object can be created in several ways:
/// * By a *type literal*, a type name occurring as an expression,
///   like `Type type = int;`,
///   or a type variable occurring as an expression, like `Type type = T;`.
/// * By reading the run-time type of an object,
///   like `Type type = o.runtimeType;`.
/// * Through `dart:mirrors`.
///
/// A type object is intended as an entry point for using `dart:mirrors`.
/// The only operations supported are comparing to other type objects
/// for equality, and converting it to a string for debugging.
abstract class Type {
  /// A hash code for the type which is compatible with [operator==].
  int get hashCode;

  /// Whether [other] is a [Type] instance representing an equivalent type.
  ///
  /// The language specification dictates which types are considered
  /// to be the equivalent.
  /// If two types are equivalent, it's guaranteed that they are subtypes
  /// of each other,
  /// but there are also types which are subtypes of each other,
  /// and which are not equivalent (for example `dynamic` and `void`,
  /// or `FutureOr<Object>` and `Object`).
  bool operator ==(Object other);

  /// Returns a string which represents the underlying type.
  ///
  /// The string is only intended for providing information to a reader
  /// while debugging.
  /// There is no guaranteed format,
  /// the string value returned for a [Type] instances is entirely
  /// implementation dependent.
  ///
  /// The string should be consistent, so a `Type` object for the *same* type
  /// returns the same string throughout a program execution.
  /// The string may or may not contain parts corresponding to the
  /// source name of declaration of the type, if the type has a source name
  /// at all (some types reachable through `dart:mirrors` may not).
  String toString();
}