Skip to content

NSDiffableDataSourceSnapshot ​

NSDiffableDataSourceSnapshot represents an inventory of a list's data: which sections there are, which items are in each section, and in what order. It holds only identifiers, not content; the content is looked up by identifier in the data source's cellProvider.

A snapshot is just data, and changing it doesn't affect the screen. The list changes only after the snapshot is handed to the data source's applySnapshot().

There are two ways to get a snapshot:

HowWhat you getWhen to use it
new NSDiffableDataSourceSnapshot()An empty snapshotPutting data in for the first time; replacing all the data
source.snapshot()A copy of the list's current dataAdding, deleting, or changing items in the existing data

Inheritance: EventTarget → NSObject → NSDiffableDataSourceSnapshot

Constructor ​

NSDiffableDataSourceSnapshot()

Creates an empty snapshot.

Instance properties ​

PropertyDescription
numberOfSections read-onlyThe total number of sections
numberOfItems read-onlyThe total number of items
sectionIdentifiers read-onlyThe identifiers of all sections, in order
itemIdentifiers read-onlyThe identifiers of all items, concatenated in section order

Instance methods ​

Queries:

MethodDescription
numberOfItemsInSection()How many items a section has
itemIdentifiersInSectionWithIdentifier()The identifiers of the items in a section
sectionIdentifierForSectionContainingItemIdentifier()Which section an item is in
indexOfItemIdentifier()An item's position among all items
indexOfSectionIdentifier()A section's position

Changing sections:

MethodDescription
appendSectionsWithIdentifiers()Adds sections at the end
insertSectionsWithIdentifiers()Inserts sections before or after a given section
deleteSectionsWithIdentifiers()Deletes sections and the items in them
moveSectionWithIdentifier()Moves a section before or after another
reloadSectionsWithIdentifiers()Marks the content of the items in some sections as changed

Changing items:

MethodDescription
appendItemsWithIdentifiers()Adds items at the end of a section
insertItemsWithIdentifiers()Inserts items before or after a given item
deleteItemsWithIdentifiers()Deletes items
deleteAllItems()Deletes all sections and items
moveItemWithIdentifier()Moves an item before or after another
reloadItemsWithIdentifiers()Marks items' content as changed; a new cell is used when applied
reconfigureItemsWithIdentifiers()Marks items' content as changed; the existing cell is reused when applied

Common rules for mutating methods ​

  • None of them return a value. Parameters that take a group of identifiers are all arrays.
  • For methods that take a before… key and an after… key, exactly one of the two must be given.
  • On error they all throw TypeError, with a message that starts with the method name. On error the snapshot is left unchanged; none of the identifiers in that call are added.
CaseError
An identifier isn't a string or an integerappendItemsWithIdentifiers: identifiers must be strings or integers, got 1.5
A non-array where an array is expectedappendItemsWithIdentifiers needs an array of identifiers
An identifier being added is already in the snapshotappendItemsWithIdentifiers: item identifier "pear" is already in the snapshot
An identifier appears twice in the same callappendItemsWithIdentifiers: item identifier "x" appears more than once
The section referred to doesn't existappendItemsWithIdentifiers: there is no section with identifier "nope"
The item referred to doesn't exist (insertion position, move, reload, reconfigure)insertItemsWithIdentifiers: there is no item with identifier "nope"
Neither or both of before… and after… giveninsertItemsWithIdentifiers needs exactly one of { beforeItemWithIdentifier } or { afterItemWithIdentifier }

Content changed: reload and reconfigure ​

reloadItemsWithIdentifiers() and reconfigureItemsWithIdentifiers() both mean "this item's content has changed". They differ in how cells are handled:

MethodWhen the snapshot is applied
reconfigureItemsWithIdentifiers()Calls cellProvider again on the existing cell. Usually the one to use
reloadItemsWithIdentifiers()Uses a new cell, then calls cellProvider

Changing only the data the app keeps itself doesn't change the list: the snapshot holds only identifiers, and when the identifiers haven't changed, the system assumes there's nothing to update.

Examples ​

Two sections ​

js
const snapshot = new NSDiffableDataSourceSnapshot();
snapshot.appendSectionsWithIdentifiers(['unpaid', 'done']);
snapshot.appendItemsWithIdentifiers(['A1002'], { intoSectionWithIdentifier: 'unpaid' });
snapshot.appendItemsWithIdentifiers(['A1001', 'A1003'], { intoSectionWithIdentifier: 'done' });
console.log(snapshot.numberOfSections, snapshot.numberOfItems, snapshot.itemIdentifiers.join(','));

Result: Prints 2 3 A1002,A1001,A1003.

Corresponding iOS API ​

ObjCJS
[[NSDiffableDataSourceSnapshot alloc] init]new NSDiffableDataSourceSnapshot()
[snapshot appendItemsWithIdentifiers:ids intoSectionWithIdentifier:@"main"]snapshot.appendItemsWithIdentifiers(ids, { intoSectionWithIdentifier: 'main' })
[snapshot insertItemsWithIdentifiers:ids beforeItemWithIdentifier:@"x"]snapshot.insertItemsWithIdentifiers(ids, { beforeItemWithIdentifier: 'x' })

In ObjC an identifier can be any hashable object; in JS it's a string or an integer. NSNotFound is replaced by -1. Where the system throws an exception that crashes the app on misuse, JS throws a TypeError you can catch.

See also ​