// SPDX-License-Identifier: Apache-2.0 OR MIT //! A punctuated sequence of syntax tree nodes separated by punctuation.//!//! Lots of things in Rust are punctuated sequences.//!//! - The fields of a struct are `Punctuated<Field, Token![,]>`.//! - The segments of a path are `Punctuated<PathSegment, Token![::]>`.//! - The bounds on a generic parameter are `Punctuated<TypeParamBound,//!   Token![+]>`.//! - The arguments to a function call are `Punctuated<Expr, Token![,]>`.//!//! This module provides a common representation for these punctuated sequences//! in the form of the [`Punctuated<T, P>`] type. We store a vector of pairs of//! syntax tree node + punctuation, where every node in the sequence is followed//! by punctuation except for possibly the final one.//!//! [`Punctuated<T, P>`]: Punctuated//!//! ```text//! a_function_call(arg1, arg2, arg3);//!                 ~~~~^ ~~~~^ ~~~~//! ``` use crate::drops::{NoDrop, TrivialDrop};#[cfg(feature = "parsing")]use crate::error::Result;#[cfg(feature = "parsing")]use crate::parse::{Parse, ParseStream};#[cfg(feature = "parsing")]use crate::token::Token;#[cfg(feature = "extra-traits")]use std::fmt::{self, Debug};#[cfg(feature = "extra-traits")]use std::hash::{Hash, Hasher};#[cfg(any(feature = "full", feature = "derive"))]use std::iter;use std::ops::{Index, IndexMut};use std::option;use std::slice;use std::vec; /// **A punctuated sequence of syntax tree nodes of type `T` separated by/// punctuation of type `P`.**////// Refer to the [module documentation] for details about punctuated sequences.////// [module documentation]: selfpub struct Punctuated<T, P> {    inner: Vec<(T, P)>,    last: Option<Box<T>>,} impl<T, P> Punctuated<T, P> {    /// Creates an empty punctuated sequence.    pub const fn new() -> Self {        Punctuated {            inner: Vec::new(),            last: None,        }    }     /// Determines whether this punctuated sequence is empty, meaning it    /// contains no syntax tree nodes or punctuation.    pub fn is_empty(&self) -> bool {        self.inner.len() == 0 && self.last.is_none()    }     /// Returns the number of syntax tree nodes in this punctuated sequence.    ///    /// This is the number of nodes of type `T`, not counting the punctuation of    /// type `P`.    pub fn len(&self) -> usize {        self.inner.len() + if self.last.is_some() { 1 } else { 0 }    }     /// Borrows the first element in this sequence.    pub fn first(&self) -> Option<&T> {        self.iter().next()    }     /// Mutably borrows the first element in this sequence.    pub fn first_mut(&mut self) -> Option<&mut T> {        self.iter_mut().next()    }     /// Borrows the last element in this sequence.    pub fn last(&self) -> Option<&T> {        self.iter().next_back()    }     /// Mutably borrows the last element in this sequence.    pub fn last_mut(&mut self) -> Option<&mut T> {        self.iter_mut().next_back()    }     /// Borrows the element at the given index.    pub fn get(&self, index: usize) -> Option<&T> {        if let Some((value, _punct)) = self.inner.get(index) {            Some(value)        } else if index == self.inner.len() {            self.last.as_deref()        } else {            None        }    }     /// Mutably borrows the element at the given index.    pub fn get_mut(&mut self, index: usize) -> Option<&mut T> {        let inner_len = self.inner.len();        if let Some((value, _punct)) = self.inner.get_mut(index) {            Some(value)        } else if index == inner_len {            self.last.as_deref_mut()        } else {            None        }    }     /// Returns an iterator over borrowed syntax tree nodes of type `&T`.    pub fn iter(&self) -> Iter<T> {        Iter {            inner: Box::new(NoDrop::new(PrivateIter {                inner: self.inner.iter(),                last: self.last.as_ref().map(Box::as_ref).into_iter(),            })),        }    }     /// Returns an iterator over mutably borrowed syntax tree nodes of type    /// `&mut T`.    pub fn iter_mut(&mut self) -> IterMut<T> {        IterMut {            inner: Box::new(NoDrop::new(PrivateIterMut {                inner: self.inner.iter_mut(),                last: self.last.as_mut().map(Box::as_mut).into_iter(),            })),        }    }     /// Returns an iterator over the contents of this sequence as borrowed    /// punctuated pairs.    pub fn pairs(&self) -> Pairs<T, P> {        Pairs {            inner: self.inner.iter(),            last: self.last.as_ref().map(Box::as_ref).into_iter(),        }    }     /// Returns an iterator over the contents of this sequence as mutably    /// borrowed punctuated pairs.    pub fn pairs_mut(&mut self) -> PairsMut<T, P> {        PairsMut {            inner: self.inner.iter_mut(),            last: self.last.as_mut().map(Box::as_mut).into_iter(),        }    }     /// Returns an iterator over the contents of this sequence as owned    /// punctuated pairs.    pub fn into_pairs(self) -> IntoPairs<T, P> {        IntoPairs {            inner: self.inner.into_iter(),            last: self.last.map(|t| *t).into_iter(),        }    }     /// Appends a syntax tree node onto the end of this punctuated sequence. The    /// sequence must already have a trailing punctuation, or be empty.    ///    /// Use [`push`] instead if the punctuated sequence may or may not already    /// have trailing punctuation.    ///    /// [`push`]: Punctuated::push    ///    /// # Panics    ///    /// Panics if the sequence is nonempty and does not already have a trailing    /// punctuation.    pub fn push_value(&mut self, value: T) {        assert!(            self.empty_or_trailing(),            "Punctuated::push_value: cannot push value if Punctuated is missing trailing punctuation",        );         self.last = Some(Box::new(value));    }     /// Appends a trailing punctuation onto the end of this punctuated sequence.    /// The sequence must be non-empty and must not already have trailing    /// punctuation.    ///    /// # Panics    ///    /// Panics if the sequence is empty or already has a trailing punctuation.    pub fn push_punct(&mut self, punctuation: P) {        assert!(            self.last.is_some(),            "Punctuated::push_punct: cannot push punctuation if Punctuated is empty or already has trailing punctuation",        );         let last = self.last.take().unwrap();        self.inner.push((*last, punctuation));    }     /// Removes the last punctuated pair from this sequence, or `None` if the    /// sequence is empty.    pub fn pop(&mut self) -> Option<Pair<T, P>> {        if self.last.is_some() {            self.last.take().map(|t| Pair::End(*t))        } else {            self.inner.pop().map(|(t, p)| Pair::Punctuated(t, p))        }    }     /// Removes the trailing punctuation from this punctuated sequence, or    /// `None` if there isn't any.    pub fn pop_punct(&mut self) -> Option<P> {        if self.last.is_some() {            None        } else {            let (t, p) = self.inner.pop()?;            self.last = Some(Box::new(t));            Some(p)        }    }     /// Determines whether this punctuated sequence ends with a trailing    /// punctuation.    pub fn trailing_punct(&self) -> bool {        self.last.is_none() && !self.is_empty()    }     /// Returns true if either this `Punctuated` is empty, or it has a trailing    /// punctuation.    ///    /// Equivalent to `punctuated.is_empty() || punctuated.trailing_punct()`.    pub fn empty_or_trailing(&self) -> bool {        self.last.is_none()    }     /// Appends a syntax tree node onto the end of this punctuated sequence.    ///    /// If there is not a trailing punctuation in this sequence when this method    /// is called, the default value of punctuation type `P` is inserted before    /// the given value of type `T`.    pub fn push(&mut self, value: T)    where        P: Default,    {        if !self.empty_or_trailing() {            self.push_punct(Default::default());        }        self.push_value(value);    }     /// Inserts an element at position `index`.    ///    /// # Panics    ///    /// Panics if `index` is greater than the number of elements previously in    /// this punctuated sequence.    pub fn insert(&mut self, index: usize, value: T)    where        P: Default,    {        assert!(            index <= self.len(),            "Punctuated::insert: index out of range",        );         if index == self.len() {            self.push(value);        } else {            self.inner.insert(index, (value, Default::default()));        }    }     /// Clears the sequence of all values and punctuation, making it empty.    pub fn clear(&mut self) {        self.inner.clear();        self.last = None;    }     /// Parses zero or more occurrences of `T` separated by punctuation of type    /// `P`, with optional trailing punctuation.    ///    /// Parsing continues until the end of this parse stream. The entire content    /// of this parse stream must consist of `T` and `P`.    #[cfg(feature = "parsing")]    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]    pub fn parse_terminated(input: ParseStream) -> Result<Self>    where        T: Parse,        P: Parse,    {        Self::parse_terminated_with(input, T::parse)    }     /// Parses zero or more occurrences of `T` using the given parse function,    /// separated by punctuation of type `P`, with optional trailing    /// punctuation.    ///    /// Like [`parse_terminated`], the entire content of this stream is expected    /// to be parsed.    ///    /// [`parse_terminated`]: Punctuated::parse_terminated    #[cfg(feature = "parsing")]    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]    pub fn parse_terminated_with<'a>(        input: ParseStream<'a>,        parser: fn(ParseStream<'a>) -> Result<T>,    ) -> Result<Self>    where        P: Parse,    {        let mut punctuated = Punctuated::new();         loop {            if input.is_empty() {                break;            }            let value = parser(input)?;            punctuated.push_value(value);            if input.is_empty() {                break;            }            let punct = input.parse()?;            punctuated.push_punct(punct);        }         Ok(punctuated)    }     /// Parses one or more occurrences of `T` separated by punctuation of type    /// `P`, not accepting trailing punctuation.    ///    /// Parsing continues as long as punctuation `P` is present at the head of    /// the stream. This method returns upon parsing a `T` and observing that it    /// is not followed by a `P`, even if there are remaining tokens in the    /// stream.    #[cfg(feature = "parsing")]    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]    pub fn parse_separated_nonempty(input: ParseStream) -> Result<Self>    where        T: Parse,        P: Token + Parse,    {        Self::parse_separated_nonempty_with(input, T::parse)    }     /// Parses one or more occurrences of `T` using the given parse function,    /// separated by punctuation of type `P`, not accepting trailing    /// punctuation.    ///    /// Like [`parse_separated_nonempty`], may complete early without parsing    /// the entire content of this stream.    ///    /// [`parse_separated_nonempty`]: Punctuated::parse_separated_nonempty    #[cfg(feature = "parsing")]    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]    pub fn parse_separated_nonempty_with<'a>(        input: ParseStream<'a>,        parser: fn(ParseStream<'a>) -> Result<T>,    ) -> Result<Self>    where        P: Token + Parse,    {        let mut punctuated = Punctuated::new();         loop {            let value = parser(input)?;            punctuated.push_value(value);            if !P::peek(input.cursor()) {                break;            }            let punct = input.parse()?;            punctuated.push_punct(punct);        }         Ok(punctuated)    }} #[cfg(feature = "clone-impls")]#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))]impl<T, P> Clone for Punctuated<T, P>where    T: Clone,    P: Clone,{    fn clone(&self) -> Self {        Punctuated {            inner: self.inner.clone(),            last: self.last.clone(),        }    }     fn clone_from(&mut self, other: &Self) {        self.inner.clone_from(&other.inner);        self.last.clone_from(&other.last);    }} #[cfg(feature = "extra-traits")]#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]impl<T, P> Eq for Punctuated<T, P>where    T: Eq,    P: Eq,{} #[cfg(feature = "extra-traits")]#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]impl<T, P> PartialEq for Punctuated<T, P>where    T: PartialEq,    P: PartialEq,{    fn eq(&self, other: &Self) -> bool {        let Punctuated { inner, last } = self;        *inner == other.inner && *last == other.last    }} #[cfg(feature = "extra-traits")]#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]impl<T, P> Hash for Punctuated<T, P>where    T: Hash,    P: Hash,{    fn hash<H: Hasher>(&self, state: &mut H) {        let Punctuated { inner, last } = self;        inner.hash(state);        last.hash(state);    }} #[cfg(feature = "extra-traits")]#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]impl<T: Debug, P: Debug> Debug for Punctuated<T, P> {    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {        let mut list = f.debug_list();        for (t, p) in &self.inner {            list.entry(t);            list.entry(p);        }        if let Some(last) = &self.last {            list.entry(last);        }        list.finish()    }} impl<T, P> FromIterator<T> for Punctuated<T, P>where    P: Default,{    fn from_iter<I: IntoIterator<Item = T>>(i: I) -> Self {        let mut ret = Punctuated::new();        ret.extend(i);        ret    }} impl<T, P> Extend<T> for Punctuated<T, P>where    P: Default,{    fn extend<I: IntoIterator<Item = T>>(&mut self, i: I) {        for value in i {            self.push(value);        }    }} impl<T, P> FromIterator<Pair<T, P>> for Punctuated<T, P> {    fn from_iter<I: IntoIterator<Item = Pair<T, P>>>(i: I) -> Self {        let mut ret = Punctuated::new();        do_extend(&mut ret, i.into_iter());        ret    }} impl<T, P> Extend<Pair<T, P>> for Punctuated<T, P>where    P: Default,{    fn extend<I: IntoIterator<Item = Pair<T, P>>>(&mut self, i: I) {        if !self.empty_or_trailing() {            self.push_punct(P::default());        }        do_extend(self, i.into_iter());    }} fn do_extend<T, P, I>(punctuated: &mut Punctuated<T, P>, i: I)where

Lines 1–500 of 1157. Load more