Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@jflinter
jflinter committed Apr 14, 2017
1 parent 89fc66f commit d19d35b
Show file tree
Hide file tree
Showing 9 changed files with 91 additions and 59 deletions.
6 changes: 3 additions & 3 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The first thing (found in `Dwifft.swift`) is an algorithm that calculates the di

The second thing (found in `Dwifft+UIKit.swift`) is a series of diff calculators for `UITableView`s and `UICollectionView`s. Let's say you have a `UITableView` that's backed by a simple array of values (like a list of names, e.g. `["Alice", "Bob", "Carol"]`. If that array changes (maybe Bob leaves, and is replaced by Dave, so our list is now `["Alice, "Carol", "Dave"]`), we'll want to update the table. The easiest way to do this is by calling `reloadData` on it. This has a couple of downsides: the transition isn't animated, and it'll cause your user to lose their scroll position if they've scrolled the table. The nicer way is to use the `insertRowsAtIndexPaths:withRowAnimation` and `deleteRowsAtIndexPaths:withRowAnimation` methods on `UITableView`, but this requires you to figure out which index paths have changed in your array (in our example, you'd have to figure out that the row at index 1 should be removed, and a new row should be inserted at index 2 should then be added). If only we had a way to diff the previous value of our array with it's new value. Wait a minute.

When you wire up a `TableViewDiffCalculator` to your `UITableView` (or a `CollectionViewDiffCalculator` to your `UICollectionView`, it'll _automatically_ calculate diffs and trigger the necessary animations on it whenever you change its `sectionedValues` property. Neat, right? Notably, as of Dwifft 0.6, Dwifft will also figure out _section_ insertions and deletions, as well as how to efficiently insert and delete rows across different sections, which is just so massively useful if you have a multi-section table. If you're currently using a <0.6 version of Dwifft and want to do this, read the [0.6 release notes](TODO).
When you wire up a `TableViewDiffCalculator` to your `UITableView` (or a `CollectionViewDiffCalculator` to your `UICollectionView`, it'll _automatically_ calculate diffs and trigger the necessary animations on it whenever you change its `sectionedValues` property. Neat, right? Notably, as of Dwifft 0.6, Dwifft will also figure out _section_ insertions and deletions, as well as how to efficiently insert and delete rows across different sections, which is just so massively useful if you have a multi-section table. If you're currently using a <0.6 version of Dwifft and want to do this, read the [0.6 release notes](https://github.com/jflinter/Dwifft/releases/tag/0.6).

Even longer version
---
Expand All @@ -32,12 +32,12 @@ Why you should use Dwifft
How to get started
---
- First, you should take a look at the example app, to get a feel for how Dwifft is meant to be used.
- Next, you should just sit down and read the [entire documentation](TODO) - it will take you <10 minutes, and you'll leave knowing everything there is to know about Dwifft.
- Next, you should just sit down and read the [entire documentation](https://jackflintermann.com/Dwifft) - it will take you <10 minutes, and you'll leave knowing everything there is to know about Dwifft.
- Then, install Dwifft via cocoapods or carthage or whatever people are using these days.
- Then get to Dwiffing.

Contributing
---
Contributions are welcome, with some caveats - please read the [contributing guidelines](TODO) before opening a PR to avoid wasting both our time.
Contributions are welcome, with some caveats - please read the [contributing guidelines](https://github.com/jflinter/Dwifft/blob/master/CONTRIBUTING.md) before opening a PR to avoid wasting both our time.

Ok, that's it, there's nothing more here.
32 changes: 16 additions & 16 deletions docs/Typealiases.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,24 +100,30 @@ <h1>Typealiases</h1>
<li class="item">
<div>
<code>
<a name="/s:6Dwifft34SimpleCollectionViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleCollectionViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft34SimpleCollectionViewDiffCalculator">SimpleCollectionViewDiffCalculator</a>
<a name="/s:6Dwifft29SimpleTableViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleTableViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft29SimpleTableViewDiffCalculator">SimpleTableViewDiffCalculator</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>See SimpleTableViewDiffCalculator for explanation</p>
<p>Let&rsquo;s say your data model consists of different sections containing different model types. Since
<code><a href="Structs/SectionedValues.html">SectionedValues</a></code> requires a uniform type for all of its rows, this can be a clunky situation. You
can address this in a couple of ways. The first is to define a custom enum that encompasses all of the
things that <em>could</em> be in your data model - if section 1 has a bunch of <code>String</code>s, and section 2 has a bunch
of <code>Int</code>s, define a <code>StringOrInt</code> enum that conforms to <code>Equatable</code>, and fill the <code><a href="Structs/SectionedValues.html">SectionedValues</a></code>
that you use to drive your DiffCalculator up with those. Alternatively, if you are lazy, and your
models all conform to <code>Hashable</code>, you can use a SimpleTableViewDiffCalculator instead.</p>

</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleCollectionViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/CollectionViewDiffCalculator.html">CollectionViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleTableViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/TableViewDiffCalculator.html">TableViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>

</div>
</div>
Expand All @@ -127,30 +133,24 @@ <h4>Declaration</h4>
<li class="item">
<div>
<code>
<a name="/s:6Dwifft29SimpleTableViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleTableViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft29SimpleTableViewDiffCalculator">SimpleTableViewDiffCalculator</a>
<a name="/s:6Dwifft34SimpleCollectionViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleCollectionViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft34SimpleCollectionViewDiffCalculator">SimpleCollectionViewDiffCalculator</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Let&rsquo;s say your data model consists of different sections containing different model types. Since
<code><a href="Structs/SectionedValues.html">SectionedValues</a></code> requires a uniform type for all of its rows, this can be a clunky situation. You
can address this in a couple of ways. The first is to define a custom enum that encompasses all of the
things that <em>could</em> be in your data model - if section 1 has a bunch of <code>String</code>s, and section 2 has a bunch
of <code>Int</code>s, define a <code>StringOrInt</code> enum that conforms to <code>Equatable</code>, and fill the <code><a href="Structs/SectionedValues.html">SectionedValues</a></code>
that you use to drive your DiffCalculator up with those. Alternatively, if you are lazy, and your
models all conform to <code>Hashable</code>, you can use a SimpleTableViewDiffCalculator instead.</p>
<p>See SimpleTableViewDiffCalculator for explanation</p>

</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleTableViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/TableViewDiffCalculator.html">TableViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleCollectionViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/CollectionViewDiffCalculator.html">CollectionViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>

</div>
</div>
Expand Down
32 changes: 16 additions & 16 deletions docs/docsets/Dwifft.docset/Contents/Resources/Documents/Typealiases.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,24 +100,30 @@ <h1>Typealiases</h1>
<li class="item">
<div>
<code>
<a name="/s:6Dwifft34SimpleCollectionViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleCollectionViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft34SimpleCollectionViewDiffCalculator">SimpleCollectionViewDiffCalculator</a>
<a name="/s:6Dwifft29SimpleTableViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleTableViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft29SimpleTableViewDiffCalculator">SimpleTableViewDiffCalculator</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>See SimpleTableViewDiffCalculator for explanation</p>
<p>Let&rsquo;s say your data model consists of different sections containing different model types. Since
<code><a href="Structs/SectionedValues.html">SectionedValues</a></code> requires a uniform type for all of its rows, this can be a clunky situation. You
can address this in a couple of ways. The first is to define a custom enum that encompasses all of the
things that <em>could</em> be in your data model - if section 1 has a bunch of <code>String</code>s, and section 2 has a bunch
of <code>Int</code>s, define a <code>StringOrInt</code> enum that conforms to <code>Equatable</code>, and fill the <code><a href="Structs/SectionedValues.html">SectionedValues</a></code>
that you use to drive your DiffCalculator up with those. Alternatively, if you are lazy, and your
models all conform to <code>Hashable</code>, you can use a SimpleTableViewDiffCalculator instead.</p>

</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleCollectionViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/CollectionViewDiffCalculator.html">CollectionViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleTableViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/TableViewDiffCalculator.html">TableViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>

</div>
</div>
Expand All @@ -127,30 +133,24 @@ <h4>Declaration</h4>
<li class="item">
<div>
<code>
<a name="/s:6Dwifft29SimpleTableViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleTableViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft29SimpleTableViewDiffCalculator">SimpleTableViewDiffCalculator</a>
<a name="/s:6Dwifft34SimpleCollectionViewDiffCalculator"></a>
<a name="//apple_ref/swift/Alias/SimpleCollectionViewDiffCalculator" class="dashAnchor"></a>
<a class="token" href="#/s:6Dwifft34SimpleCollectionViewDiffCalculator">SimpleCollectionViewDiffCalculator</a>
</code>
</div>
<div class="height-container">
<div class="pointer-container"></div>
<section class="section">
<div class="pointer"></div>
<div class="abstract">
<p>Let&rsquo;s say your data model consists of different sections containing different model types. Since
<code><a href="Structs/SectionedValues.html">SectionedValues</a></code> requires a uniform type for all of its rows, this can be a clunky situation. You
can address this in a couple of ways. The first is to define a custom enum that encompasses all of the
things that <em>could</em> be in your data model - if section 1 has a bunch of <code>String</code>s, and section 2 has a bunch
of <code>Int</code>s, define a <code>StringOrInt</code> enum that conforms to <code>Equatable</code>, and fill the <code><a href="Structs/SectionedValues.html">SectionedValues</a></code>
that you use to drive your DiffCalculator up with those. Alternatively, if you are lazy, and your
models all conform to <code>Hashable</code>, you can use a SimpleTableViewDiffCalculator instead.</p>
<p>See SimpleTableViewDiffCalculator for explanation</p>

</div>
<div class="declaration">
<h4>Declaration</h4>
<div class="language">
<p class="aside-title">Swift</p>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleTableViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/TableViewDiffCalculator.html">TableViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>
<pre class="highlight"><code><span class="kd">typealias</span> <span class="kt">SimpleCollectionViewDiffCalculator</span> <span class="o">=</span> <span class="kt"><a href="Classes/CollectionViewDiffCalculator.html">CollectionViewDiffCalculator</a></span><span class="o">&lt;</span><span class="kt">AnyHashable</span><span class="p">,</span> <span class="kt">AnyHashable</span><span class="o">&gt;</span></code></pre>

</div>
</div>
Expand Down
Loading

0 comments on commit d19d35b

Please sign in to comment.