equatable 0.2.3

  • README.md
  • CHANGELOG.md
  • Example
  • Installing
  • Versions
  • 99
logo

Simplify Equality Comparisons

Build Status Code Coverage Pub Package
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:

class Person {
  final String name;

  const Person(this.name);
}

We can create create instances of Person like so:

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.

print(bob == Person("Bob")); // false

For more information about this, you can check out the official Dart Documentation.

In order to be able to compare two instances of Person we need to change our class to override == and hashCode like so:

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:

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

dependencies:
  equatable: ^0.1.0

Next, we need to install it:

# Dart
pub get

# Flutter
flutter packages get

Lastly, we need to extend Equatable

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  final String name;

  Person(this.name) : super([name]);
}

When working with json:

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  final String name;

  Person(this.name) : super([name]);

  factory Person.fromJson(Map<String, dynamic> 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.

Recap #

Without Equatable #

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 #

import 'package:equatable/equatable.dart';

class Person extends Equatable {
  final String name;

  Person(this.name) : super([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 EquatableMixinBase and EquatableMixin like so:

class EquatableDateTime extends DateTime
    with EquatableMixinBase, 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 continue to just use the EquatableMixin and override props.

class EquatableDateTimeSubclass extends EquatableDateTime with EquatableMixin {
  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 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 #

ClassRuntime (microseconds)
RAW0.143
Empty Equatable0.124
Hydrated Equatable0.126

Instantiation A() #

ClassRuntime (microseconds)
RAW0.099
Empty Equatable0.121
Hydrated Equatable0.251

0.2.3 #

Documentation Updates

0.2.2 #

Bug Fixes:

  • Equatable instances that are equal now have the same hashCode (#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.

example/main.dart

import 'package:equatable/equatable.dart';

class Credentials extends Equatable {
  final String username;
  final String password;

  Credentials({this.username, this.password}) : super([username, password]);
}

class EquatableDateTime extends DateTime
    with EquatableMixinBase, 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];
  }
}

void main() {
  // Extending Equatable
  final credentialsA = Credentials(username: 'Joe', password: 'password123');
  final credentialsB = Credentials(username: 'Bob', password: 'password!');
  final credentialsC = Credentials(username: 'Bob', password: 'password!');

  print(credentialsA == credentialsA); // true
  print(credentialsB == credentialsB); // true
  print(credentialsC == credentialsC); // true
  print(credentialsA == credentialsB); // false
  print(credentialsB == credentialsC); // true

  print(credentialsA); // [Joe, password123]
  print(credentialsB); // [Bob, password!]
  print(credentialsC); // [Bob, password!]

  // Equatable Mixin
  final dateTimeA = EquatableDateTime(2019);
  final dateTimeB = EquatableDateTime(2019, 2, 20, 19, 46);
  final dateTimeC = EquatableDateTime(2019, 2, 20, 19, 46);

  print(dateTimeA == dateTimeA); // true
  print(dateTimeB == dateTimeB); // true
  print(dateTimeC == dateTimeC); // true
  print(dateTimeA == dateTimeB); // false
  print(dateTimeB == dateTimeC); // true

  print(dateTimeA); // 2019-01-01 00:00:00.000
  print(dateTimeB); // 2019-02-20 19:46:00.000
  print(dateTimeC); // 2019-02-20 19:46:00.000
}

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:


dependencies:
  equatable: ^0.2.3

2. Install it

You can install packages from the command line:

with pub:


$ pub get

with Flutter:


$ flutter packages get

Alternatively, your editor might support pub get or flutter packages get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:


import 'package:equatable/equatable.dart';
  
Version Uploaded Documentation Archive
0.2.3 Mar 9, 2019 Go to the documentation of equatable 0.2.3 Download equatable 0.2.3 archive
0.2.2 Feb 26, 2019 Go to the documentation of equatable 0.2.2 Download equatable 0.2.2 archive
0.2.1 Feb 25, 2019 Go to the documentation of equatable 0.2.1 Download equatable 0.2.1 archive
0.2.0 Feb 21, 2019 Go to the documentation of equatable 0.2.0 Download equatable 0.2.0 archive
0.1.10 Jan 26, 2019 Go to the documentation of equatable 0.1.10 Download equatable 0.1.10 archive
0.1.9 Jan 24, 2019 Go to the documentation of equatable 0.1.9 Download equatable 0.1.9 archive
0.1.8 Jan 23, 2019 Go to the documentation of equatable 0.1.8 Download equatable 0.1.8 archive
0.1.7 Jan 23, 2019 Go to the documentation of equatable 0.1.7 Download equatable 0.1.7 archive
0.1.6 Jan 10, 2019 Go to the documentation of equatable 0.1.6 Download equatable 0.1.6 archive
0.1.5 Jan 7, 2019 Go to the documentation of equatable 0.1.5 Download equatable 0.1.5 archive

All 15 versions...

Popularity:
Describes how popular the package is relative to other packages. [more]
97
Health:
Code health derived from static analysis. [more]
100
Maintenance:
Reflects how tidy and up-to-date the package is. [more]
100
Overall:
Weighted score of the above. [more]
99
Learn more about scoring.

We analyzed this package on Mar 9, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

  • Dart: 2.2.0
  • pana: 0.12.14

Platforms

Detected platforms: Flutter, web, other

No platform restriction found in primary library package:equatable/equatable.dart.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0 <3.0.0
Dev dependencies
test >=1.3.0 <2.0.0
test_coverage ^0.2.0