ArxivRequest

public protocol ArxivRequest

A type providing specification of aXiv API request.

  • Returns full specification of the request.

    Conformig type decide and document configuration of the returned specification.

    Declaration

    Swift

    var requestSpecification: ArxivRequestSpecification { get }
  • url Extension method

    Returns URL for making arXiv API calls specified by the request.

    Declaration

    Swift

    var url: URL { get }
  • sorted(by:) Extension method

    Returns a new request changing the sorting criterion in requestSpecification.

    Declaration

    Swift

    func sorted(by sortingCriterion: ArxivRequestSpecification.SortingCriterion) -> ArxivRequest

    Parameters

    sortCriterion

    A sorting criterion.

  • sortingOrder(_:) Extension method

    Returns a new request changing the sorting order in requestSpecification.

    Declaration

    Swift

    func sortingOrder(_ sortingOrder: ArxivRequestSpecification.SortingOrder) -> ArxivRequest

    Parameters

    sortingOrder

    A sorting order.

  • startIndex(_:) Extension method

    Returns a new request changing the start index in requestSpecification.

    Use to imlement paging. For example, if itemsPerPage == 20, the first page corresponds to startIndex == 0, the second page to startIndex == 40, the third page to startIndex == 60 etc.

    ArxivReponse values can be used for getting various page indicies for given response.

    From arxiv API manual:

    In cases where the API needs to be called multiple times in a row, we encourage you to play nice and incorporate a 3 second delay in your code.

    Because of speed limitations in our implementation of the API, the maximum number of results returned from a single call (itemsPerPage) is limited to 30000 in slices of at most 2000 at a time, using the itemsPerPage and startIndex query parameters.

    For example to retrieve matches 6001-8000:

     term("electron", in: .any)
         .startIndex(6000)
         .itemsPerPage(8000)
    

    Large result sets put considerable load on the server and also take a long time to render. We recommend to refine queries which return more than 1,000 results, or at least request smaller slices. For bulk metadata harvesting or set information, etc., the OAI-PMH interface is more suitable. A request with itemsPerPage > 30,000 will result in an HTTP 400 error code with appropriate explanation. A request for 30000 results will typically take a little over 2 minutes to return a response of over 15MB. Requests for fewer results are much faster and correspondingly smaller.

    Precondition

    i >= 0

    Declaration

    Swift

    func startIndex(_ i: Int) -> ArxivRequest

    Parameters

    i

    Start index of the request.

  • itemsPerPage(_:) Extension method

    Returns a new request changing the number of items per single response page in requestSpecification.

    From arxiv API manual:

    In cases where the API needs to be called multiple times in a row, we encourage you to play nice and incorporate a 3 second delay in your code.

    Because of speed limitations in our implementation of the API, the maximum number of results returned from a single call (itemsPerPage) is limited to 30000 in slices of at most 2000 at a time, using the itemsPerPage and startIndex parameters.

    For example to retrieve matches 6001-8000:

     term("electron", in: .any)
         .startIndex(6000)
         .itemsPerPage(8000)
    

    Large result sets put considerable load on the server and also take a long time to render. We recommend to refine queries which return more than 1,000 results, or at least request smaller slices. For bulk metadata harvesting or set information, etc., the OAI-PMH interface is more suitable. A request with itemsPerPage > 30000 will result in an HTTP 400 error code with appropriate explanation. A request for 30000 results will typically take a little over 2 minutes to return a response of over 15MB. Requests for fewer results are much faster and correspondingly smaller.

    Precondition

    n > 0

    Declaration

    Swift

    func itemsPerPage(_ n: Int) -> ArxivRequest

    Parameters

    n

    Maximum number of articles per response.

  • fetch(using:delegate:) Extension method, asynchronous

    Uses provided session to download and parse articles specified by the request and delivers the result asynchronously.

    Throws

    An error which is either ArxivURLError, ArxivServerError, ArxivParserError or ArxivAPIError.

    Declaration

    Swift

    @available(macOS 12.0.0, iOS 15.0.0, *)
    func fetch(using session: URLSession, delegate: URLSessionTaskDelegate? = nil) async throws -> ArxivResponse

    Parameters

    session

    An URLSession object used for fetching.

    delegate

    A delegate that receives life cycle and authentication challenge callbacks as the transfer progresses.

  • fetchTask(using:completion:) Extension method

    Uses provided session to create and return a task described by the request.

    The completion handler takes a single Result argument, which is either a succesfuly parsed ArxivResponse or an error, if one occurs. The error is either ArxivURLError, ArxivServerError, ArxivParserError or ArxivAPIError.

    If multiple tasks are programatically run in a raw, a 3 seconds delay between the tasks is recomended by arxiv API manual.

    Note

    Completion handler is called on session’s delegateQueue.

    Declaration

    Swift

    func fetchTask(using session: URLSession, completion: @escaping ArxivFetchTaskCompetionHandler) -> URLSessionDataTask

    Parameters

    session

    An URLSession object used for creating and running the task.

    completion

    A function to be called after the task finishes.

  • fetch(using:completion:) Extension method

    Uses provided session to create and and run a task described by the request. Method returns the task after it starts running.

    The completion handler takes a single Result argument, which is either a succesfuly parsed ArxivResponse, or an ArxivKitError, if one occurs.

    If multiple tasks are programatically run in a raw, a 3 seconds delay between the tasks is recomended by arxiv API manual.

    Note

    Completion handler is called on session’s delegateQueue.

    Declaration

    Swift

    @discardableResult
    func fetch(using session: URLSession, completion: @escaping ArxivFetchTaskCompetionHandler) -> URLSessionDataTask

    Parameters

    session

    An URLSession object used for creating and running the task.

    completion

    A function to be called after the task finishes.

  • Uses provided session to create and return a task described by the request.

    When the task completes, a result is assigned to property indicated bykeyPath on the provided object.

    The result is either a succesfuly parsed ArxivResponse or an error, if one occurs. The error is either ArxivURLError, ArxivServerError, ArxivParserError or ArxivAPIError.

    Note

    The assignment happens on session’s delegateQueue.

    Declaration

    Swift

    func fetchTask<Root>(
        using session: URLSession,
        assignResultTo keyPath: ArxivFetchResultKeypath<Root>,
        on object: Root
    ) -> URLSessionDataTask

    Parameters

    session

    An URLSession object used for creating and running the task.

    keyPath

    A key path that indicates the property to assign.

    object

    The object that contains the property.

  • Uses provided session to create and and run a task described by the request. Method returns the task after it starts running.

    The result is either a succesfuly parsed ArxivResponse or an error, if one occurs. The error is either ArxivURLError, ArxivServerError, ArxivParserError or ArxivAPIError.

    Note

    The assignment happens on session’s delegateQueue.

    Declaration

    Swift

    @discardableResult
    func fetch<Root>(
        using session: URLSession,
        assignResultTo keyPath: ArxivFetchResultKeypath<Root>,
        on object: Root
    ) -> URLSessionDataTask

    Parameters

    session

    An URLSession object used for creating and running the task.

    keyPath

    A key path that indicates the property to assign.

    object

    The object that contains the property.