class Telerivet::APICursor

An easy-to-use interface for interacting with API methods that return collections of objects that may be split into multiple pages of results.

Using the APICursor, you can easily iterate over query results without having to manually fetch each page of results.

Public Class Methods

new(api, item_cls, path, params = nil) click to toggle source
# File lib/telerivet/apicursor.rb, line 14
def initialize(api, item_cls, path, params = nil)
    params ||= {}

    if params.has_key?('count')
        raise Exception, "Cannot construct APICursor with 'count' parameter. Call the count() method instead."
    end

    @api = api
    @item_cls = item_cls
    @path = path
    @params = params
    
    @count = -1
    @pos = nil
    @data = nil
    @truncated = nil
    @next_marker = nil
    @limit = nil
    @offset = 0
end

Public Instance Methods

all() click to toggle source
# File lib/telerivet/apicursor.rb, line 86
def all()
    to_a
end
count() click to toggle source

Returns the total count of entities matching the current query, without actually fetching the entities themselves.

This is much more efficient than all() if you only need the count, as it only results in one API call, regardless of the number of entities matched by the query.

Returns:

int
# File lib/telerivet/apicursor.rb, line 75
def count()
    if @count == -1
        params = @params.clone
        params['count'] = 1
        
        res = @api.do_request("GET", @path, params)
        @count = res['count'].to_i
    end
    @count
end
each() { |item| ... } click to toggle source
# File lib/telerivet/apicursor.rb, line 35
def each()
    loop do
        item = self.next()
        return if item == nil               
        yield item
    end
end
has_next?() click to toggle source

Returns true if there are any more entities in the result set, false otherwise

Returns:

bool
# File lib/telerivet/apicursor.rb, line 96
def has_next?()
    return false if @limit != nil && @offset >= @limit

    load_next_page() if @data == nil
        
    return true if @pos < @data.length
    
    return false if !@truncated
        
    load_next_page()
    
    @pos < @data.length
end
limit(_limit) click to toggle source

Limits the maximum number of entities fetched by this query.

By default, iterating over the cursor will automatically fetch additional result pages as necessary. To prevent fetching more objects than you need, call this method to set the maximum number of objects retrieved from the API.

Arguments:

- limit (int)
    * The maximum number of entities to fetch from the server (may require multiple API
        calls if greater than 200)
    * Required

Returns:

the current APICursor object
# File lib/telerivet/apicursor.rb, line 59
def limit(_limit)
    @limit = _limit
    self
end
load_next_page() click to toggle source
# File lib/telerivet/apicursor.rb, line 136
def load_next_page()
    request_params = @params.clone
            
    if @next_marker != nil
        request_params['marker'] = @next_marker
    end
    
    if @limit != nil && !request_params.has_key?("page_size")
        request_params['page_size'] = [@limit, 200].min
    end
    
    response = @api.do_request("GET", @path, request_params)
    
    @data = response['data']
    @truncated = response['truncated']
    @next_marker = response['next_marker']
    @pos = 0
end
next() click to toggle source

Returns the next entity in the result set.

Returns:

Telerivet::Entity
# File lib/telerivet/apicursor.rb, line 116
def next()             
    if @limit != nil && @offset >= @limit
        return nil
    end
    
    if @data == nil || (@pos >= @data.length && @truncated)
        load_next_page()
    end
    
    if @pos < @data.length
        item_data = @data[@pos]
        @pos += 1
        @offset += 1
        cls = @item_cls
        return cls.new(@api, item_data, true)
    else
        return nil
    end
end