Add change information to collection notifications

[tgoyne]

This adds a third parameter to the notification block on Results/List/RLMResults/RLMArray/etc. that reports the indices in the collection which were deleted, inserted and modified. In addition, it skips sending the notification when the collection did not actually change, rather than notifying on every change to the relevant table(s). It does not include information about which property on the object at the given index changed or supply the old value at that index; for those KVO on each object must be used.

Most of the testing for this is done at the objectstore level, so see the corresponding PR there.

Closes #687. Closes #3435.

Things left to do:

• Functionality
  • Change information for List
  • Change information for unsorted Results
  • Change information for sorted Results
  • Change information for Results derived from List
  • Finalize API
• Testing
  • Write tests covering everything that can reasonably be tested in object-store
  • Obj-c integration tests
  • Swift integration tests
  • TSan on object store tests
  • TSan on realm-cocoa tests
  • Fuzz-test unsorted query changesets
  • Fuzz-test sorted query changesets
  • Fuzz-test unsorted linkview changesets
  • Fuzz-test sorted linkview changesets
• Documentation
  • Write API docs
  • Update the guide
  • Release post
  • Update existing UITableView examples
  • Add an NSOutlineView example
• Performance
  • Small changesets, Unsorted
  • Small changesets, Sorted
  • Small changesets, List
  • Many changesets, Unsorted
  • Many changesets, Sorted
  • Many changesets, List
  • Large changesets, Unsorted
  • Large changesets, Sorted
  • Large changesets, List

My current goal performance-wise is to have everything be fast enough that no one will need a way to opt-out of the changeset calculations, as that'd make the API unpleasant. Since most of the work is done on background threads and doesn't block the UI this should be easily attainable.

[TimOliver]

I noticed this when copying this code for the documentation: 'occurred' needs another 'r' there.

[jpsim]

Instead of having two separate addNotificationBlock overloads for NSIndexPath/Int block parameters, could we use platform-specific typealiases? e.g. Int for OS X, NSIndexPath for others?

Otherwise, our users will end up fighting Swift's type inference system:

vs

[tgoyne]

After thinking about it some more and looking at some code using the notifications, I'm now thinking that the obj-c NSIndexPath version should be [change insertionsInSection:0] (withSection?), and the Swift one should just be removed entirely.

Only generating paths for section 0 makes it not useful for grouped table views, and generalizing it doesn't really make it worse for the simple case. In Swift, you can just do insertions.map { NSIndexPath(section: 0, index: $0) }, so the whole thing is kinda pointless.

[tgoyne]

I tried using fine-grained notifications for the GroupedTableView example, and it turns out that the current design doesn't work for that when a single transaction modifies multiple sections. The problem is that all of the sections need to be updated within a single UITableView batch as it rechecks the sizes of all of the groups when you call endUpdates, but from within the notification block there's no good way to know if there's still more blocks which will be called. Some ideas for how to handle this:

1. Don't, and just document it as an unsupported use-case
2. Do something like let tokens = [results1, results2, results].addNotificationBlock { [changes] in ... } to make it possible to get all of the change notifications at once. I'm not really sure what the obj-c API would look like for this.
3. Delay sending the Realm DidChange notification until after the async queries have been updated so that you can end the batch there
4. Something less awful?

[bdash]

m_query doesn't seem like an appropriate name for this member given that the thing it holds is described as a collection.

[bdash]

I love the newly-added comments explaining the move detection code!

👍

[gastonmorixe]

Thank you @tgoyne and the team!

[jpsim]

This doesn't appear to be used anywhere. Is it still worth keeping around?