Deprecated

class Deprecated

The annotation @Deprecated('migration') marks a feature as deprecated.

The annotation deprecated is a shorthand for deprecating until an unspecified "next release" without migration instructions.

A feature can be any part of an API, from a full library to a single parameter.

The intent of the @Deprecated annotation is to inform authors who are currently using the feature, that they will soon need to stop using that feature in their code, even if the feature is currently still working correctly.

Deprecation is an early warning that the deprecated feature is scheduled to be removed at a later time, a time possibly specified in message. A deprecated feature should no longer be used, code using it will break at some point in the future. If existing code is using the feature, that code should be rewritten to no longer use the deprecated feature.

A deprecated feature should document how the same effect can be achieved in message, so the programmer knows how to rewrite the code.

The @Deprecated annotation applies to libraries, top-level declarations (variables, getters, setters, functions, classes, mixins, extension and typedefs), class-level declarations (variables, getters, setters, methods, operators or constructors, whether static or not), named optional parameters and trailing optional positional parameters.

Deprecation applies transitively to parts of a deprecated feature:

• If a library is deprecated, so is every member of it.
• If a class is deprecated, so is every member of it.
• If a variable is deprecated, so are its implicit getter and setter.

If a feature is deprecated in a superclass, it is not automatically deprecated in a subclass as well. It is reasonable to remove a member from a superclass and retain it in a subclass, so it needs to be possible to deprecate the member only in the superclass.

A tool that processes Dart source code may report when:

• the code imports a deprecated library.
• the code exports a deprecated library, or any deprecated member of a non-deprecated library.
• the code refers statically to a deprecated declaration.
• the code uses a member of an object with a statically known type, where the member is deprecated on the interface of the static type.
• the code calls a method with an argument where the corresponding optional parameter is deprecated on the object's static type.

If the deprecated use is inside a library, class or method which is itself deprecated, the tool should not bother the user about it. A deprecated feature is expected to use other deprecated features.

Constructors

Deprecated() const

const Deprecated(String? message)

Creates a deprecation annotation which specifies the migration path and expiration of the annotated feature.

The message is displayed as part of the warning. The message should be aimed at the programmer using the annotated feature, and should recommend an alternative (if available), and say when this feature is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated(this.message) : _kind = _DeprecationKind.use;

Deprecated.extend() const

const Deprecated.extend([String? message])

Creates an annotation which deprecates extending a class.

The annotation can be used on class declarations which can currently be extended, so they are not marked final, sealed, or interface, but where the ability to extend will be removed in a later release.

Any existing class declaration which extends the class will cause a warning that such use is deprecated. Does not affect classes which implement or mix in the annotated class (see Deprecated.implement, Deprecated.mixin, and Deprecated.subclass).

The annotation is not inherited by subclasses. If a public subclass will also become unextendable, which it will if the annotated declaration becomes final or interface, but not if it becomes sealed, then the subclass should deprecate extendability as well.

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who owns the extending class, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.extend([this.message]) : _kind = _DeprecationKind.extend;

Deprecated.implement() const

const Deprecated.implement([String? message])

Creates an annotation which deprecates implementing a class or mixin.

The annotation can be used on class or mixin declarations whose interface can currently be implemented, so they are not marked final, sealed, or base, but where the ability to implement will be removed in a later release.

Any existing class, mixin or enum declaration which implements the interface will cause a warning that such use is deprecated. Does not affect classes which extend or mix in the annotated class or mixin (see Deprecated.extend, Deprecated.mixin, and Deprecated.subclass).

The annotation is not inherited by subclasses. If a public subclass will also become unimplementable, which it will if the annotated declaration becomes final or base, but not if it becomes sealed, then the subclass should deprecate implementation as well.

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who owns the implementing class, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.implement([this.message])
  : _kind = _DeprecationKind.implement;

Deprecated.instantiate() const

const Deprecated.instantiate([String? message])

Creates an annotation which deprecates instantiating a class.

The annotation can be used on class declarations which can currently be instantiated, so they are not marked abstract or sealed, but where the ability to instantiate will be removed in a later release.

Any existing code which instantiates the annotated class will cause a warning that such use is deprecated.

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who owns the instantiating code, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.instantiate([this.message])
  : _kind = _DeprecationKind.instantiate;

Deprecated.mixin() const

const Deprecated.mixin([String? message])

Creates an annotation which deprecates mixing in a class.

The annotation can be used on class declarations which can currently be mixed in, so they are marked mixin, but where the ability to mix in will be removed in a later release.

Any existing class declaration which mixes in the annotated class will cause a warning that such use is deprecated. Does not affect classes which extend or implement the annotated class (see Deprecated.extend, Deprecated.implement and Deprecated.subclass).

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who owns the class which mixes in the annotated class, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.mixin([this.message]) : _kind = _DeprecationKind.mixin;

Deprecated.optional() const

const Deprecated.optional([String? message])

Creates an annotation which deprecates omitting an argument for the annotated parameter.

The annotation can be used on optional parameters of methods, constructors, or top-level functions, indicating the parameter will be required in a later release.

Any call to a function which does not pass a value for the annotated parameter will cause a warning that such omission is deprecated.

The annotation is not inherited in method overrides.

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who is calling the function with the annotated parameter, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.optional([this.message]) : _kind = _DeprecationKind.optional;

Deprecated.subclass() const

const Deprecated.subclass([String? message])

Creates an annotation which deprecates subclassing (implementing or extending) a class.

The annotation can be used on class and mixin declarations which can currently be subclassed, so they are not marked final, or sealed, but where the ability to subclass will be removed in a later release.

Any existing class declaration which extends or implements the annotated class or mixin will cause a warning that such use is deprecated. Does not affect classes which mix in the annotated class (see Deprecated.extend, Deprecated.implement and Deprecated.mixin).

The annotation is not inherited by subclasses. If a public subclass will also become unsubclassable, which it will if the annotated declaration becomes final, but not if it becomes sealed, then the subclass should deprecate subclassability as well.

The message, if given, is displayed as part of the warning. The message should be aimed at the programmer who owns the subclassing class, and should recommend an alternative (if available), and say when this functionality is expected to be removed if that is sooner or later than the next major version.

Implementation

const Deprecated.subclass([this.message]) : _kind = _DeprecationKind.subclass;

Properties

hashCode no setter inherited

int get hashCode

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

Implementation

external int get hashCode;

message final

final String? message

Message provided to the user when they use the deprecated feature.

The message should explain how to migrate away from the feature if an alternative is available, and when the deprecated feature is expected to be removed.

Implementation

final String? message;

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() override

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.

Implementation

String toString() => "Deprecated feature: $message";

Operators

operator ==() inherited

bool operator ==(Object other)

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

Implementation

external bool operator ==(Object other);