From 85396f12369d56394e1f600b98e0f11071ff2afc Mon Sep 17 00:00:00 2001 From: Jesse Squires Date: Fri, 24 Feb 2017 13:32:27 -0800 Subject: [PATCH] Update IGListDiffable and Equality.md Summary: Per #509 Closes https://github.com/Instagram/IGListKit/pull/513 Differential Revision: D4613737 Pulled By: jessesquires fbshipit-source-id: f77960819a047a0bd504dbf7ebf0558a569801cf --- Guides/IGListDiffable and Equality.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/Guides/IGListDiffable and Equality.md b/Guides/IGListDiffable and Equality.md index 90da7283..ec897099 100644 --- a/Guides/IGListDiffable and Equality.md +++ b/Guides/IGListDiffable and Equality.md @@ -1,10 +1,16 @@ # IGListDiffable and Equality -This guide details how to write good `isEqual:` methods. +This guide explains the `IGListDiffable` protocol and how to write good `-isEqual:` methods. ## Background -`IGListKit` requires that models implement the method `isEqualToDiffableObject:` which should perform the same type of check as `isEqual:`, but without impacting performance characteristics like in Objective-C containers such as `NSDictionary` and `NSSet`. +The [`IGListDiffable` protocol](https://instagram.github.io/IGListKit/Protocols/IGListDiffable.html) requires clients to implement two methods, `-diffIdentifier` and `-isEqualToDiffableObject:`. + +The method `-isEqualToDiffableObject:` should perform the same type of check as `-isEqual:`, but without impacting performance characteristics, like in Objective-C containers such as `NSDictionary` and `NSSet`. + +Why are both of these methods required for diffing? The point of having the two methods has to do with **identity** and **equality**, where the diff identifier uniquely identifies data (common scenario is primary key in databases). Equality comes into play when comparing the values of two uniquely identical objects (driving reloading). + +See also: [#509](https://github.com/Instagram/IGListKit/issues/509) ## `IGListDiffable` bare minimum @@ -22,7 +28,7 @@ The quickest way to get started with diffable models is use the _object itself_ ## Writing better Equality methods -Even though `IGListKit` uses the method `isEqualToDiffableObject:`, the concepts of writing a good equality check apply in general. Here are the basics to writing good `-isEqual:` and `-hash` functions. Note this is all Objective-C but applies to Swift also. +Even though `IGListKit` uses the method `-isEqualToDiffableObject:`, the concepts of writing a good equality check apply in general. Here are the basics to writing good `-isEqual:` and `-hash` functions. Note this is all Objective-C but applies to Swift also. - If you override `-isEqual:` you **must** override `-hash`. Check out this [article by Mike Ash](https://www.mikeash.com/pyblog/friday-qa-2010-06-18-implementing-equality-and-hashing.html) for details. - Always compare the pointer first. This saves a lot of wasteful `objc_msgSend(...)` calls and value comparisons if checking the same instance. @@ -70,7 +76,7 @@ You would implement its equality methods like so: ## Using both `IGListDiffable` and `-isEqual:` -Making your objects work universally with Objective-C containers and `IGListKit` is easy once you've implemented `isEqual:` and `-hash`. +Making your objects work universally with Objective-C containers and `IGListKit` is easy once you've implemented `-isEqual:` and `-hash`. ```objc @interface User