ra1028/differencekit

DifferenceKit is a Swift library that figures out exactly what changed between two lists of items. Given an old list and a new list, it calculates which items were added, removed, moved, or updated, and it does so in linear time, meaning the work it does grows proportionally to the number of items rather than ballooning as lists get longer. The algorithm is based on a technique published by Paul Heckel in 1978 and has been adapted for modern Swift. The main use case is animating changes in iOS and macOS list interfaces. When an app refreshes data, rather than wiping the visible list and redrawing everything from scratch, DifferenceKit tells the list exactly which rows changed so the interface can animate insertions, deletions, and moves smoothly. This applies to the standard iOS scrolling list view and grid view, as well as equivalents in the Texture layout library. The library works on iOS, macOS, tvOS, watchOS, and Linux. A known difficulty with iOS list animation is that certain combinations of changes applied at the same time cause the app to crash. DifferenceKit addresses this by splitting the full set of changes into a series of smaller stages, each of which is safe to apply on its own. The result is called a StagedChangeset, and the library provides convenience methods that apply each stage in the correct order while keeping the underlying data synchronized. To use the library, developers mark their data types with a protocol called Differentiable, which requires two things: a way to identify each item uniquely, and a way to check whether an item's content has changed. Common Swift types like strings and numbers can be made Differentiable with a single line of code. Sectioned lists, where items are grouped into labeled sections, are also supported. The library is available through the standard Swift package managers and is released under the Apache 2.0 license.