Struct PageIterator 

pub struct PageIterator<P>
where
    P: Send,
{ /* private fields */ }

Available on crate feature export-azure only.

Iterates over a collection pages of items from a service.

Examples

Some clients may return a PageIterator if there are no items to iterate or multiple items to iterate. The following example shows how you can also get a PageIterator from a Pager to iterate over pages instead of items. The pattern for iterating pages is otherwise the same:

let client = SecretClient::new(
    "https://my-vault.vault.azure.net",
    credential.clone(),
    None,
)?;

// Iterate each page of secrets using a PageIterator.
let mut pager = client.list_secret_properties(None)?.into_pages();
while let Some(page) = pager.try_next().await? {
    let page = page.into_model()?;
    for secret in page.value {
        println!("{}", secret.resource_id()?.name);
    }
}

Implementations

impl<P> PageIterator<P>

where P: Send,

pub fn new<F>( make_request: F, options: Option<PagerOptions<'static>>, ) -> PageIterator<P>

where F: Fn(PagerState, PagerOptions<'static>) -> Pin<Box<dyn Future<Output = Result<PagerResult<P>, Error>> + Send>> + Send + 'static,

Creates a PageIterator from a callback that will be called repeatedly to request each page.

This method expect a callback that accepts a single PagerState parameter, and returns a PagerResult value asynchronously. The result will be an asynchronous stream of Result values.

The first time your callback is called, it will be called with PagerState::Initial, indicating no next link/continuation token is present.

Your callback must return one of:

• Ok(result) - The request succeeded, and the provided PagerResult indicates the value to return and if there are more pages.
• Err(..) - The request failed. The error will be yielded to the stream, the stream will end, and the callback will not be called again.

Examples

To page results using a next link:

#[derive(serde::Deserialize)]
struct ListItemsResult {
    items: Vec<String>,
    next_link: Option<String>,
}
let url = "https://example.com/my_paginated_api".parse().unwrap();
let mut base_req = Request::new(url, Method::Get);
let pager = PageIterator::new(move |next_link: PagerState, options: PagerOptions<'static>| {
    // The callback must be 'static, so you have to clone and move any values you want to use.
    let pipeline = pipeline.clone();
    let api_version = api_version.clone();
    let mut req = base_req.clone();
    Box::pin(async move {
        if let PagerState::More(next_link) = next_link {
            let next_link: Url = next_link.try_into().expect("expected Url");
            // Ensure the api-version from the client is appended.
            let qp = next_link
                .query_pairs()
                .filter(|(name, _)| name.ne("api-version"));
            req
                .url_mut()
                .query_pairs_mut()
                .clear()
                .extend_pairs(qp)
                .append_pair("api-version", &api_version);
        }
        let resp = pipeline
          .send(&options.context, &mut req, None)
          .await?;
        let (status, headers, body) = resp.deconstruct();
        let result: ListItemsResult = json::from_json(&body)?;
        let resp: Response<ListItemsResult> = RawResponse::from_bytes(status, headers, body).into();
        Ok(match result.next_link {
            Some(next_link) => PagerResult::More {
                response: resp,
                continuation: PagerContinuation::Link(next_link.parse()?),
            },
            None => PagerResult::Done { response: resp }
        })
    })
}, None);

To page results using headers:

#[derive(serde::Deserialize)]
struct ListItemsResult {
    items: Vec<String>,
}
let url = "https://example.com/my_paginated_api".parse().unwrap();
let mut base_req = Request::new(url, Method::Get);
let pager = PageIterator::new(move |continuation, options| {
    // The callback must be 'static, so you have to clone and move any values you want to use.
    let pipeline = pipeline.clone();
    let mut req = base_req.clone();
    Box::pin(async move {
        if let PagerState::More(continuation) = continuation {
            req.insert_header("x-ms-continuation", continuation.as_ref().to_string());
        }
        let resp: Response<ListItemsResult> = pipeline
          .send(&options.context, &mut req, None)
          .await?
          .into();
        Ok(PagerResult::from_response_header(resp, &HeaderName::from_static("x-ms-continuation")))
    })
}, None);

pub fn continuation(&self) -> Option<&PagerContinuation>

Gets the continuation token to pass to PagerOptions to resume paging in another iterator.

pub fn into_continuation(self) -> Option<PagerContinuation>

Gets the continuation token to pass to PagerOptions to resume paging in another iterator.

Examples

This takes ownership of the iterator and can be useful when constructing a new iterator.

let pager1 = client.list_secret_properties(None)?.into_pages();
assert!(pager1.try_next().await?.is_some());
let options = SecretClientListSecretPropertiesOptions {
    method_options: PagerOptions {
        continuation: pager1.into_continuation(),
        ..Default::default()
    },
    ..Default::default()
};
let pager2 = client.list_secret_properties(Some(options))?.into_pages();
assert!(pager2.try_next().await?.is_some());

Trait Implementations

impl<P> Debug for PageIterator<P>

where P: Send,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<P> FusedStream for PageIterator<P>

where P: Send,

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<P> Stream for PageIterator<P>

where P: Send,

type Item = Result<P, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut PageIterator<P>>, cx: &mut Context<'_>, ) -> Poll<Option<<PageIterator<P> as Stream>::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<'pin, P> Unpin for PageIterator<P>

where P: Send, <PinnedFieldsOfHelperStruct<__PageIterator<'pin, P>> as PinnedFieldsOfHelperTrait>::Actual: Unpin,