Pagination

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.

A collection that supports offset-based pagination.

Offset-based paging collections use an offset index to paginate items in a larger list of results. Offset-based pagination is the default mechanism for returning paginated results from the Spotify Web API.

A collection that supports cursor-based pagination.

The CursorPagingCollection protocol is tightly linked with the CursorProtocol and CursorPageable protocols. As opposed to offset-based paging collections, cursor-based paging collections depend on a set of cursors to identify the first and last items in a given page, providing reference points from which to page through a larger list of results, typically sorted in chronological order. The type of cursor used to identify the items depends on the type of items returned in the page. Therefore, types that conform to this protocol must also conform its elements to CursorPageable and provide an associated type that conforms to the CursorProtocol, where its cursor type matches that of the collection’s Element.

A type that contains a set of cursors used to identify items and traverse adjacent pages in a cursor-based paging collection.

The CursorProtocol protocol is tightly linked with the CursorPageable and CursorPagingCollection protocols. Cursor-based paging collections depend on a set of cursors to identify the first and last items in a given page, providing reference points from which to page through a larger list of results, typically sorted in chronological order. The type of cursor used to identify the items depends on the type of items returned in the page. Therefore, types that conform to this protocol must provide an associated cursor type that can be used to uniquely identify themselves within a paging collection.

A type that can be returned in a cursor-based paging collection.

The CursorPageable protocol is tightly linked with the CursorProtocol and CursorPagingCollection protocols. Cursor-based paging collections depend on a set of cursors to identify the first and last items in a given page, providing reference points from which to page through a larger list of results, typically sorted in chronological order. The type of cursor used to identify the items depends on the type of items returned in the page. Therefore, types that conform to this protocol must provide an associated cursor type that can be used to uniquely identify themselves within a paging collection.

The cursor type must also be decodable.

A generic collection that provides offset-based paginated results from a Spotify Web API request.

A generic collection that provides cursor-based paginated results from a Spotify Web API request.

A structure representing the parameters for paginating the elements of a larger collection.