You are viewing documentation for version 1 of the AWS SDK for Ruby. Version 2 documentation can be found here.
Module: AWS::Core::Collection
- Includes:
- Enumerable
- Included in:
- Simple, WithLimitAndNextToken, WithNextToken
- Defined in:
- lib/aws/core/collection.rb,
lib/aws/core/collection/simple.rb,
lib/aws/core/collection/with_next_token.rb,
lib/aws/core/collection/with_limit_and_next_token.rb
Overview
Provides useful methods for enumerating items in a collection.
Defined Under Namespace
Modules: Simple, WithLimitAndNextToken, WithNextToken
Instance Method Summary collapse
-
#each(options = {}, &block) ⇒ nil_or_next_token
Yields once for every item in this collection.
-
#each_batch(options = {}, &block) ⇒ nil_or_next_token
Yields items from this collection in batches.
-
#enum(options = {}) ⇒ Enumerable::Enumerator
(also: #enumerator)
Use this method when you want to call a method provided by Enumerable, but you need to pass options:.
-
#first(options = {}) ⇒ item_or_nil
Returns the first item from this collection.
-
#in_groups_of(size, options = {}) {|group| ... } ⇒ nil_or_next_token
Yields items from this collection in groups of an exact size (except for perhaps the last group).
-
#page(options = {}) ⇒ Object
Returns a single page of results in a kind-of array (PageResult).
Instance Method Details
#each(options = {}, &block) ⇒ nil_or_next_token
46 47 48 49 50 |
# File 'lib/aws/core/collection.rb', line 46 def each = {}, &block each_batch() do |batch| batch.each(&block) end end |
#each_batch(options = {}, &block) ⇒ nil_or_next_token
If you require fixed batch sizes, see #in_groups_of.
Yields items from this collection in batches.
collection.each_batch do |batch|
batch.each do |item|
# ...
end
end
Variable Batch Sizes
Each AWS service has its own rules on how it returns results. Because of this batch size may very based on:
Service limits (e.g. S3 limits keys to 1000 per response)
The size of response objects (SimpleDB limits responses to 1MB)
Time to process the request
Because of these variables, batch sizes may not be consistent for a single collection. Each batch represents all of the items returned in a single resopnse.
79 80 81 |
# File 'lib/aws/core/collection.rb', line 79 def each_batch = {}, &block _each_batch(.dup, &block) end |
#enum(options = {}) ⇒ Enumerable::Enumerator Also known as: enumerator
Use this method when you want to call a method provided by Enumerable, but you need to pass options:
# raises an error because collect does not accept arguments
collection.collect(:limit => 10) {|i| i.name }
# not an issue with the enum method
collection.enum(:limit => 10).collect(&:name)
97 98 99 |
# File 'lib/aws/core/collection.rb', line 97 def enum = {} to_enum(:each, ) end |
#first(options = {}) ⇒ item_or_nil
Returns the first item from this collection.
107 108 109 |
# File 'lib/aws/core/collection.rb', line 107 def first = {} enum(.merge(:limit => 1)).first end |
#in_groups_of(size, options = {}) {|group| ... } ⇒ nil_or_next_token
Yields items from this collection in groups of an exact size (except for perhaps the last group).
collection.in_groups_of (10, :limit => 30) do |group|
# each group should be exactly 10 items unless
# fewer than 30 items are returned by the service
group.each do |item|
#...
end
end
129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 |
# File 'lib/aws/core/collection.rb', line 129 def in_groups_of size, = {}, &block group = [] nil_or_next_token = each_batch() do |batch| batch.each do |item| group << item if group.size == size yield(group) group = [] end end end yield(group) unless group.empty? nil_or_next_token end |
#page(options = {}) ⇒ Object
This method does not accept a :page
option, which means you
can only start at the begining of the collection and request
the next page of results. You can not choose an offset
or know how many pages of results there will be.
Returns a single page of results in a kind-of array (PageResult).
items = collection.page(:per_page => 10) # defaults to 10 items
items.is_a?(Array) # => true
items.size # => 8
items.per_page # => 10
items.last_page? # => true
If you need to display a "next page" link in a web view you can
use the #more? method. Just make sure the generated link
contains the next_token
.
<% if items.more? %>
<%= link_to('Next Page', params.merge(:next_token => items.next_token) %>
<% end %>
Then in your controller you can find the next page of results:
items = collection.page(:next_token => params[:next_token])
Given a PageResult you can also get more results directly:
more_items = items.next_page
191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 |
# File 'lib/aws/core/collection.rb', line 191 def page = {} each_opts = .dup per_page = each_opts.delete(:per_page) per_page = [nil,''].include?(per_page) ? 10 : per_page.to_i each_opts[:limit] = per_page items = [] next_token = each(each_opts) do |item| items << item end Core::PageResult.new(self, items, per_page, next_token) end |