# equatable 1.2.0 An abstract class that helps to implement equality without needing to explicitly override == and hashCode. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com flutter pub add 'equatable:1.2.0' ``` Published: 2020-05-29T16:53:39.353519Z Expected archive SHA-256: cc5e9c6ec7a339d9aab41593005444a460c7e3f68988de527af9dcd5e0d5ca31 Available in cache; verification: upstream_checksum ## Direct dependencies - collection: ^1.14.11 - meta: ^1.1.6 ## Package README (untrusted upstream documentation) logo

Simplify Equality Comparisons

Build Status Code Coverage Pub Package
style: effective dart MIT License Gitter

--- ## Overview Being able to compare objects in `Dart` often involves having to override the `==` operator as well as `hashCode`. Not only is it verbose and tedious, but failure to do so can lead to inefficient code which does not behave as we expect. By default, `==` returns true if two objects are the same instance. Let's say we have the following class: ```dart class Person { final String name; const Person(this.name); } ``` We can create create instances of `Person` like so: ```dart void main() { final Person bob = Person("Bob"); } ``` Later if we try to compare two instances of `Person` either in our production code or in our tests we will run into a problem. ```dart print(bob == Person("Bob")); // false ``` For more information about this, you can check out the official [Dart Documentation](https://www.dartlang.org/guides/language/effective-dart/design#equality). In order to be able to compare two instances of `Person` we need to change our class to override `==` and `hashCode` like so: ```dart class Person { final String name; const Person(this.name); @override bool operator ==(Object other) => identical(this, other) || other is Person && runtimeType == other.runtimeType && name == other.name; @override int get hashCode => name.hashCode; } ``` Now if we run the following code again: ```dart print(bob == Person("Bob")); // true ``` it will be able to compare different instances of `Person`. You can see how this can quickly become a hassle when dealing with complex classes. This is where `Equatable` comes in! ## What does Equatable do? `Equatable` overrides `==` and `hashCode` for you so you don't have to waste your time writing lots of boilerplate code. There are other packages that will actually generate the boilerplate for you; however, you still have to run the code generation step which is not ideal. With `Equatable` there is no code generation needed and we can focus more on writing amazing applications and less on mundane tasks. ## Usage First, we need to do add `equatable` to the dependencies of the `pubspec.yaml` ```yaml dependencies: equatable: ^1.2.0 ``` Next, we need to install it: ```sh # Dart pub get # Flutter flutter packages get ``` Lastly, we need to extend `Equatable` ```dart import 'package:equatable/equatable.dart'; class Person extends Equatable { final String name; Person(this.name); @override List get props => [name]; } ``` When working with json: ```dart import 'package:equatable/equatable.dart'; class Person extends Equatable { final String name; Person(this.name); @override List get props => [name]; factory Person.fromJson(Map json) { return Person(json['name']); } } ``` We can now compare instances of `Person` just like before without the pain of having to write all of that boilerplate. **Note:** Equatable is designed to only work with immutable objects so all member variables must be final (This is not just a feature of `Equatable` - [overriding a `hashCode` with a mutable value can break hash-based collections](https://dart.dev/guides/language/effective-dart/design#avoid-defining-custom-equality-for-mutable-classes)). Equatable also supports `const` constructors: ```dart import 'package:equatable/equatable.dart'; class Person extends Equatable { final String name; const Person(this.name); @override List get props => [name]; } ``` ### `toString` Implementation Equatable can implement `toString` method including all the given props. If you want that behaviour, just include the following: ```dart @override bool get stringify => true; ``` For instance: ```dart import 'package:equatable/equatable.dart'; class Person extends Equatable { final String name; const Person(this.name); @override List get props => [name]; @override bool get stringify => true; } ``` For the name `Bob`, the output will be: `Person(Bob)` This flag by default is false and `toString` will return just the type: `Person` #### EquatableConfig `stringify` can also be configured globally for all `Equatable` instances via `EquatableConfig` ```dart EquatableConfig.stringify = true; ``` If `stringify` is overridden for a specific `Equatable` class, then the value of `EquatableConfig.stringify` is ignored. In other words, the local configuration always takes precedence over the global configuration. ## Recap ### Without Equatable ```dart class Person { final String name; const Person(this.name); @override bool operator ==(Object other) => identical(this, other) || other is Person && runtimeType == other.runtimeType && name == other.name; @override int get hashCode => name.hashCode; } ``` ### With Equatable ```dart import 'package:equatable/equatable.dart'; class Person extends Equatable { final String name; Person(this.name); @override List get props => [name]; } ``` ## EquatableMixin Sometimes it isn't possible to extend `Equatable` because your class already has a superclass. In this case, you can still get the benefits of `Equatable` by using the `EquatableMixin`. ### Usage Let's say we want to make an `EquatableDateTime` class, we can use `EquatableMixin` like so: ```dart class EquatableDateTime extends DateTime with EquatableMixin { EquatableDateTime( int year, [ int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0, ]) : super(year, month, day, hour, minute, second, millisecond, microsecond); @override List get props { return [year, month, day, hour, minute, second, millisecond, microsecond]; } } ``` Now if we want to create a subclass of `EquatableDateTime`, we can just override `props`. ```dart class EquatableDateTimeSubclass extends EquatableDateTime { final int century; EquatableDateTime( this.century, int year,[ int month = 1, int day = 1, int hour = 0, int minute = 0, int second = 0, int millisecond = 0, int microsecond = 0, ]) : super(year, month, day, hour, minute, second, millisecond, microsecond); @override List get props => super.props..addAll([century]); } ``` ## Performance You might be wondering what the performance impact will be if you use `Equatable`. [Performance Tests](https://github.com/felangel/equatable/raw/master/performance_tests) have been written to test how `Equatable` stacks up to manually overriding `==` and `hashCode` in terms of class instantiation as well as equality comparison. ### Results (average over 10 runs) #### Equality Comparison A == A | Class | Runtime (μs) | | ------------------ | ------------ | | RAW | 0.193 | | Empty Equatable | 0.191 | | Hydrated Equatable | 0.190 | #### Instantiation A() | Class | Runtime (μs) | | ------------------ | ------------ | | RAW | 0.165 | | Empty Equatable | 0.181 | | Hydrated Equatable | 0.182 | \*_Performance Tests run using: Dart VM version: 2.4.0_ ## Changelog # 1.2.0 - Added `EquatableConfig` for global `stringify` configuration ([#69](https://github.com/felangel/equatable/pull/69)) # 1.1.1 - Updates to `EquatableUtils` documentation # 1.1.0 - Fix `hashCode` error when `props` is `null` ([#45](https://github.com/felangel/equatable/pull/45)) - Added `stringify` feature (optional `toString` override) ([#45](https://github.com/felangel/equatable/pull/45)) # 1.0.3 - Fix `hashCode` collisions for lists within props ([#53](https://github.com/felangel/equatable/pull/53)) # 1.0.2 - Fix internal lint warnings # 1.0.1 - Fix `hashCode` collisions with `Map` properties ([#43](https://github.com/felangel/equatable/issues/43)) # 1.0.0 - Update hashCode implementation to use `Jenkins Hash` ([#39](https://github.com/felangel/equatable/issues/39)) - Documentation Updates # 0.6.1 - Minor documentation updates # 0.6.0 - The `props` getter override is required for both `Equatable` and `EquatableMixin` - Performance Improvements # 0.5.1 - Allow const constructors on `Equatable` class # 0.5.0 - Removed `EquatableMixinBase` (now covered by `EquatableMixin`). - Typed `EquatableMixin` from `List` to `List` to fix linter issues with `implicit-dynamic: false`. # 0.4.0 Update `toString` to default to `runtimeType` ([#27](https://github.com/felangel/equatable/issues/27)) # 0.3.0 Enforce Immutability ([#25](https://github.com/felangel/equatable/issues/25)) # 0.2.6 Improved support for collection types ([#19](https://github.com/felangel/equatable/issues/19)) # 0.2.5 Improved support for `Iterable`, `List`, `Map`, and `Set` props ([#17](https://github.com/felangel/equatable/issues/17)) # 0.2.4 Additional Minor Documentation Updates # 0.2.3 Documentation Updates # 0.2.2 Bug Fixes: - `Equatable` instances that are equal now have the same `hashCode` ([#8](https://github.com/felangel/equatable/issues/8)) # 0.2.1 Update Dart support to `>=2.0.0 <3.0.0` # 0.2.0 Add `EquatableMixin` and `EquatableMixinBase` # 0.1.10 Enhancements to `toString` override # 0.1.9 equatable has 0 dependencies # 0.1.8 Support `Iterable` props # 0.1.7 Added `toString` override # 0.1.6 Documentation Updates - Performance Tests # 0.1.5 Additional Performance Optimizations & Documentation Updates # 0.1.4 Performance Optimizations # 0.1.3 Bug Fixes # 0.1.2 Additional Updates to Documentation. - Logo Added # 0.1.1 Minor Updates to Documentation. # 0.1.0 Initial Version of the library. - Includes the ability to extend `Equatable` and not have to override `==` and `hashCode`.