streaming_iterator/
sources.rs

1use super::{DoubleEndedStreamingIterator, StreamingIterator};
2use super::{DoubleEndedStreamingIteratorMut, StreamingIteratorMut};
3use core::marker::PhantomData;
4use core::usize;
5
6/// Turns a normal, non-streaming iterator into a streaming iterator.
7///
8/// ```
9/// # use streaming_iterator::{StreamingIterator, convert};
10/// let scores = vec![100, 50, 80];
11/// let mut streaming_iter = convert(scores);
12/// while let Some(score) = streaming_iter.next() {
13///     println!("The score is: {}", score);
14/// }
15/// ```
16#[inline]
17pub fn convert<I>(it: I) -> Convert<I::IntoIter>
18where
19    I: IntoIterator,
20{
21    Convert {
22        it: it.into_iter(),
23        item: None,
24    }
25}
26
27/// Turns an iterator of references into a streaming iterator.
28///
29/// ```
30/// # use streaming_iterator::{StreamingIterator, convert_ref};
31/// let scores = vec![100, 50, 80];
32/// let mut streaming_iter = convert_ref(&scores);
33/// while let Some(score) = streaming_iter.next() {
34///     println!("The score is: {}", score);
35/// }
36/// ```
37#[inline]
38pub fn convert_ref<'a, I, T: ?Sized>(iterator: I) -> ConvertRef<'a, I::IntoIter, T>
39where
40    I: IntoIterator<Item = &'a T>,
41{
42    ConvertRef {
43        it: iterator.into_iter(),
44        item: None,
45    }
46}
47
48/// Turns an iterator of mutable references into a streaming iterator.
49///
50/// ```
51/// # use streaming_iterator::{StreamingIteratorMut, convert_mut};
52/// let mut scores = vec![Some(100), None, Some(80)];
53/// {
54///     let mut streaming_iter = convert_mut(&mut scores);
55///     while let Some(opt_score) = streaming_iter.next_mut() {
56///         if let Some(score) = opt_score.take() {
57///             println!("The score is: {}", score);
58///         }
59///         // else already reported
60///     }
61/// }
62/// assert_eq!(scores, [None, None, None]);
63/// ```
64#[inline]
65pub fn convert_mut<'a, I, T: ?Sized>(iterator: I) -> ConvertMut<'a, I::IntoIter, T>
66where
67    I: IntoIterator<Item = &'a mut T>,
68{
69    ConvertMut {
70        it: iterator.into_iter(),
71        item: None,
72    }
73}
74
75/// Creates an empty iterator.
76///
77/// ```
78/// # use streaming_iterator::StreamingIterator;
79/// let mut streaming_iter = streaming_iterator::empty::<i32>();
80/// assert_eq!(streaming_iter.next(), None);
81/// ```
82#[inline]
83pub fn empty<T>() -> Empty<T> {
84    Empty {
85        phantom: PhantomData,
86    }
87}
88
89/// Creates an iterator that returns items from a function call.
90///
91/// ```
92/// # use streaming_iterator::StreamingIterator;
93/// let mut count = 0;
94/// let mut streaming_iter = streaming_iterator::from_fn(|| {
95///     count += 1;
96///     if count < 4 { Some(count) } else { None }
97/// });
98/// assert_eq!(streaming_iter.next(), Some(&1));
99/// assert_eq!(streaming_iter.next(), Some(&2));
100/// assert_eq!(streaming_iter.next(), Some(&3));
101/// assert_eq!(streaming_iter.next(), None);
102/// ```
103#[inline]
104pub fn from_fn<T, F: FnMut() -> Option<T>>(gen: F) -> FromFn<T, F> {
105    FromFn { gen, item: None }
106}
107
108/// Creates an iterator that returns exactly one item.
109///
110/// ```
111/// # use streaming_iterator::StreamingIterator;
112/// let mut streaming_iter = streaming_iterator::once(1);
113/// assert_eq!(streaming_iter.next(), Some(&1));
114/// assert_eq!(streaming_iter.next(), None);
115/// ```
116#[inline]
117pub fn once<T>(item: T) -> Once<T> {
118    Once {
119        first: true,
120        item: Some(item),
121    }
122}
123
124/// Creates an iterator that returns exactly one item from a function call.
125///
126/// ```
127/// # use streaming_iterator::StreamingIterator;
128/// #[derive(Debug, PartialEq)]
129/// struct Expensive(i32);
130/// let mut streaming_iter = streaming_iterator::once_with(|| Expensive(1));
131/// assert_eq!(streaming_iter.next(), Some(&Expensive(1)));
132/// assert_eq!(streaming_iter.next(), None);
133/// ```
134#[inline]
135pub fn once_with<T, F: FnOnce() -> T>(gen: F) -> OnceWith<T, F> {
136    OnceWith {
137        gen: Some(gen),
138        item: None,
139    }
140}
141
142/// Creates an iterator that returns an item endlessly.
143///
144/// ```
145/// # use streaming_iterator::StreamingIterator;
146/// let mut streaming_iter = streaming_iterator::repeat(1);
147/// assert_eq!(streaming_iter.next(), Some(&1));
148/// assert_eq!(streaming_iter.next(), Some(&1));
149/// assert_eq!(streaming_iter.next(), Some(&1));
150/// assert_eq!(streaming_iter.next(), Some(&1));
151/// assert_eq!(streaming_iter.next(), Some(&1));
152/// // ...
153/// ```
154#[inline]
155pub fn repeat<T>(item: T) -> Repeat<T> {
156    Repeat { item }
157}
158
159/// Creates an iterator that endlessly returns items from a function call.
160///
161/// ```
162/// # use streaming_iterator::StreamingIterator;
163/// let mut count = 0;
164/// let mut streaming_iter = streaming_iterator::repeat_with(|| {
165///     count += 1;
166///     count
167/// });
168/// assert_eq!(streaming_iter.next(), Some(&1));
169/// assert_eq!(streaming_iter.next(), Some(&2));
170/// assert_eq!(streaming_iter.next(), Some(&3));
171/// assert_eq!(streaming_iter.next(), Some(&4));
172/// assert_eq!(streaming_iter.next(), Some(&5));
173/// // ...
174/// ```
175#[inline]
176pub fn repeat_with<T, F: FnMut() -> T>(gen: F) -> RepeatWith<T, F> {
177    RepeatWith { gen, item: None }
178}
179
180/// Creates an iterator where each successive item is computed from the preceding one.
181///
182/// ```
183/// # use streaming_iterator::StreamingIterator;
184/// let mut streaming_iter = streaming_iterator::successors(
185///     Some(1),
186///     |count| if count < 3 { Some(count + 1) } else { None },
187/// );
188/// assert_eq!(streaming_iter.next(), Some(&1));
189/// assert_eq!(streaming_iter.next(), Some(&2));
190/// assert_eq!(streaming_iter.next(), Some(&3));
191/// assert_eq!(streaming_iter.next(), None);
192/// ```
193#[inline]
194pub fn successors<T, F: FnMut(T) -> Option<T>>(first: Option<T>, succ: F) -> Successors<T, F> {
195    Successors {
196        first: true,
197        item: first,
198        succ,
199    }
200}
201
202/// A streaming iterator which yields elements from a normal, non-streaming, iterator.
203#[derive(Clone, Debug)]
204pub struct Convert<I>
205where
206    I: Iterator,
207{
208    it: I,
209    item: Option<I::Item>,
210}
211
212impl<I> StreamingIterator for Convert<I>
213where
214    I: Iterator,
215{
216    type Item = I::Item;
217
218    #[inline]
219    fn advance(&mut self) {
220        self.item = self.it.next();
221    }
222
223    #[inline]
224    fn get(&self) -> Option<&I::Item> {
225        self.item.as_ref()
226    }
227
228    #[inline]
229    fn size_hint(&self) -> (usize, Option<usize>) {
230        self.it.size_hint()
231    }
232
233    #[inline]
234    fn count(self) -> usize {
235        self.it.count()
236    }
237
238    #[inline]
239    fn fold<Acc, Fold>(self, init: Acc, mut f: Fold) -> Acc
240    where
241        Self: Sized,
242        Fold: FnMut(Acc, &Self::Item) -> Acc,
243    {
244        self.it.fold(init, move |acc, item| f(acc, &item))
245    }
246}
247
248impl<I> DoubleEndedStreamingIterator for Convert<I>
249where
250    I: DoubleEndedIterator,
251{
252    #[inline]
253    fn advance_back(&mut self) {
254        self.item = self.it.next_back();
255    }
256
257    #[inline]
258    fn rfold<Acc, Fold>(self, init: Acc, mut f: Fold) -> Acc
259    where
260        Self: Sized,
261        Fold: FnMut(Acc, &Self::Item) -> Acc,
262    {
263        self.it.rfold(init, move |acc, item| f(acc, &item))
264    }
265}
266
267impl<I> StreamingIteratorMut for Convert<I>
268where
269    I: Iterator,
270{
271    #[inline]
272    fn get_mut(&mut self) -> Option<&mut I::Item> {
273        self.item.as_mut()
274    }
275
276    #[inline]
277    fn fold_mut<B, F>(self, init: B, mut f: F) -> B
278    where
279        Self: Sized,
280        F: FnMut(B, &mut Self::Item) -> B,
281    {
282        self.it.fold(init, move |acc, mut item| f(acc, &mut item))
283    }
284}
285
286impl<I> DoubleEndedStreamingIteratorMut for Convert<I>
287where
288    I: DoubleEndedIterator,
289{
290    #[inline]
291    fn rfold_mut<B, F>(self, init: B, mut f: F) -> B
292    where
293        Self: Sized,
294        F: FnMut(B, &mut Self::Item) -> B,
295    {
296        self.it.rfold(init, move |acc, mut item| f(acc, &mut item))
297    }
298}
299
300/// A streaming iterator which yields elements from an iterator of references.
301#[derive(Clone, Debug)]
302pub struct ConvertRef<'a, I, T: ?Sized>
303where
304    I: Iterator<Item = &'a T>,
305{
306    it: I,
307    item: Option<&'a T>,
308}
309
310impl<'a, I, T: ?Sized> StreamingIterator for ConvertRef<'a, I, T>
311where
312    I: Iterator<Item = &'a T>,
313{
314    type Item = T;
315
316    #[inline]
317    fn advance(&mut self) {
318        self.item = self.it.next();
319    }
320
321    #[inline]
322    fn get(&self) -> Option<&T> {
323        self.item
324    }
325
326    #[inline]
327    fn size_hint(&self) -> (usize, Option<usize>) {
328        self.it.size_hint()
329    }
330
331    #[inline]
332    fn count(self) -> usize {
333        self.it.count()
334    }
335
336    #[inline]
337    fn fold<Acc, Fold>(self, init: Acc, f: Fold) -> Acc
338    where
339        Self: Sized,
340        Fold: FnMut(Acc, &Self::Item) -> Acc,
341    {
342        self.it.fold(init, f)
343    }
344}
345
346impl<'a, I, T: ?Sized> DoubleEndedStreamingIterator for ConvertRef<'a, I, T>
347where
348    I: DoubleEndedIterator<Item = &'a T>,
349{
350    #[inline]
351    fn advance_back(&mut self) {
352        self.item = self.it.next_back();
353    }
354
355    #[inline]
356    fn rfold<Acc, Fold>(self, init: Acc, f: Fold) -> Acc
357    where
358        Self: Sized,
359        Fold: FnMut(Acc, &Self::Item) -> Acc,
360    {
361        self.it.rfold(init, f)
362    }
363}
364
365/// A streaming iterator which yields elements from an iterator of mutable references.
366#[derive(Debug)]
367pub struct ConvertMut<'a, I, T: ?Sized>
368where
369    I: Iterator<Item = &'a mut T>,
370{
371    it: I,
372    item: Option<&'a mut T>,
373}
374
375impl<'a, I, T: ?Sized> StreamingIterator for ConvertMut<'a, I, T>
376where
377    I: Iterator<Item = &'a mut T>,
378{
379    type Item = T;
380
381    #[inline]
382    fn advance(&mut self) {
383        self.item = self.it.next();
384    }
385
386    #[inline]
387    fn get(&self) -> Option<&T> {
388        match self.item {
389            Some(&mut ref item) => Some(item),
390            None => None,
391        }
392    }
393
394    #[inline]
395    fn size_hint(&self) -> (usize, Option<usize>) {
396        self.it.size_hint()
397    }
398
399    #[inline]
400    fn count(self) -> usize {
401        self.it.count()
402    }
403
404    #[inline]
405    fn fold<Acc, Fold>(self, init: Acc, mut f: Fold) -> Acc
406    where
407        Self: Sized,
408        Fold: FnMut(Acc, &Self::Item) -> Acc,
409    {
410        self.it.fold(init, move |acc, item| f(acc, item))
411    }
412}
413
414impl<'a, I, T: ?Sized> DoubleEndedStreamingIterator for ConvertMut<'a, I, T>
415where
416    I: DoubleEndedIterator<Item = &'a mut T>,
417{
418    #[inline]
419    fn advance_back(&mut self) {
420        self.item = self.it.next_back();
421    }
422
423    #[inline]
424    fn rfold<Acc, Fold>(self, init: Acc, mut f: Fold) -> Acc
425    where
426        Self: Sized,
427        Fold: FnMut(Acc, &Self::Item) -> Acc,
428    {
429        self.it.rfold(init, move |acc, item| f(acc, item))
430    }
431}
432
433impl<'a, I, T: ?Sized> StreamingIteratorMut for ConvertMut<'a, I, T>
434where
435    I: Iterator<Item = &'a mut T>,
436{
437    #[inline]
438    fn get_mut(&mut self) -> Option<&mut Self::Item> {
439        match self.item {
440            Some(&mut ref mut item) => Some(item),
441            None => None,
442        }
443    }
444
445    #[inline]
446    fn fold_mut<B, F>(self, init: B, f: F) -> B
447    where
448        Self: Sized,
449        F: FnMut(B, &mut Self::Item) -> B,
450    {
451        self.it.fold(init, f)
452    }
453}
454
455impl<'a, I, T: ?Sized> DoubleEndedStreamingIteratorMut for ConvertMut<'a, I, T>
456where
457    I: DoubleEndedIterator<Item = &'a mut T>,
458{
459    #[inline]
460    fn rfold_mut<B, F>(self, init: B, f: F) -> B
461    where
462        Self: Sized,
463        F: FnMut(B, &mut Self::Item) -> B,
464    {
465        self.it.rfold(init, f)
466    }
467}
468
469/// A simple iterator that returns nothing.
470#[derive(Clone, Debug)]
471pub struct Empty<T> {
472    phantom: PhantomData<T>,
473}
474
475impl<T> StreamingIterator for Empty<T> {
476    type Item = T;
477
478    #[inline]
479    fn advance(&mut self) {}
480
481    #[inline]
482    fn get(&self) -> Option<&Self::Item> {
483        None
484    }
485
486    #[inline]
487    fn size_hint(&self) -> (usize, Option<usize>) {
488        (0, Some(0))
489    }
490}
491
492impl<T> DoubleEndedStreamingIterator for Empty<T> {
493    #[inline]
494    fn advance_back(&mut self) {}
495}
496
497impl<T> StreamingIteratorMut for Empty<T> {
498    #[inline]
499    fn get_mut(&mut self) -> Option<&mut Self::Item> {
500        None
501    }
502}
503
504impl<T> DoubleEndedStreamingIteratorMut for Empty<T> {}
505
506/// A simple iterator that returns items from a function call.
507#[derive(Clone, Debug)]
508pub struct FromFn<T, F> {
509    gen: F,
510    item: Option<T>,
511}
512
513impl<T, F: FnMut() -> Option<T>> StreamingIterator for FromFn<T, F> {
514    type Item = T;
515
516    #[inline]
517    fn advance(&mut self) {
518        self.item = (self.gen)();
519    }
520
521    #[inline]
522    fn get(&self) -> Option<&Self::Item> {
523        self.item.as_ref()
524    }
525}
526
527impl<T, F: FnMut() -> Option<T>> StreamingIteratorMut for FromFn<T, F> {
528    #[inline]
529    fn get_mut(&mut self) -> Option<&mut Self::Item> {
530        self.item.as_mut()
531    }
532}
533
534/// A simple iterator that returns exactly one item.
535#[derive(Clone, Debug)]
536pub struct Once<T> {
537    first: bool,
538    item: Option<T>,
539}
540
541impl<T> StreamingIterator for Once<T> {
542    type Item = T;
543
544    #[inline]
545    fn advance(&mut self) {
546        if self.first {
547            self.first = false;
548        } else {
549            self.item = None;
550        }
551    }
552
553    #[inline]
554    fn get(&self) -> Option<&Self::Item> {
555        self.item.as_ref()
556    }
557
558    #[inline]
559    fn size_hint(&self) -> (usize, Option<usize>) {
560        let len = self.first as usize;
561        (len, Some(len))
562    }
563}
564
565impl<T> DoubleEndedStreamingIterator for Once<T> {
566    #[inline]
567    fn advance_back(&mut self) {
568        self.advance();
569    }
570}
571
572impl<T> StreamingIteratorMut for Once<T> {
573    #[inline]
574    fn get_mut(&mut self) -> Option<&mut Self::Item> {
575        self.item.as_mut()
576    }
577}
578
579impl<T> DoubleEndedStreamingIteratorMut for Once<T> {}
580
581/// A simple iterator that returns exactly one item from a function call.
582#[derive(Clone, Debug)]
583pub struct OnceWith<T, F> {
584    gen: Option<F>,
585    item: Option<T>,
586}
587
588impl<T, F: FnOnce() -> T> StreamingIterator for OnceWith<T, F> {
589    type Item = T;
590
591    #[inline]
592    fn advance(&mut self) {
593        self.item = self.gen.take().map(|gen| gen());
594    }
595
596    #[inline]
597    fn get(&self) -> Option<&Self::Item> {
598        self.item.as_ref()
599    }
600
601    #[inline]
602    fn size_hint(&self) -> (usize, Option<usize>) {
603        let len = self.gen.is_some() as usize;
604        (len, Some(len))
605    }
606}
607
608impl<T, F: FnOnce() -> T> DoubleEndedStreamingIterator for OnceWith<T, F> {
609    #[inline]
610    fn advance_back(&mut self) {
611        self.advance();
612    }
613}
614
615impl<T, F: FnOnce() -> T> StreamingIteratorMut for OnceWith<T, F> {
616    #[inline]
617    fn get_mut(&mut self) -> Option<&mut Self::Item> {
618        self.item.as_mut()
619    }
620}
621
622impl<T, F: FnOnce() -> T> DoubleEndedStreamingIteratorMut for OnceWith<T, F> {}
623
624/// A simple iterator that repeats an item endlessly.
625///
626/// Note: if the item is modified through `StreamingIteratorMut`,
627/// this will continue be reflected in further iterations!
628#[derive(Clone, Debug)]
629pub struct Repeat<T> {
630    item: T,
631}
632
633impl<T> StreamingIterator for Repeat<T> {
634    type Item = T;
635
636    #[inline]
637    fn advance(&mut self) {}
638
639    #[inline]
640    fn get(&self) -> Option<&Self::Item> {
641        Some(&self.item)
642    }
643
644    #[inline]
645    fn size_hint(&self) -> (usize, Option<usize>) {
646        (usize::MAX, None)
647    }
648}
649
650impl<T> DoubleEndedStreamingIterator for Repeat<T> {
651    #[inline]
652    fn advance_back(&mut self) {}
653}
654
655impl<T> StreamingIteratorMut for Repeat<T> {
656    #[inline]
657    fn get_mut(&mut self) -> Option<&mut Self::Item> {
658        Some(&mut self.item)
659    }
660}
661
662impl<T> DoubleEndedStreamingIteratorMut for Repeat<T> {}
663
664/// A simple iterator that endlessly returns items from a function call.
665#[derive(Clone, Debug)]
666pub struct RepeatWith<T, F> {
667    gen: F,
668    item: Option<T>,
669}
670
671impl<T, F: FnMut() -> T> StreamingIterator for RepeatWith<T, F> {
672    type Item = T;
673
674    #[inline]
675    fn advance(&mut self) {
676        self.item = Some((self.gen)());
677    }
678
679    #[inline]
680    fn get(&self) -> Option<&Self::Item> {
681        self.item.as_ref()
682    }
683
684    #[inline]
685    fn size_hint(&self) -> (usize, Option<usize>) {
686        (usize::MAX, None)
687    }
688}
689
690impl<T, F: FnMut() -> T> StreamingIteratorMut for RepeatWith<T, F> {
691    #[inline]
692    fn get_mut(&mut self) -> Option<&mut Self::Item> {
693        self.item.as_mut()
694    }
695}
696
697/// An iterator where each successive item is computed from the preceding one.
698///
699/// Note: if an item is modified through `StreamingIteratorMut`, those changes
700/// will be visible to the successor function when the iterator is advanced.
701#[derive(Clone, Debug)]
702pub struct Successors<T, F> {
703    first: bool,
704    item: Option<T>,
705    succ: F,
706}
707
708impl<T, F: FnMut(T) -> Option<T>> StreamingIterator for Successors<T, F> {
709    type Item = T;
710
711    #[inline]
712    fn advance(&mut self) {
713        if self.first {
714            self.first = false;
715        } else if let Some(item) = self.item.take() {
716            self.item = (self.succ)(item);
717        }
718    }
719
720    #[inline]
721    fn get(&self) -> Option<&Self::Item> {
722        self.item.as_ref()
723    }
724
725    #[inline]
726    fn size_hint(&self) -> (usize, Option<usize>) {
727        match (self.first, &self.item) {
728            // We have a first item and unknown successors
729            (true, &Some(_)) => (1, None),
730            // We only have unknown successors
731            (false, &Some(_)) => (0, None),
732            // We have nothing.
733            (_, &None) => (0, Some(0)),
734        }
735    }
736}
737
738impl<T, F: FnMut(T) -> Option<T>> StreamingIteratorMut for Successors<T, F> {
739    #[inline]
740    fn get_mut(&mut self) -> Option<&mut Self::Item> {
741        self.item.as_mut()
742    }
743}
streaming_iterator/sources.rs

streaming_iterator/
sources.rs
