ListMonitor

public final class ListMonitor<O> : Hashable where O : DynamicObject
extension ListMonitor: CustomDebugStringConvertible, CoreStoreDebugStringConvertible

The ListMonitor monitors changes to a list of DynamicObject instances. Observers that implement the ListObserver protocol may then register themselves to the ListMonitor‘s addObserver(_:) method:

let monitor = dataStack.monitorList(
    From<Person>(),
    Where("title", isEqualTo: "Engineer"),
    OrderBy(.ascending("lastName"))
)
monitor.addObserver(self)

The ListMonitor instance needs to be held on (retained) for as long as the list needs to be observed. Observers registered via addObserver(_:) are not retained. ListMonitor only keeps a weak reference to all observers, thus keeping itself free from retain-cycles.

Lists created with monitorList(...) keep a single-section list of objects, where each object can be accessed by index:

let firstPerson: MyPersonEntity = monitor[0]

Accessing the list with an index above the valid range will raise an exception.

Creating a sectioned-list is also possible with the monitorSectionedList(...) method:

let monitor = dataStack.monitorSectionedList(
    From<Person>(),
    SectionBy("age") { "Age \($0)" },
    Where("title", isEqualTo: "Engineer"),
    OrderBy(.ascending("lastName"))
)
monitor.addObserver(self)

Objects from ListMonitors created this way can be accessed either by an IndexPath or a tuple:

let indexPath = IndexPath(forItem: 3, inSection: 2)
let person1 = monitor[indexPath]
let person2 = monitor[2, 3]

In the example above, both person1 and person2 will contain the object at section=2, index=3.

