Struct ItemIterator 

pub struct ItemIterator<P>
where
    P: Page + Send,
{ /* private fields */ }

Available on crate feature export-azure only.

Iterates over a collection of items or individual pages of items from a service.

You can asynchronously iterate over items returned by a collection request to a service, or asynchronously fetch pages of items if preferred.

Examples

For clients that return a Pager, you can iterate over items across one or more pages:

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

// List secret properties using a Pager.
let mut pager = client.list_secret_properties(None)?;
while let Some(secret) = pager.try_next().await? {
    println!("{}", secret.resource_id()?.name);
}

If you want to iterate each page of items, you can call Pager::into_pages to get a PageIterator:

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> ItemIterator<P>

where P: Page + Send,

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

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

Creates a ItemIterator 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 Option::None, 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>,
}
#[async_trait::async_trait]
impl Page for ListItemsResult {
    type Item = String;
    type IntoIter = <Vec<String> as IntoIterator>::IntoIter;
    async fn into_items(self) -> Result<Self::IntoIter> {
        Ok(self.items.into_iter())
    }
}
let url = "https://example.com/my_paginated_api".parse().unwrap();
let mut base_req = Request::new(url, Method::Get);
let pager = ItemIterator::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>,
}
#[async_trait::async_trait]
impl Page for ListItemsResult {
    type Item = String;
    type IntoIter = <Vec<String> as IntoIterator>::IntoIter;
    async fn into_items(self) -> Result<Self::IntoIter> {
        Ok(self.items.into_iter())
    }
}
let url = "https://example.com/my_paginated_api".parse().unwrap();
let mut base_req = Request::new(url, Method::Get);
let pager = ItemIterator::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-next-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)?;
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))?;
assert!(pager2.try_next().await?.is_some());

pub fn into_pages(self) -> PageIterator<P>

Gets a PageIterator to iterate over pages instead of items.

Resumes from the current page of items until after all items in the current page have been iterated to avoid skipping items in the current page.

Trait Implementations

impl<P> Debug for ItemIterator<P>

where P: Page + Send,

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

Formats the value using the given formatter.

impl<P> FusedStream for ItemIterator<P>

where P: Page + Send,

fn is_terminated(&self) -> bool

Returns true if the stream should no longer be polled.

impl<P> Stream for ItemIterator<P>

where P: Page + Send,

type Item = Result<<P as Page>::Item, Error>

Values yielded by the stream.

fn poll_next( self: Pin<&mut ItemIterator<P>>, cx: &mut Context<'_>, ) -> Poll<Option<<ItemIterator<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 ItemIterator<P>

where P: Page + Send, <PinnedFieldsOfHelperStruct<__ItemIterator<'pin, P>> as PinnedFieldsOfHelperTrait>::Actual: Unpin,