syn/
punctuated.rs

1// SPDX-License-Identifier: Apache-2.0 OR MIT
2
3//! A punctuated sequence of syntax tree nodes separated by punctuation.
4//!
5//! Lots of things in Rust are punctuated sequences.
6//!
7//! - The fields of a struct are `Punctuated<Field, Token![,]>`.
8//! - The segments of a path are `Punctuated<PathSegment, Token![::]>`.
9//! - The bounds on a generic parameter are `Punctuated<TypeParamBound,
10//!   Token![+]>`.
11//! - The arguments to a function call are `Punctuated<Expr, Token![,]>`.
12//!
13//! This module provides a common representation for these punctuated sequences
14//! in the form of the [`Punctuated<T, P>`] type. We store a vector of pairs of
15//! syntax tree node + punctuation, where every node in the sequence is followed
16//! by punctuation except for possibly the final one.
17//!
18//! [`Punctuated<T, P>`]: Punctuated
19//!
20//! ```text
21//! a_function_call(arg1, arg2, arg3);
22//!                 ~~~~^ ~~~~^ ~~~~
23//! ```
24
25use crate::drops::{NoDrop, TrivialDrop};
26#[cfg(feature = "parsing")]
27use crate::error::Result;
28#[cfg(feature = "parsing")]
29use crate::parse::{Parse, ParseStream};
30#[cfg(feature = "parsing")]
31use crate::token::Token;
32#[cfg(feature = "extra-traits")]
33use std::fmt::{self, Debug};
34#[cfg(feature = "extra-traits")]
35use std::hash::{Hash, Hasher};
36#[cfg(any(feature = "full", feature = "derive"))]
37use std::iter;
38use std::ops::{Index, IndexMut};
39use std::option;
40use std::slice;
41use std::vec;
42
43/// **A punctuated sequence of syntax tree nodes of type `T` separated by
44/// punctuation of type `P`.**
45///
46/// Refer to the [module documentation] for details about punctuated sequences.
47///
48/// [module documentation]: self
49pub struct Punctuated<T, P> {
50    inner: Vec<(T, P)>,
51    last: Option<Box<T>>,
52}
53
54impl<T, P> Punctuated<T, P> {
55    /// Creates an empty punctuated sequence.
56    pub const fn new() -> Self {
57        Punctuated {
58            inner: Vec::new(),
59            last: None,
60        }
61    }
62
63    /// Determines whether this punctuated sequence is empty, meaning it
64    /// contains no syntax tree nodes or punctuation.
65    pub fn is_empty(&self) -> bool {
66        self.inner.len() == 0 && self.last.is_none()
67    }
68
69    /// Returns the number of syntax tree nodes in this punctuated sequence.
70    ///
71    /// This is the number of nodes of type `T`, not counting the punctuation of
72    /// type `P`.
73    pub fn len(&self) -> usize {
74        self.inner.len() + if self.last.is_some() { 1 } else { 0 }
75    }
76
77    /// Borrows the first element in this sequence.
78    pub fn first(&self) -> Option<&T> {
79        self.iter().next()
80    }
81
82    /// Mutably borrows the first element in this sequence.
83    pub fn first_mut(&mut self) -> Option<&mut T> {
84        self.iter_mut().next()
85    }
86
87    /// Borrows the last element in this sequence.
88    pub fn last(&self) -> Option<&T> {
89        self.iter().next_back()
90    }
91
92    /// Mutably borrows the last element in this sequence.
93    pub fn last_mut(&mut self) -> Option<&mut T> {
94        self.iter_mut().next_back()
95    }
96
97    /// Borrows the element at the given index.
98    pub fn get(&self, index: usize) -> Option<&T> {
99        if let Some((value, _punct)) = self.inner.get(index) {
100            Some(value)
101        } else if index == self.inner.len() {
102            self.last.as_deref()
103        } else {
104            None
105        }
106    }
107
108    /// Mutably borrows the element at the given index.
109    pub fn get_mut(&mut self, index: usize) -> Option<&mut T> {
110        let inner_len = self.inner.len();
111        if let Some((value, _punct)) = self.inner.get_mut(index) {
112            Some(value)
113        } else if index == inner_len {
114            self.last.as_deref_mut()
115        } else {
116            None
117        }
118    }
119
120    /// Returns an iterator over borrowed syntax tree nodes of type `&T`.
121    pub fn iter(&self) -> Iter<T> {
122        Iter {
123            inner: Box::new(NoDrop::new(PrivateIter {
124                inner: self.inner.iter(),
125                last: self.last.as_ref().map(Box::as_ref).into_iter(),
126            })),
127        }
128    }
129
130    /// Returns an iterator over mutably borrowed syntax tree nodes of type
131    /// `&mut T`.
132    pub fn iter_mut(&mut self) -> IterMut<T> {
133        IterMut {
134            inner: Box::new(NoDrop::new(PrivateIterMut {
135                inner: self.inner.iter_mut(),
136                last: self.last.as_mut().map(Box::as_mut).into_iter(),
137            })),
138        }
139    }
140
141    /// Returns an iterator over the contents of this sequence as borrowed
142    /// punctuated pairs.
143    pub fn pairs(&self) -> Pairs<T, P> {
144        Pairs {
145            inner: self.inner.iter(),
146            last: self.last.as_ref().map(Box::as_ref).into_iter(),
147        }
148    }
149
150    /// Returns an iterator over the contents of this sequence as mutably
151    /// borrowed punctuated pairs.
152    pub fn pairs_mut(&mut self) -> PairsMut<T, P> {
153        PairsMut {
154            inner: self.inner.iter_mut(),
155            last: self.last.as_mut().map(Box::as_mut).into_iter(),
156        }
157    }
158
159    /// Returns an iterator over the contents of this sequence as owned
160    /// punctuated pairs.
161    pub fn into_pairs(self) -> IntoPairs<T, P> {
162        IntoPairs {
163            inner: self.inner.into_iter(),
164            last: self.last.map(|t| *t).into_iter(),
165        }
166    }
167
168    /// Appends a syntax tree node onto the end of this punctuated sequence. The
169    /// sequence must already have a trailing punctuation, or be empty.
170    ///
171    /// Use [`push`] instead if the punctuated sequence may or may not already
172    /// have trailing punctuation.
173    ///
174    /// [`push`]: Punctuated::push
175    ///
176    /// # Panics
177    ///
178    /// Panics if the sequence is nonempty and does not already have a trailing
179    /// punctuation.
180    pub fn push_value(&mut self, value: T) {
181        assert!(
182            self.empty_or_trailing(),
183            "Punctuated::push_value: cannot push value if Punctuated is missing trailing punctuation",
184        );
185
186        self.last = Some(Box::new(value));
187    }
188
189    /// Appends a trailing punctuation onto the end of this punctuated sequence.
190    /// The sequence must be non-empty and must not already have trailing
191    /// punctuation.
192    ///
193    /// # Panics
194    ///
195    /// Panics if the sequence is empty or already has a trailing punctuation.
196    pub fn push_punct(&mut self, punctuation: P) {
197        assert!(
198            self.last.is_some(),
199            "Punctuated::push_punct: cannot push punctuation if Punctuated is empty or already has trailing punctuation",
200        );
201
202        let last = self.last.take().unwrap();
203        self.inner.push((*last, punctuation));
204    }
205
206    /// Removes the last punctuated pair from this sequence, or `None` if the
207    /// sequence is empty.
208    pub fn pop(&mut self) -> Option<Pair<T, P>> {
209        if self.last.is_some() {
210            self.last.take().map(|t| Pair::End(*t))
211        } else {
212            self.inner.pop().map(|(t, p)| Pair::Punctuated(t, p))
213        }
214    }
215
216    /// Removes the trailing punctuation from this punctuated sequence, or
217    /// `None` if there isn't any.
218    pub fn pop_punct(&mut self) -> Option<P> {
219        if self.last.is_some() {
220            None
221        } else {
222            let (t, p) = self.inner.pop()?;
223            self.last = Some(Box::new(t));
224            Some(p)
225        }
226    }
227
228    /// Determines whether this punctuated sequence ends with a trailing
229    /// punctuation.
230    pub fn trailing_punct(&self) -> bool {
231        self.last.is_none() && !self.is_empty()
232    }
233
234    /// Returns true if either this `Punctuated` is empty, or it has a trailing
235    /// punctuation.
236    ///
237    /// Equivalent to `punctuated.is_empty() || punctuated.trailing_punct()`.
238    pub fn empty_or_trailing(&self) -> bool {
239        self.last.is_none()
240    }
241
242    /// Appends a syntax tree node onto the end of this punctuated sequence.
243    ///
244    /// If there is not a trailing punctuation in this sequence when this method
245    /// is called, the default value of punctuation type `P` is inserted before
246    /// the given value of type `T`.
247    pub fn push(&mut self, value: T)
248    where
249        P: Default,
250    {
251        if !self.empty_or_trailing() {
252            self.push_punct(Default::default());
253        }
254        self.push_value(value);
255    }
256
257    /// Inserts an element at position `index`.
258    ///
259    /// # Panics
260    ///
261    /// Panics if `index` is greater than the number of elements previously in
262    /// this punctuated sequence.
263    pub fn insert(&mut self, index: usize, value: T)
264    where
265        P: Default,
266    {
267        assert!(
268            index <= self.len(),
269            "Punctuated::insert: index out of range",
270        );
271
272        if index == self.len() {
273            self.push(value);
274        } else {
275            self.inner.insert(index, (value, Default::default()));
276        }
277    }
278
279    /// Clears the sequence of all values and punctuation, making it empty.
280    pub fn clear(&mut self) {
281        self.inner.clear();
282        self.last = None;
283    }
284
285    /// Parses zero or more occurrences of `T` separated by punctuation of type
286    /// `P`, with optional trailing punctuation.
287    ///
288    /// Parsing continues until the end of this parse stream. The entire content
289    /// of this parse stream must consist of `T` and `P`.
290    #[cfg(feature = "parsing")]
291    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
292    pub fn parse_terminated(input: ParseStream) -> Result<Self>
293    where
294        T: Parse,
295        P: Parse,
296    {
297        Self::parse_terminated_with(input, T::parse)
298    }
299
300    /// Parses zero or more occurrences of `T` using the given parse function,
301    /// separated by punctuation of type `P`, with optional trailing
302    /// punctuation.
303    ///
304    /// Like [`parse_terminated`], the entire content of this stream is expected
305    /// to be parsed.
306    ///
307    /// [`parse_terminated`]: Punctuated::parse_terminated
308    #[cfg(feature = "parsing")]
309    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
310    pub fn parse_terminated_with<'a>(
311        input: ParseStream<'a>,
312        parser: fn(ParseStream<'a>) -> Result<T>,
313    ) -> Result<Self>
314    where
315        P: Parse,
316    {
317        let mut punctuated = Punctuated::new();
318
319        loop {
320            if input.is_empty() {
321                break;
322            }
323            let value = parser(input)?;
324            punctuated.push_value(value);
325            if input.is_empty() {
326                break;
327            }
328            let punct = input.parse()?;
329            punctuated.push_punct(punct);
330        }
331
332        Ok(punctuated)
333    }
334
335    /// Parses one or more occurrences of `T` separated by punctuation of type
336    /// `P`, not accepting trailing punctuation.
337    ///
338    /// Parsing continues as long as punctuation `P` is present at the head of
339    /// the stream. This method returns upon parsing a `T` and observing that it
340    /// is not followed by a `P`, even if there are remaining tokens in the
341    /// stream.
342    #[cfg(feature = "parsing")]
343    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
344    pub fn parse_separated_nonempty(input: ParseStream) -> Result<Self>
345    where
346        T: Parse,
347        P: Token + Parse,
348    {
349        Self::parse_separated_nonempty_with(input, T::parse)
350    }
351
352    /// Parses one or more occurrences of `T` using the given parse function,
353    /// separated by punctuation of type `P`, not accepting trailing
354    /// punctuation.
355    ///
356    /// Like [`parse_separated_nonempty`], may complete early without parsing
357    /// the entire content of this stream.
358    ///
359    /// [`parse_separated_nonempty`]: Punctuated::parse_separated_nonempty
360    #[cfg(feature = "parsing")]
361    #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))]
362    pub fn parse_separated_nonempty_with<'a>(
363        input: ParseStream<'a>,
364        parser: fn(ParseStream<'a>) -> Result<T>,
365    ) -> Result<Self>
366    where
367        P: Token + Parse,
368    {
369        let mut punctuated = Punctuated::new();
370
371        loop {
372            let value = parser(input)?;
373            punctuated.push_value(value);
374            if !P::peek(input.cursor()) {
375                break;
376            }
377            let punct = input.parse()?;
378            punctuated.push_punct(punct);
379        }
380
381        Ok(punctuated)
382    }
383}
384
385#[cfg(feature = "clone-impls")]
386#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))]
387impl<T, P> Clone for Punctuated<T, P>
388where
389    T: Clone,
390    P: Clone,
391{
392    fn clone(&self) -> Self {
393        Punctuated {
394            inner: self.inner.clone(),
395            last: self.last.clone(),
396        }
397    }
398
399    fn clone_from(&mut self, other: &Self) {
400        self.inner.clone_from(&other.inner);
401        self.last.clone_from(&other.last);
402    }
403}
404
405#[cfg(feature = "extra-traits")]
406#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]
407impl<T, P> Eq for Punctuated<T, P>
408where
409    T: Eq,
410    P: Eq,
411{
412}
413
414#[cfg(feature = "extra-traits")]
415#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]
416impl<T, P> PartialEq for Punctuated<T, P>
417where
418    T: PartialEq,
419    P: PartialEq,
420{
421    fn eq(&self, other: &Self) -> bool {
422        let Punctuated { inner, last } = self;
423        *inner == other.inner && *last == other.last
424    }
425}
426
427#[cfg(feature = "extra-traits")]
428#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]
429impl<T, P> Hash for Punctuated<T, P>
430where
431    T: Hash,
432    P: Hash,
433{
434    fn hash<H: Hasher>(&self, state: &mut H) {
435        let Punctuated { inner, last } = self;
436        inner.hash(state);
437        last.hash(state);
438    }
439}
440
441#[cfg(feature = "extra-traits")]
442#[cfg_attr(docsrs, doc(cfg(feature = "extra-traits")))]
443impl<T: Debug, P: Debug> Debug for Punctuated<T, P> {
444    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
445        let mut list = f.debug_list();
446        for (t, p) in &self.inner {
447            list.entry(t);
448            list.entry(p);
449        }
450        if let Some(last) = &self.last {
451            list.entry(last);
452        }
453        list.finish()
454    }
455}
456
457impl<T, P> FromIterator<T> for Punctuated<T, P>
458where
459    P: Default,
460{
461    fn from_iter<I: IntoIterator<Item = T>>(i: I) -> Self {
462        let mut ret = Punctuated::new();
463        ret.extend(i);
464        ret
465    }
466}
467
468impl<T, P> Extend<T> for Punctuated<T, P>
469where
470    P: Default,
471{
472    fn extend<I: IntoIterator<Item = T>>(&mut self, i: I) {
473        for value in i {
474            self.push(value);
475        }
476    }
477}
478
479impl<T, P> FromIterator<Pair<T, P>> for Punctuated<T, P> {
480    fn from_iter<I: IntoIterator<Item = Pair<T, P>>>(i: I) -> Self {
481        let mut ret = Punctuated::new();
482        do_extend(&mut ret, i.into_iter());
483        ret
484    }
485}
486
487impl<T, P> Extend<Pair<T, P>> for Punctuated<T, P>
488where
489    P: Default,
490{
491    fn extend<I: IntoIterator<Item = Pair<T, P>>>(&mut self, i: I) {
492        if !self.empty_or_trailing() {
493            self.push_punct(P::default());
494        }
495        do_extend(self, i.into_iter());
496    }
497}
498
499fn do_extend<T, P, I>(punctuated: &mut Punctuated<T, P>, i: I)
500where
501    I: Iterator<Item = Pair<T, P>>,
502{
503    let mut nomore = false;
504    for pair in i {
505        if nomore {
506            panic!("punctuated extended with items after a Pair::End");
507        }
508        match pair {
509            Pair::Punctuated(a, b) => punctuated.inner.push((a, b)),
510            Pair::End(a) => {
511                punctuated.last = Some(Box::new(a));
512                nomore = true;
513            }
514        }
515    }
516}
517
518impl<T, P> IntoIterator for Punctuated<T, P> {
519    type Item = T;
520    type IntoIter = IntoIter<T>;
521
522    fn into_iter(self) -> Self::IntoIter {
523        let mut elements = Vec::with_capacity(self.len());
524        elements.extend(self.inner.into_iter().map(|pair| pair.0));
525        elements.extend(self.last.map(|t| *t));
526
527        IntoIter {
528            inner: elements.into_iter(),
529        }
530    }
531}
532
533impl<'a, T, P> IntoIterator for &'a Punctuated<T, P> {
534    type Item = &'a T;
535    type IntoIter = Iter<'a, T>;
536
537    fn into_iter(self) -> Self::IntoIter {
538        Punctuated::iter(self)
539    }
540}
541
542impl<'a, T, P> IntoIterator for &'a mut Punctuated<T, P> {
543    type Item = &'a mut T;
544    type IntoIter = IterMut<'a, T>;
545
546    fn into_iter(self) -> Self::IntoIter {
547        Punctuated::iter_mut(self)
548    }
549}
550
551impl<T, P> Default for Punctuated<T, P> {
552    fn default() -> Self {
553        Punctuated::new()
554    }
555}
556
557/// An iterator over borrowed pairs of type `Pair<&T, &P>`.
558///
559/// Refer to the [module documentation] for details about punctuated sequences.
560///
561/// [module documentation]: self
562pub struct Pairs<'a, T: 'a, P: 'a> {
563    inner: slice::Iter<'a, (T, P)>,
564    last: option::IntoIter<&'a T>,
565}
566
567impl<'a, T, P> Iterator for Pairs<'a, T, P> {
568    type Item = Pair<&'a T, &'a P>;
569
570    fn next(&mut self) -> Option<Self::Item> {
571        self.inner
572            .next()
573            .map(|(t, p)| Pair::Punctuated(t, p))
574            .or_else(|| self.last.next().map(Pair::End))
575    }
576
577    fn size_hint(&self) -> (usize, Option<usize>) {
578        (self.len(), Some(self.len()))
579    }
580}
581
582impl<'a, T, P> DoubleEndedIterator for Pairs<'a, T, P> {
583    fn next_back(&mut self) -> Option<Self::Item> {
584        self.last
585            .next()
586            .map(Pair::End)
587            .or_else(|| self.inner.next_back().map(|(t, p)| Pair::Punctuated(t, p)))
588    }
589}
590
591impl<'a, T, P> ExactSizeIterator for Pairs<'a, T, P> {
592    fn len(&self) -> usize {
593        self.inner.len() + self.last.len()
594    }
595}
596
597// No Clone bound on T or P.
598impl<'a, T, P> Clone for Pairs<'a, T, P> {
599    fn clone(&self) -> Self {
600        Pairs {
601            inner: self.inner.clone(),
602            last: self.last.clone(),
603        }
604    }
605}
606
607/// An iterator over mutably borrowed pairs of type `Pair<&mut T, &mut P>`.
608///
609/// Refer to the [module documentation] for details about punctuated sequences.
610///
611/// [module documentation]: self
612pub struct PairsMut<'a, T: 'a, P: 'a> {
613    inner: slice::IterMut<'a, (T, P)>,
614    last: option::IntoIter<&'a mut T>,
615}
616
617impl<'a, T, P> Iterator for PairsMut<'a, T, P> {
618    type Item = Pair<&'a mut T, &'a mut P>;
619
620    fn next(&mut self) -> Option<Self::Item> {
621        self.inner
622            .next()
623            .map(|(t, p)| Pair::Punctuated(t, p))
624            .or_else(|| self.last.next().map(Pair::End))
625    }
626
627    fn size_hint(&self) -> (usize, Option<usize>) {
628        (self.len(), Some(self.len()))
629    }
630}
631
632impl<'a, T, P> DoubleEndedIterator for PairsMut<'a, T, P> {
633    fn next_back(&mut self) -> Option<Self::Item> {
634        self.last
635            .next()
636            .map(Pair::End)
637            .or_else(|| self.inner.next_back().map(|(t, p)| Pair::Punctuated(t, p)))
638    }
639}
640
641impl<'a, T, P> ExactSizeIterator for PairsMut<'a, T, P> {
642    fn len(&self) -> usize {
643        self.inner.len() + self.last.len()
644    }
645}
646
647/// An iterator over owned pairs of type `Pair<T, P>`.
648///
649/// Refer to the [module documentation] for details about punctuated sequences.
650///
651/// [module documentation]: self
652pub struct IntoPairs<T, P> {
653    inner: vec::IntoIter<(T, P)>,
654    last: option::IntoIter<T>,
655}
656
657impl<T, P> Iterator for IntoPairs<T, P> {
658    type Item = Pair<T, P>;
659
660    fn next(&mut self) -> Option<Self::Item> {
661        self.inner
662            .next()
663            .map(|(t, p)| Pair::Punctuated(t, p))
664            .or_else(|| self.last.next().map(Pair::End))
665    }
666
667    fn size_hint(&self) -> (usize, Option<usize>) {
668        (self.len(), Some(self.len()))
669    }
670}
671
672impl<T, P> DoubleEndedIterator for IntoPairs<T, P> {
673    fn next_back(&mut self) -> Option<Self::Item> {
674        self.last
675            .next()
676            .map(Pair::End)
677            .or_else(|| self.inner.next_back().map(|(t, p)| Pair::Punctuated(t, p)))
678    }
679}
680
681impl<T, P> ExactSizeIterator for IntoPairs<T, P> {
682    fn len(&self) -> usize {
683        self.inner.len() + self.last.len()
684    }
685}
686
687impl<T, P> Clone for IntoPairs<T, P>
688where
689    T: Clone,
690    P: Clone,
691{
692    fn clone(&self) -> Self {
693        IntoPairs {
694            inner: self.inner.clone(),
695            last: self.last.clone(),
696        }
697    }
698}
699
700/// An iterator over owned values of type `T`.
701///
702/// Refer to the [module documentation] for details about punctuated sequences.
703///
704/// [module documentation]: self
705pub struct IntoIter<T> {
706    inner: vec::IntoIter<T>,
707}
708
709impl<T> Iterator for IntoIter<T> {
710    type Item = T;
711
712    fn next(&mut self) -> Option<Self::Item> {
713        self.inner.next()
714    }
715
716    fn size_hint(&self) -> (usize, Option<usize>) {
717        (self.len(), Some(self.len()))
718    }
719}
720
721impl<T> DoubleEndedIterator for IntoIter<T> {
722    fn next_back(&mut self) -> Option<Self::Item> {
723        self.inner.next_back()
724    }
725}
726
727impl<T> ExactSizeIterator for IntoIter<T> {
728    fn len(&self) -> usize {
729        self.inner.len()
730    }
731}
732
733impl<T> Clone for IntoIter<T>
734where
735    T: Clone,
736{
737    fn clone(&self) -> Self {
738        IntoIter {
739            inner: self.inner.clone(),
740        }
741    }
742}
743
744/// An iterator over borrowed values of type `&T`.
745///
746/// Refer to the [module documentation] for details about punctuated sequences.
747///
748/// [module documentation]: self
749pub struct Iter<'a, T: 'a> {
750    inner: Box<NoDrop<dyn IterTrait<'a, T> + 'a>>,
751}
752
753trait IterTrait<'a, T: 'a>: Iterator<Item = &'a T> + DoubleEndedIterator + ExactSizeIterator {
754    fn clone_box(&self) -> Box<NoDrop<dyn IterTrait<'a, T> + 'a>>;
755}
756
757struct PrivateIter<'a, T: 'a, P: 'a> {
758    inner: slice::Iter<'a, (T, P)>,
759    last: option::IntoIter<&'a T>,
760}
761
762impl<'a, T, P> TrivialDrop for PrivateIter<'a, T, P>
763where
764    slice::Iter<'a, (T, P)>: TrivialDrop,
765    option::IntoIter<&'a T>: TrivialDrop,
766{
767}
768
769#[cfg(any(feature = "full", feature = "derive"))]
770pub(crate) fn empty_punctuated_iter<'a, T>() -> Iter<'a, T> {
771    Iter {
772        inner: Box::new(NoDrop::new(iter::empty())),
773    }
774}
775
776// No Clone bound on T.
777impl<'a, T> Clone for Iter<'a, T> {
778    fn clone(&self) -> Self {
779        Iter {
780            inner: self.inner.clone_box(),
781        }
782    }
783}
784
785impl<'a, T> Iterator for Iter<'a, T> {
786    type Item = &'a T;
787
788    fn next(&mut self) -> Option<Self::Item> {
789        self.inner.next()
790    }
791
792    fn size_hint(&self) -> (usize, Option<usize>) {
793        (self.len(), Some(self.len()))
794    }
795}
796
797impl<'a, T> DoubleEndedIterator for Iter<'a, T> {
798    fn next_back(&mut self) -> Option<Self::Item> {
799        self.inner.next_back()
800    }
801}
802
803impl<'a, T> ExactSizeIterator for Iter<'a, T> {
804    fn len(&self) -> usize {
805        self.inner.len()
806    }
807}
808
809impl<'a, T, P> Iterator for PrivateIter<'a, T, P> {
810    type Item = &'a T;
811
812    fn next(&mut self) -> Option<Self::Item> {
813        self.inner
814            .next()
815            .map(|pair| &pair.0)
816            .or_else(|| self.last.next())
817    }
818}
819
820impl<'a, T, P> DoubleEndedIterator for PrivateIter<'a, T, P> {
821    fn next_back(&mut self) -> Option<Self::Item> {
822        self.last
823            .next()
824            .or_else(|| self.inner.next_back().map(|pair| &pair.0))
825    }
826}
827
828impl<'a, T, P> ExactSizeIterator for PrivateIter<'a, T, P> {
829    fn len(&self) -> usize {
830        self.inner.len() + self.last.len()
831    }
832}
833
834// No Clone bound on T or P.
835impl<'a, T, P> Clone for PrivateIter<'a, T, P> {
836    fn clone(&self) -> Self {
837        PrivateIter {
838            inner: self.inner.clone(),
839            last: self.last.clone(),
840        }
841    }
842}
843
844impl<'a, T, I> IterTrait<'a, T> for I
845where
846    T: 'a,
847    I: DoubleEndedIterator<Item = &'a T>
848        + ExactSizeIterator<Item = &'a T>
849        + Clone
850        + TrivialDrop
851        + 'a,
852{
853    fn clone_box(&self) -> Box<NoDrop<dyn IterTrait<'a, T> + 'a>> {
854        Box::new(NoDrop::new(self.clone()))
855    }
856}
857
858/// An iterator over mutably borrowed values of type `&mut T`.
859///
860/// Refer to the [module documentation] for details about punctuated sequences.
861///
862/// [module documentation]: self
863pub struct IterMut<'a, T: 'a> {
864    inner: Box<NoDrop<dyn IterMutTrait<'a, T, Item = &'a mut T> + 'a>>,
865}
866
867trait IterMutTrait<'a, T: 'a>:
868    DoubleEndedIterator<Item = &'a mut T> + ExactSizeIterator<Item = &'a mut T>
869{
870}
871
872struct PrivateIterMut<'a, T: 'a, P: 'a> {
873    inner: slice::IterMut<'a, (T, P)>,
874    last: option::IntoIter<&'a mut T>,
875}
876
877impl<'a, T, P> TrivialDrop for PrivateIterMut<'a, T, P>
878where
879    slice::IterMut<'a, (T, P)>: TrivialDrop,
880    option::IntoIter<&'a mut T>: TrivialDrop,
881{
882}
883
884#[cfg(any(feature = "full", feature = "derive"))]
885pub(crate) fn empty_punctuated_iter_mut<'a, T>() -> IterMut<'a, T> {
886    IterMut {
887        inner: Box::new(NoDrop::new(iter::empty())),
888    }
889}
890
891impl<'a, T> Iterator for IterMut<'a, T> {
892    type Item = &'a mut T;
893
894    fn next(&mut self) -> Option<Self::Item> {
895        self.inner.next()
896    }
897
898    fn size_hint(&self) -> (usize, Option<usize>) {
899        (self.len(), Some(self.len()))
900    }
901}
902
903impl<'a, T> DoubleEndedIterator for IterMut<'a, T> {
904    fn next_back(&mut self) -> Option<Self::Item> {
905        self.inner.next_back()
906    }
907}
908
909impl<'a, T> ExactSizeIterator for IterMut<'a, T> {
910    fn len(&self) -> usize {
911        self.inner.len()
912    }
913}
914
915impl<'a, T, P> Iterator for PrivateIterMut<'a, T, P> {
916    type Item = &'a mut T;
917
918    fn next(&mut self) -> Option<Self::Item> {
919        self.inner
920            .next()
921            .map(|pair| &mut pair.0)
922            .or_else(|| self.last.next())
923    }
924}
925
926impl<'a, T, P> DoubleEndedIterator for PrivateIterMut<'a, T, P> {
927    fn next_back(&mut self) -> Option<Self::Item> {
928        self.last
929            .next()
930            .or_else(|| self.inner.next_back().map(|pair| &mut pair.0))
931    }
932}
933
934impl<'a, T, P> ExactSizeIterator for PrivateIterMut<'a, T, P> {
935    fn len(&self) -> usize {
936        self.inner.len() + self.last.len()
937    }
938}
939
940impl<'a, T, I> IterMutTrait<'a, T> for I
941where
942    T: 'a,
943    I: DoubleEndedIterator<Item = &'a mut T> + ExactSizeIterator<Item = &'a mut T> + 'a,
944{
945}
946
947/// A single syntax tree node of type `T` followed by its trailing punctuation
948/// of type `P` if any.
949///
950/// Refer to the [module documentation] for details about punctuated sequences.
951///
952/// [module documentation]: self
953pub enum Pair<T, P> {
954    Punctuated(T, P),
955    End(T),
956}
957
958impl<T, P> Pair<T, P> {
959    /// Extracts the syntax tree node from this punctuated pair, discarding the
960    /// following punctuation.
961    pub fn into_value(self) -> T {
962        match self {
963            Pair::Punctuated(t, _) | Pair::End(t) => t,
964        }
965    }
966
967    /// Borrows the syntax tree node from this punctuated pair.
968    pub fn value(&self) -> &T {
969        match self {
970            Pair::Punctuated(t, _) | Pair::End(t) => t,
971        }
972    }
973
974    /// Mutably borrows the syntax tree node from this punctuated pair.
975    pub fn value_mut(&mut self) -> &mut T {
976        match self {
977            Pair::Punctuated(t, _) | Pair::End(t) => t,
978        }
979    }
980
981    /// Borrows the punctuation from this punctuated pair, unless this pair is
982    /// the final one and there is no trailing punctuation.
983    pub fn punct(&self) -> Option<&P> {
984        match self {
985            Pair::Punctuated(_, p) => Some(p),
986            Pair::End(_) => None,
987        }
988    }
989
990    /// Mutably borrows the punctuation from this punctuated pair, unless the
991    /// pair is the final one and there is no trailing punctuation.
992    ///
993    /// # Example
994    ///
995    /// ```
996    /// # use proc_macro2::Span;
997    /// # use syn::punctuated::Punctuated;
998    /// # use syn::{parse_quote, Token, TypeParamBound};
999    /// #
1000    /// # let mut punctuated = Punctuated::<TypeParamBound, Token![+]>::new();
1001    /// # let span = Span::call_site();
1002    /// #
1003    /// punctuated.insert(0, parse_quote!('lifetime));
1004    /// if let Some(punct) = punctuated.pairs_mut().next().unwrap().punct_mut() {
1005    ///     punct.span = span;
1006    /// }
1007    /// ```
1008    pub fn punct_mut(&mut self) -> Option<&mut P> {
1009        match self {
1010            Pair::Punctuated(_, p) => Some(p),
1011            Pair::End(_) => None,
1012        }
1013    }
1014
1015    /// Creates a punctuated pair out of a syntax tree node and an optional
1016    /// following punctuation.
1017    pub fn new(t: T, p: Option<P>) -> Self {
1018        match p {
1019            Some(p) => Pair::Punctuated(t, p),
1020            None => Pair::End(t),
1021        }
1022    }
1023
1024    /// Produces this punctuated pair as a tuple of syntax tree node and
1025    /// optional following punctuation.
1026    pub fn into_tuple(self) -> (T, Option<P>) {
1027        match self {
1028            Pair::Punctuated(t, p) => (t, Some(p)),
1029            Pair::End(t) => (t, None),
1030        }
1031    }
1032}
1033
1034#[cfg(feature = "clone-impls")]
1035#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))]
1036impl<T, P> Pair<&T, &P> {
1037    pub fn cloned(self) -> Pair<T, P>
1038    where
1039        T: Clone,
1040        P: Clone,
1041    {
1042        match self {
1043            Pair::Punctuated(t, p) => Pair::Punctuated(t.clone(), p.clone()),
1044            Pair::End(t) => Pair::End(t.clone()),
1045        }
1046    }
1047}
1048
1049#[cfg(feature = "clone-impls")]
1050#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))]
1051impl<T, P> Clone for Pair<T, P>
1052where
1053    T: Clone,
1054    P: Clone,
1055{
1056    fn clone(&self) -> Self {
1057        match self {
1058            Pair::Punctuated(t, p) => Pair::Punctuated(t.clone(), p.clone()),
1059            Pair::End(t) => Pair::End(t.clone()),
1060        }
1061    }
1062}
1063
1064#[cfg(feature = "clone-impls")]
1065#[cfg_attr(docsrs, doc(cfg(feature = "clone-impls")))]
1066impl<T, P> Copy for Pair<T, P>
1067where
1068    T: Copy,
1069    P: Copy,
1070{
1071}
1072
1073impl<T, P> Index<usize> for Punctuated<T, P> {
1074    type Output = T;
1075
1076    fn index(&self, index: usize) -> &Self::Output {
1077        if index == self.len() - 1 {
1078            match &self.last {
1079                Some(t) => t,
1080                None => &self.inner[index].0,
1081            }
1082        } else {
1083            &self.inner[index].0
1084        }
1085    }
1086}
1087
1088impl<T, P> IndexMut<usize> for Punctuated<T, P> {
1089    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
1090        if index == self.len() - 1 {
1091            match &mut self.last {
1092                Some(t) => t,
1093                None => &mut self.inner[index].0,
1094            }
1095        } else {
1096            &mut self.inner[index].0
1097        }
1098    }
1099}
1100
1101#[cfg(all(feature = "fold", any(feature = "full", feature = "derive")))]
1102pub(crate) fn fold<T, P, V, F>(
1103    punctuated: Punctuated<T, P>,
1104    fold: &mut V,
1105    mut f: F,
1106) -> Punctuated<T, P>
1107where
1108    V: ?Sized,
1109    F: FnMut(&mut V, T) -> T,
1110{
1111    Punctuated {
1112        inner: punctuated
1113            .inner
1114            .into_iter()
1115            .map(|(t, p)| (f(fold, t), p))
1116            .collect(),
1117        last: match punctuated.last {
1118            Some(t) => Some(Box::new(f(fold, *t))),
1119            None => None,
1120        },
1121    }
1122}
1123
1124#[cfg(feature = "printing")]
1125mod printing {
1126    use crate::punctuated::{Pair, Punctuated};
1127    use proc_macro2::TokenStream;
1128    use quote::{ToTokens, TokenStreamExt};
1129
1130    #[cfg_attr(docsrs, doc(cfg(feature = "printing")))]
1131    impl<T, P> ToTokens for Punctuated<T, P>
1132    where
1133        T: ToTokens,
1134        P: ToTokens,
1135    {
1136        fn to_tokens(&self, tokens: &mut TokenStream) {
1137            tokens.append_all(self.pairs());
1138        }
1139    }
1140
1141    #[cfg_attr(docsrs, doc(cfg(feature = "printing")))]
1142    impl<T, P> ToTokens for Pair<T, P>
1143    where
1144        T: ToTokens,
1145        P: ToTokens,
1146    {
1147        fn to_tokens(&self, tokens: &mut TokenStream) {
1148            match self {
1149                Pair::Punctuated(a, b) => {
1150                    a.to_tokens(tokens);
1151                    b.to_tokens(tokens);
1152                }
1153                Pair::End(a) => a.to_tokens(tokens),
1154            }
1155        }
1156    }
1157}
syn/punctuated.rs

syn/
punctuated.rs