Public (Accessors)

  • The type for the objects contained bye the ListMonitor

    Declaration

    Swift

    public typealias ObjectType = O

  • Returns the object at the given index within the first section. This subscript indexer is typically used for ListMonitors created with monitorList(_:).

    Declaration

    Swift

    public subscript(index: Int) -> O { get }

    Parameters

    index

    the index of the object. Using an index above the valid range will raise an exception.

    Return Value

    the DynamicObject at the specified index

  • Returns the object at the given index, or nil if out of bounds. This subscript indexer is typically used for ListMonitors created with monitorList(_:).

    Declaration

    Swift

    public subscript(safeIndex index: Int) -> O? { get }

    Parameters

    index

    the index for the object. Using an index above the valid range will return nil.

    Return Value

    the DynamicObject at the specified index, or nil if out of bounds

  • Returns the object at the given sectionIndex and itemIndex. This subscript indexer is typically used for ListMonitors created with monitorSectionedList(_:).

    Declaration

    Swift

    public subscript(sectionIndex: Int, itemIndex: Int) -> O { get }

    Parameters

    sectionIndex

    the section index for the object. Using a sectionIndex with an invalid range will raise an exception.
    itemIndex

    the index for the object within the section. Using an itemIndex with an invalid range will raise an exception.

    Return Value

    the DynamicObject at the specified section and item index

  • Returns the object at the given section and item index, or nil if out of bounds. This subscript indexer is typically used for ListMonitors created with monitorSectionedList(_:).

    Declaration

    Swift

    public subscript(safeSectionIndex sectionIndex: Int, safeItemIndex itemIndex: Int) -> O? { get }

    Parameters

    sectionIndex

    the section index for the object. Using a sectionIndex with an invalid range will return nil.
    itemIndex

    the index for the object within the section. Using an itemIndex with an invalid range will return nil.

    Return Value

    the DynamicObject at the specified section and item index, or nil if out of bounds

  • Returns the object at the given IndexPath. This subscript indexer is typically used for ListMonitors created with monitorSectionedList(_:).

    Declaration

    Swift

    public subscript(indexPath: IndexPath) -> O { get }

    Parameters

    indexPath

    the IndexPath for the object. Using an indexPath with an invalid range will raise an exception.

    Return Value

    the DynamicObject at the specified index path

  • Returns the object at the given IndexPath, or nil if out of bounds. This subscript indexer is typically used for ListMonitors created with monitorSectionedList(_:).

    Declaration

    Swift

    public subscript(safeIndexPath indexPath: IndexPath) -> O? { get }

    Parameters

    indexPath

    the IndexPath for the object. Using an indexPath with an invalid range will return nil.

    Return Value

    the DynamicObject at the specified index path, or nil if out of bounds

  • Checks if the ListMonitor has at least one section

    Declaration

    Swift

    public func hasSections() -> Bool

    Return Value

    true if at least one section exists, false otherwise

  • Checks if the ListMonitor has at least one object in any section.

    Declaration

    Swift

    public func hasObjects() -> Bool

    Return Value

    true if at least one object in any section exists, false otherwise

  • Checks if the ListMonitor has at least one object the specified section.

    Declaration

    Swift

    public func hasObjects(in section: Int) -> Bool

    Parameters

    section

    the section index. Using an index outside the valid range will return false.

    Return Value

    true if at least one object in the specified section exists, false otherwise

  • Returns the number of sections

    Declaration

    Swift

    public func numberOfSections() -> Int

    Return Value

    the number of sections

  • Returns the number of objects in all sections

    Declaration

    Swift

    public func numberOfObjects() -> Int

    Return Value

    the number of objects in all sections

  • Returns the number of objects in the specified section

    Declaration

    Swift

    public func numberOfObjects(in section: Int) -> Int

    Parameters

    section

    the section index. Using an index outside the valid range will raise an exception.

    Return Value

    the number of objects in the specified section

  • Returns the number of objects in the specified section, or nil if out of bounds.

    Declaration

    Swift

    public func numberOfObjects(safelyIn section: Int) -> Int?

    Parameters

    section

    the section index. Using an index outside the valid range will return nil.

    Return Value

    the number of objects in the specified section

  • Returns the NSFetchedResultsSectionInfo for the specified section

    Declaration

    Swift

    public func sectionInfo(at section: Int) -> NSFetchedResultsSectionInfo

    Parameters

    section

    the section index. Using an index outside the valid range will raise an exception.

    Return Value

    the NSFetchedResultsSectionInfo for the specified section

  • Returns the NSFetchedResultsSectionInfo for the specified section, or nil if out of bounds.

    Declaration

    Swift

    public func sectionInfo(safelyAt section: Int) -> NSFetchedResultsSectionInfo?

    Parameters

    section

    the section index. Using an index outside the valid range will return nil.

    Return Value

    the NSFetchedResultsSectionInfo for the specified section, or nil if the section index is out of bounds.

  • Returns the NSFetchedResultsSectionInfos for all sections

    Declaration

    Swift

    public func sections() -> [NSFetchedResultsSectionInfo]

    Return Value

    the NSFetchedResultsSectionInfos for all sections

  • Returns the target section for a specified “Section Index” title and index.

    Declaration

    Swift

    public func targetSection(forSectionIndexTitle sectionIndexTitle: String, at sectionIndex: Int) -> Int

    Parameters

    sectionIndexTitle

    the title of the Section Index
    sectionIndex

    the index of the Section Index

    Return Value

    the target section for the specified “Section Index” title and index.

  • Returns the section index titles for all sections

    Declaration

    Swift

    public func sectionIndexTitles() -> [String]

    Return Value

    the section index titles for all sections

  • Returns the index of the DynamicObject if it exists in the ListMonitor‘s fetched objects, or nil if not found.

    Declaration

    Swift

    public func index(of object: O) -> Int?

    Parameters

    object

    the DynamicObject to search the index of

    Return Value

    the index of the DynamicObject if it exists in the ListMonitor‘s fetched objects, or nil if not found.

  • Returns the IndexPath of the DynamicObject if it exists in the ListMonitor‘s fetched objects, or nil if not found.

    Declaration

    Swift

    public func indexPath(of object: O) -> IndexPath?

    Parameters

    object

    the DynamicObject to search the index of

    Return Value

    the IndexPath of the DynamicObject if it exists in the ListMonitor‘s fetched objects, or nil if not found.

Public (Observers)

  • Registers a ListObserver to be notified when changes to the receiver’s list occur.

    To prevent retain-cycles, ListMonitor only keeps weak references to its observers.

    For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

    Calling addObserver(_:) multiple times on the same observer is safe, as ListMonitor unregisters previous notifications to the observer before re-registering them.

    Declaration

    Swift

    public func addObserver<U>(_ observer: U) where O == U.ListEntityType, U : ListObserver

    Parameters

    observer

    a ListObserver to send change notifications to

  • Registers a ListObjectObserver to be notified when changes to the receiver’s list occur.

    To prevent retain-cycles, ListMonitor only keeps weak references to its observers.

    For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

    Calling addObserver(_:) multiple times on the same observer is safe, as ListMonitor unregisters previous notifications to the observer before re-registering them.

    Declaration

    Swift

    public func addObserver<U>(_ observer: U) where O == U.ListEntityType, U : ListObjectObserver

    Parameters

    observer

    a ListObjectObserver to send change notifications to

  • Registers a ListSectionObserver to be notified when changes to the receiver’s list occur.

    To prevent retain-cycles, ListMonitor only keeps weak references to its observers.

    For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

    Calling addObserver(_:) multiple times on the same observer is safe, as ListMonitor unregisters previous notifications to the observer before re-registering them.

    Declaration

    Swift

    public func addObserver<U>(_ observer: U) where O == U.ListEntityType, U : ListSectionObserver

    Parameters

    observer

    a ListSectionObserver to send change notifications to

  • Unregisters a ListObserver from receiving notifications for changes to the receiver’s list.

    For thread safety, this method needs to be called from the main thread. An assertion failure will occur (on debug builds only) if called from any thread other than the main thread.

    Declaration

    Swift

    public func removeObserver<U>(_ observer: U) where O == U.ListEntityType, U : ListObserver

    Parameters

    observer

    a ListObserver to unregister notifications to

