PagingCollection

public protocol PagingCollection : RandomAccessCollection

A collection that provides paginated results from a Spotify Web API request.

Paging collections are either offset-based or cursor-based depending on the type of paging object returned by the API. The PagingCollection protocol serves as a base for common collection requirements.

Paging collections inherit from the RandomAccessCollection protocol, adopting all the functionality and efficiency of a bidirectional, random-access collection such as Array. In addition to the paging and API-specific requirements, types that conform to this protocol must also implement the requirements of the Collection and BidirectionalCollection protocols—and in order to meet the complexity guarantees of a random-access collection, either the index must conform to the Strideable protocol, or the index(_:offsetBy:) and distance(from:to:) methods must be implemented with O(1) efficiency.

  • The maximum number of items returned in the page, as set in the request or by default.

    Declaration

    Swift

    var limit: Int { get }

  • The total number of items available to return.

    Whereas the count property provides the number of items in the current page of results, total provides the total number of items generated by the API request. Note that not all requests return this value (for example, when fetching a list of recently played tracks).

    Declaration

    Swift

    var total: Int? { get }
  • url

    A link to the Web API endpoint returning the full result of the request.

    Declaration

    Swift

    var url: URL { get }

  • The URL to the next page of items, or nil if no next page exists.

    Declaration

    Swift

    var nextURL: URL? { get }

  • The URL to the previous page of items, or nil if no previous page exists.

    Declaration

    Swift

    var previousURL: URL? { get }

Traversing Pages
  • getNext(completion:) Extension method

    Gets the next page of items and provides it to the specified handler, or nil if no next page exists.

    Note

    This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

    Declaration

    Swift

    public func getNext(completion handler: @escaping (Self?, Error?) -> Void)

    Parameters

    handler

    The callback handler for this request, providing the next page of elements if successful, or an error identifying if and why the request or the decoding failed if unsuccessful.
  • getPrevious(completion:) Extension method

    Gets the previous page of items and provides it to the specified handler, or nil if no previous page exists.

    Note

    This method uses the SPTAuth default instance session to authenticate the underlying request. If this session does not contain a valid access token, the request will result in an error.

    Declaration

    Swift

    public func getPrevious(completion handler: @escaping (Self?, Error?) -> Void)

    Parameters

    handler

    The callback handler for this request, providing the previous page of elements if successful, or an error identifying if and why the request or the decoding failed if unsuccessful.

Decoding JSON Paging Objects
  • init(from:) Extension method

    Creates a SpotifyKit type from the specified JSON data.

    Declaration

    Swift

    public convenience init(from jsonData: Data) throws

    Parameters

    jsonData

    The data containing the JSON-encoded Spotify object.