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