Public (Refetching)

  • Returns true if a call to refetch(...) was made to the ListMonitor and is currently waiting for the fetching to complete. Returns false otherwise.

    Declaration

    Swift

    public private(set) var isPendingRefetch: Bool { get }

  • Asks the ListMonitor to refetch its objects using the specified series of FetchClauses. Note that this method does not execute the fetch immediately; the actual fetching will happen after the NSFetchedResultsController‘s last controllerDidChangeContent(_:) notification completes.

    refetch(...) broadcasts listMonitorWillRefetch(...) to its observers immediately, and then listMonitorDidRefetch(...) after the new fetch request completes.

    Important

    Starting CoreStore 4.0, all FetchClauses required by the ListMonitor should be provided in the arguments list of refetch(...).

    Declaration

    Swift

    public func refetch(
    _ fetchClauses: FetchClause...,
    sourceIdentifier: Any? = nil
)

    Parameters

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.
    sourceIdentifier

    an optional value that identifies the source of this transaction. This identifier will be passed to the change notifications and callers can use it for custom handling that depends on the source.

  • Asks the ListMonitor to refetch its objects using the specified series of FetchClauses. Note that this method does not execute the fetch immediately; the actual fetching will happen after the NSFetchedResultsController‘s last controllerDidChangeContent(_:) notification completes.

    refetch(...) broadcasts listMonitorWillRefetch(...) to its observers immediately, and then listMonitorDidRefetch(...) after the new fetch request completes.

    Important

    Starting CoreStore 4.0, all FetchClauses required by the ListMonitor should be provided in the arguments list of refetch(...).

    Declaration

    Swift

    public func refetch(
    _ fetchClauses: [FetchClause],
    sourceIdentifier: Any? = nil
)

    Parameters

    fetchClauses

    a series of FetchClause instances for fetching the object list. Accepts Where, OrderBy, and Tweak clauses.
    sourceIdentifier

    an optional value that identifies the source of this transaction. This identifier will be passed to the change notifications and callers can use it for custom handling that depends on the source.

Public (3rd Party Utilities)

  • Allow external libraries to store custom data in the ListMonitor. App code should rarely have a need for this.

    enum Static {
    static var myDataKey: Void?
}
monitor.userInfo[&Static.myDataKey] = myObject

    Important

    Do not use this method to store thread-sensitive data.

    Declaration

    Swift

    public let userInfo: UserInfo

Equatable

  • Declaration

    Swift

    public static func == (lhs: ListMonitor<O>, rhs: ListMonitor<O>) -> Bool

Hashable

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

CustomDebugStringConvertible

  • Declaration

    Swift

    public var debugDescription: String { get }

Available where O: NSManagedObject

  • Returns all objects in all sections

    Declaration

    Swift

    public func objectsInAllSections() -> [O]

    Return Value

    all objects in all sections

  • Returns all objects in the specified section

    Declaration

    Swift

    public func objects(in section: Int) -> [O]

    Parameters

    section

    the section index. Using an index outside the valid range will raise an exception.

    Return Value

    all objects in the specified section

  • Returns all objects in the specified section, or nil if out of bounds.

    Declaration

    Swift

    public func objects(safelyIn section: Int) -> [O]?

    Parameters

    section

    the section index. Using an index outside the valid range will return nil.

    Return Value

    all objects in the specified section

Available where O: CoreStoreObject

  • Returns all objects in all sections

    Declaration

    Swift

    public func objectsInAllSections() -> [O]

    Return Value

    all objects in all sections

  • Returns all objects in the specified section

    Declaration

    Swift

    public func objects(in section: Int) -> [O]

    Parameters

    section

    the section index. Using an index outside the valid range will raise an exception.

    Return Value

    all objects in the specified section

  • Returns all objects in the specified section, or nil if out of bounds.

    Declaration

    Swift

    public func objects(safelyIn section: Int) -> [O]?

    Parameters

    section

    the section index. Using an index outside the valid range will return nil.

    Return Value

    all objects in the specified section