oxedyne/fe2o3 — fe2o3_text/tests/annealer_corpus/rayon

oxedyne/fe2o3/fe2o3_text/tests/annealer_corpus/rayon_iter.rs

117 KiB, 1 run

created by r1870400018:11782, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	//! Traits for writing parallel programs using an iterator-style interface
2	//!
3	//! You will rarely need to interact with this module directly unless you have
4	//! need to name one of the iterator types.
5	//!
6	//! Parallel iterators make it easy to write iterator-like chains that
7	//! execute in parallel: typically all you have to do is convert the
8	//! first `.iter()` (or `iter_mut()`, `into_iter()`, etc) method into
9	//! `par_iter()` (or `par_iter_mut()`, `into_par_iter()`, etc). For
10	//! example, to compute the sum of the squares of a sequence of
11	//! integers, one might write:
12	//!
13	//! ```rust
14	//! use rayon::prelude::*;
15	//! fn sum_of_squares(input: &[i32]) -> i32 {
16	//! input.par_iter()
17	//! .map(\|i\| i * i)
18	//! .sum()
19	//! }
20	//! ```
21	//!
22	//! Or, to increment all the integers in a slice, you could write:
23	//!
24	//! ```rust
25	//! use rayon::prelude::*;
26	//! fn increment_all(input: &mut [i32]) {
27	//! input.par_iter_mut()
28	//! .for_each(\|p\| *p += 1);
29	//! }
30	//! ```
31	//!
32	//! To use parallel iterators, first import the traits by adding
33	//! something like `use rayon::prelude::*` to your module. You can
34	//! then call `par_iter`, `par_iter_mut`, or `into_par_iter` to get a
35	//! parallel iterator. Like a [regular iterator][], parallel
36	//! iterators work by first constructing a computation and then
37	//! executing it.
38	//!
39	//! In addition to `par_iter()` and friends, some types offer other
40	//! ways to create (or consume) parallel iterators:
41	//!
42	//! - Slices (`&[T]`, `&mut [T]`) offer methods like `par_split` and
43	//! `par_windows`, as well as various parallel sorting
44	//! operations. See [the `ParallelSlice` trait] for the full list.
45	//! - Strings (`&str`) offer methods like `par_split` and `par_lines`.
46	//! See [the `ParallelString` trait] for the full list.
47	//! - Various collections offer [`par_extend`], which grows a
48	//! collection given a parallel iterator. (If you don't have a
49	//! collection to extend, you can use [`collect()`] to create a new
50	//! one from scratch.)
51	//!
52	//! [the `ParallelSlice` trait]: crate::slice::ParallelSlice
53	//! [the `ParallelString` trait]: crate::str::ParallelString
54	//! [`par_extend`]: ParallelExtend
55	//! [`collect()`]: ParallelIterator::collect()
56	//!
57	//! To see the full range of methods available on parallel iterators,
58	//! check out the [`ParallelIterator`] and [`IndexedParallelIterator`]
59	//! traits.
60	//!
61	//! If you'd like to build a custom parallel iterator, or to write your own
62	//! combinator, then check out the [split] function and the [plumbing] module.
63	//!
64	//! [regular iterator]: Iterator
65	//! [split]: split()
66	//! [plumbing]: plumbing
67	//!
68	//! Note: Several of the `ParallelIterator` methods rely on a `Try` trait which
69	//! has been deliberately obscured from the public API. This trait is intended
70	//! to mirror the unstable `std::ops::Try` with implementations for `Option` and
71	//! `Result`, where `Some`/`Ok` values will let those iterators continue, but
72	//! `None`/`Err` values will exit early.
73	//!
74	//! A note about
75	//! [dyn compatiblity](https://doc.rust-lang.org/reference/items/traits.html#dyn-compatibility):
76	//! It is currently _not_ possible to wrap a `ParallelIterator` (or any trait
77	//! that depends on it) using a `Box<dyn ParallelIterator>` or other kind of
78	//! dynamic allocation, because `ParallelIterator` is not dyn-compatible.
79	//! (This keeps the implementation simpler and allows extra optimizations.)
80
81	use self::plumbing::*;
82	pub use either::Either;
83	use std::cmp::Ordering;
84	use std::collections::LinkedList;
85	use std::convert::Infallible;
86	use std::iter::{Product, Sum};
87	use std::ops::ControlFlow;
88	use std::ops::{Fn, RangeBounds};
89	use std::task::Poll;
90
91	pub mod plumbing;
92
93	#[cfg(test)]
94	mod test;
95
96	// There is a method to the madness here:
97	//
98	// - These modules are private but expose certain types to the end-user
99	// (e.g., `enumerate::Enumerate`) -- specifically, the types that appear in the
100	// public API surface of the `ParallelIterator` traits.
101	// - In this module, those public types are always used unprefixed, which forces
102	// us to add a `pub use` and helps identify if we missed anything.
103	// - In contrast, items that appear only in the body of a method,
104	// e.g. `find::find()`, are always used prefixed, so that they
105	// can be readily distinguished.
106
107	mod blocks;
108	mod chain;
109	mod chunks;
110	mod cloned;
111	mod collect;
112	mod copied;
113	mod empty;
114	mod enumerate;
115	mod extend;
116	mod filter;
117	mod filter_map;
118	mod find;
119	mod find_first_last;
120	mod flat_map;
121	mod flat_map_iter;
122	mod flatten;
123	mod flatten_iter;
124	mod fold;
125	mod fold_chunks;
126	mod fold_chunks_with;
127	mod for_each;
128	mod from_par_iter;
129	mod inspect;
130	mod interleave;
131	mod interleave_shortest;
132	mod intersperse;
133	mod len;
134	mod map;
135	mod map_with;
136	mod multizip;
137	mod noop;
138	mod once;
139	mod panic_fuse;
140	mod par_bridge;
141	mod positions;
142	mod product;
143	mod reduce;
144	mod repeat;
145	mod rev;
146	mod skip;
147	mod skip_any;
148	mod skip_any_while;
149	mod splitter;
150	mod step_by;
151	mod sum;
152	mod take;
153	mod take_any;
154	mod take_any_while;
155	mod try_fold;
156	mod try_reduce;
157	mod try_reduce_with;
158	mod unzip;
159	mod update;
160	mod walk_tree;
161	mod while_some;
162	mod zip;
163	mod zip_eq;
164
165	pub use self::{
166	blocks::{ExponentialBlocks, UniformBlocks},
167	chain::Chain,
168	chunks::Chunks,
169	cloned::Cloned,
170	copied::Copied,
171	empty::{Empty, empty},
172	enumerate::Enumerate,
173	filter::Filter,
174	filter_map::FilterMap,
175	flat_map::FlatMap,
176	flat_map_iter::FlatMapIter,
177	flatten::Flatten,
178	flatten_iter::FlattenIter,
179	fold::{Fold, FoldWith},
180	fold_chunks::FoldChunks,
181	fold_chunks_with::FoldChunksWith,
182	inspect::Inspect,
183	interleave::Interleave,
184	interleave_shortest::InterleaveShortest,
185	intersperse::Intersperse,
186	len::{MaxLen, MinLen},
187	map::Map,
188	map_with::{MapInit, MapWith},
189	multizip::MultiZip,
190	once::{Once, once},
191	panic_fuse::PanicFuse,
192	par_bridge::{IterBridge, ParallelBridge},
193	positions::Positions,
194	repeat::{Repeat, RepeatN, repeat, repeat_n},
195	rev::Rev,
196	skip::Skip,
197	skip_any::SkipAny,
198	skip_any_while::SkipAnyWhile,
199	splitter::{Split, split},
200	step_by::StepBy,
201	take::Take,
202	take_any::TakeAny,
203	take_any_while::TakeAnyWhile,
204	try_fold::{TryFold, TryFoldWith},
205	update::Update,
206	walk_tree::{
207	WalkTree, WalkTreePostfix, WalkTreePrefix, walk_tree, walk_tree_postfix, walk_tree_prefix,
208	},
209	while_some::WhileSome,
210	zip::Zip,
211	zip_eq::ZipEq,
212	};
213
214	#[expect(deprecated)]
215	pub use repeat::repeatn;
216
217	/// `IntoParallelIterator` implements the conversion to a [`ParallelIterator`].
218	///
219	/// By implementing `IntoParallelIterator` for a type, you define how it will
220	/// transformed into an iterator. This is a parallel version of the standard
221	/// library's [`std::iter::IntoIterator`] trait.
222	pub trait IntoParallelIterator {
223	/// The parallel iterator type that will be created.
224	type Iter: ParallelIterator<Item = Self::Item>;
225
226	/// The type of item that the parallel iterator will produce.
227	type Item: Send;
228
229	/// Converts `self` into a parallel iterator.
230	///
231	/// # Examples
232	///
233	/// ```
234	/// use rayon::prelude::*;
235	///
236	/// println!("counting in parallel:");
237	/// (0..100).into_par_iter()
238	/// .for_each(\|i\| println!("{}", i));
239	/// ```
240	///
241	/// This conversion is often implicit for arguments to methods like [`zip`].
242	///
243	/// ```
244	/// use rayon::prelude::*;
245	///
246	/// let v: Vec<_> = (0..5).into_par_iter().zip(5..10).collect();
247	/// assert_eq!(v, [(0, 5), (1, 6), (2, 7), (3, 8), (4, 9)]);
248	/// ```
249	///
250	/// [`zip`]: IndexedParallelIterator::zip()
251	fn into_par_iter(self) -> Self::Iter;
252	}
253
254	/// `IntoParallelRefIterator` implements the conversion to a
255	/// [`ParallelIterator`], providing shared references to the data.
256	///
257	/// This is a parallel version of the `iter()` method
258	/// defined by various collections.
259	///
260	/// This trait is automatically implemented
261	/// `for I where &I: IntoParallelIterator`. In most cases, users
262	/// will want to implement [`IntoParallelIterator`] rather than implement
263	/// this trait directly.
264	pub trait IntoParallelRefIterator<'data> {
265	/// The type of the parallel iterator that will be returned.
266	type Iter: ParallelIterator<Item = Self::Item>;
267
268	/// The type of item that the parallel iterator will produce.
269	/// This will typically be an `&'data T` reference type.
270	type Item: Send + 'data;
271
272	/// Converts `self` into a parallel iterator.
273	///
274	/// # Examples
275	///
276	/// ```
277	/// use rayon::prelude::*;
278	///
279	/// let v: Vec<_> = (0..100).collect();
280	/// assert_eq!(v.par_iter().sum::<i32>(), 100 * 99 / 2);
281	///
282	/// // `v.par_iter()` is shorthand for `(&v).into_par_iter()`,
283	/// // producing the exact same references.
284	/// assert!(v.par_iter().zip(&v)
285	/// .all(\|(a, b)\| std::ptr::eq(a, b)));
286	/// ```
287	fn par_iter(&'data self) -> Self::Iter;
288	}
289
290	impl<'data, I: 'data + ?Sized> IntoParallelRefIterator<'data> for I
291	where
292	&'data I: IntoParallelIterator,
293	{
294	type Iter = <&'data I as IntoParallelIterator>::Iter;
295	type Item = <&'data I as IntoParallelIterator>::Item;
296
297	fn par_iter(&'data self) -> Self::Iter {
298	self.into_par_iter()
299	}
300	}
301
302	/// `IntoParallelRefMutIterator` implements the conversion to a
303	/// [`ParallelIterator`], providing mutable references to the data.
304	///
305	/// This is a parallel version of the `iter_mut()` method
306	/// defined by various collections.
307	///
308	/// This trait is automatically implemented
309	/// `for I where &mut I: IntoParallelIterator`. In most cases, users
310	/// will want to implement [`IntoParallelIterator`] rather than implement
311	/// this trait directly.
312	pub trait IntoParallelRefMutIterator<'data> {
313	/// The type of iterator that will be created.
314	type Iter: ParallelIterator<Item = Self::Item>;
315
316	/// The type of item that will be produced; this is typically an
317	/// `&'data mut T` reference.
318	type Item: Send + 'data;
319
320	/// Creates the parallel iterator from `self`.
321	///
322	/// # Examples
323	///
324	/// ```
325	/// use rayon::prelude::*;
326	///
327	/// let mut v = vec![0usize; 5];
328	/// v.par_iter_mut().enumerate().for_each(\|(i, x)\| *x = i);
329	/// assert_eq!(v, [0, 1, 2, 3, 4]);
330	/// ```
331	fn par_iter_mut(&'data mut self) -> Self::Iter;
332	}
333
334	impl<'data, I: 'data + ?Sized> IntoParallelRefMutIterator<'data> for I
335	where
336	&'data mut I: IntoParallelIterator,
337	{
338	type Iter = <&'data mut I as IntoParallelIterator>::Iter;
339	type Item = <&'data mut I as IntoParallelIterator>::Item;
340
341	fn par_iter_mut(&'data mut self) -> Self::Iter {
342	self.into_par_iter()
343	}
344	}
345
346	/// Parallel version of the standard iterator trait.
347	///
348	/// The combinators on this trait are available on all parallel
349	/// iterators. Additional methods can be found on the
350	/// [`IndexedParallelIterator`] trait: those methods are only
351	/// available for parallel iterators where the number of items is
352	/// known in advance (so, e.g., after invoking `filter`, those methods
353	/// become unavailable).
354	///
355	/// For examples of using parallel iterators, see [the docs on the
356	/// `iter` module][iter].
357	///
358	/// [iter]: self
359	pub trait ParallelIterator: Sized + Send {
360	/// The type of item that this parallel iterator produces.
361	/// For example, if you use the [`for_each`] method, this is the type of
362	/// item that your closure will be invoked with.
363	///
364	/// [`for_each`]: #method.for_each
365	type Item: Send;
366
367	/// Executes `OP` on each item produced by the iterator, in parallel.
368	///
369	/// # Examples
370	///
371	/// ```
372	/// use rayon::prelude::*;
373	///
374	/// (0..100).into_par_iter().for_each(\|x\| println!("{:?}", x));
375	/// ```
376	fn for_each<OP>(self, op: OP)
377	where
378	OP: Fn(Self::Item) + Sync + Send,
379	{
380	for_each::for_each(self, &op)
381	}
382
383	/// Executes `OP` on the given `init` value with each item produced by
384	/// the iterator, in parallel.
385	///
386	/// The `init` value will be cloned only as needed to be paired with
387	/// the group of items in each rayon job. It does not require the type
388	/// to be `Sync`.
389	///
390	/// # Examples
391	///
392	/// ```
393	/// use std::sync::mpsc::channel;
394	/// use rayon::prelude::*;
395	///
396	/// let (sender, receiver) = channel();
397	///
398	/// (0..5).into_par_iter().for_each_with(sender, \|s, x\| s.send(x).unwrap());
399	///
400	/// let mut res: Vec<_> = receiver.iter().collect();
401	///
402	/// res.sort();
403	///
404	/// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
405	/// ```
406	fn for_each_with<OP, T>(self, init: T, op: OP)
407	where
408	OP: Fn(&mut T, Self::Item) + Sync + Send,
409	T: Send + Clone,
410	{
411	self.map_with(init, op).collect()
412	}
413
414	/// Executes `OP` on a value returned by `init` with each item produced by
415	/// the iterator, in parallel.
416	///
417	/// The `init` function will be called only as needed for a value to be
418	/// paired with the group of items in each rayon job. There is no
419	/// constraint on that returned type at all!
420	///
421	/// # Examples
422	///
423	/// ```
424	/// use rand::RngExt;
425	/// use rayon::prelude::*;
426	///
427	/// let mut v = vec![0u8; 1_000_000];
428	///
429	/// v.par_chunks_mut(1000)
430	/// .for_each_init(
431	/// \|\| rand::rng(),
432	/// \|rng, chunk\| rng.fill(chunk),
433	/// );
434	///
435	/// // There's a remote chance that this will fail...
436	/// for i in 0u8..=255 {
437	/// assert!(v.contains(&i));
438	/// }
439	/// ```
440	fn for_each_init<OP, INIT, T>(self, init: INIT, op: OP)
441	where
442	OP: Fn(&mut T, Self::Item) + Sync + Send,
443	INIT: Fn() -> T + Sync + Send,
444	{
445	self.map_init(init, op).collect()
446	}
447
448	/// Executes a fallible `OP` on each item produced by the iterator, in parallel.
449	///
450	/// If the `OP` returns `Result::Err` or `Option::None`, we will attempt to
451	/// stop processing the rest of the items in the iterator as soon as
452	/// possible, and we will return that terminating value. Otherwise, we will
453	/// return an empty `Result::Ok(())` or `Option::Some(())`. If there are
454	/// multiple errors in parallel, it is not specified which will be returned.
455	///
456	/// # Examples
457	///
458	/// ```
459	/// use rayon::prelude::*;
460	/// use std::io::{self, Write};
461	///
462	/// // This will stop iteration early if there's any write error, like
463	/// // having piped output get closed on the other end.
464	/// (0..100).into_par_iter()
465	/// .try_for_each(\|x\| writeln!(io::stdout(), "{:?}", x))
466	/// .expect("expected no write errors");
467	/// ```
468	#[expect(private_bounds)]
469	fn try_for_each<OP, R>(self, op: OP) -> R
470	where
471	OP: Fn(Self::Item) -> R + Sync + Send,
472	R: Try<Output = ()> + Send,
473	{
474	fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
475	R::from_output(())
476	}
477
478	self.map(op).try_reduce(<()>::default, ok)
479	}
480
481	/// Executes a fallible `OP` on the given `init` value with each item
482	/// produced by the iterator, in parallel.
483	///
484	/// This combines the `init` semantics of [`for_each_with()`] and the
485	/// failure semantics of [`try_for_each()`].
486	///
487	/// [`for_each_with()`]: #method.for_each_with
488	/// [`try_for_each()`]: #method.try_for_each
489	///
490	/// # Examples
491	///
492	/// ```
493	/// use std::sync::mpsc::channel;
494	/// use rayon::prelude::*;
495	///
496	/// let (sender, receiver) = channel();
497	///
498	/// (0..5).into_par_iter()
499	/// .try_for_each_with(sender, \|s, x\| s.send(x))
500	/// .expect("expected no send errors");
501	///
502	/// let mut res: Vec<_> = receiver.iter().collect();
503	///
504	/// res.sort();
505	///
506	/// assert_eq!(&res[..], &[0, 1, 2, 3, 4])
507	/// ```
508	#[expect(private_bounds)]
509	fn try_for_each_with<OP, T, R>(self, init: T, op: OP) -> R
510	where
511	OP: Fn(&mut T, Self::Item) -> R + Sync + Send,
512	T: Send + Clone,
513	R: Try<Output = ()> + Send,
514	{
515	fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
516	R::from_output(())
517	}
518
519	self.map_with(init, op).try_reduce(<()>::default, ok)
520	}
521
522	/// Executes a fallible `OP` on a value returned by `init` with each item
523	/// produced by the iterator, in parallel.
524	///
525	/// This combines the `init` semantics of [`for_each_init()`] and the
526	/// failure semantics of [`try_for_each()`].
527	///
528	/// [`for_each_init()`]: #method.for_each_init
529	/// [`try_for_each()`]: #method.try_for_each
530	///
531	/// # Examples
532	///
533	/// ```
534	/// use rand::{RngExt, TryRng};
535	/// use rayon::prelude::*;
536	///
537	/// let mut v = vec![0u8; 1_000_000];
538	///
539	/// v.par_chunks_mut(1000)
540	/// .try_for_each_init(
541	/// \|\| rand::rng(),
542	/// \|rng, chunk\| rng.try_fill_bytes(chunk),
543	/// )
544	/// .expect("expected no rand errors");
545	///
546	/// // There's a remote chance that this will fail...
547	/// for i in 0u8..=255 {
548	/// assert!(v.contains(&i));
549	/// }
550	/// ```
551	#[expect(private_bounds)]
552	fn try_for_each_init<OP, INIT, T, R>(self, init: INIT, op: OP) -> R
553	where
554	OP: Fn(&mut T, Self::Item) -> R + Sync + Send,
555	INIT: Fn() -> T + Sync + Send,
556	R: Try<Output = ()> + Send,
557	{
558	fn ok<R: Try<Output = ()>>(_: (), _: ()) -> R {
559	R::from_output(())
560	}
561
562	self.map_init(init, op).try_reduce(<()>::default, ok)
563	}
564
565	/// Counts the number of items in this parallel iterator.
566	///
567	/// # Examples
568	///
569	/// ```
570	/// use rayon::prelude::*;
571	///
572	/// let count = (0..100).into_par_iter().count();
573	///
574	/// assert_eq!(count, 100);
575	/// ```
576	fn count(self) -> usize {
577	fn one<T>(_: T) -> usize {
578	1
579	}
580
581	self.map(one).sum()
582	}
583
584	/// Applies `map_op` to each item of this iterator, producing a new
585	/// iterator with the results.
586	///
587	/// # Examples
588	///
589	/// ```
590	/// use rayon::prelude::*;
591	///
592	/// let mut par_iter = (0..5).into_par_iter().map(\|x\| x * 2);
593	///
594	/// let doubles: Vec<_> = par_iter.collect();
595	///
596	/// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
597	/// ```
598	fn map<F, R>(self, map_op: F) -> Map<Self, F>
599	where
600	F: Fn(Self::Item) -> R + Sync + Send,
601	R: Send,
602	{
603	Map::new(self, map_op)
604	}
605
606	/// Applies `map_op` to the given `init` value with each item of this
607	/// iterator, producing a new iterator with the results.
608	///
609	/// The `init` value will be cloned only as needed to be paired with
610	/// the group of items in each rayon job. It does not require the type
611	/// to be `Sync`.
612	///
613	/// # Examples
614	///
615	/// ```
616	/// use std::sync::mpsc::channel;
617	/// use rayon::prelude::*;
618	///
619	/// let (sender, receiver) = channel();
620	///
621	/// let a: Vec<_> = (0..5)
622	/// .into_par_iter() // iterating over i32
623	/// .map_with(sender, \|s, x\| {
624	/// s.send(x).unwrap(); // sending i32 values through the channel
625	/// x // returning i32
626	/// })
627	/// .collect(); // collecting the returned values into a vector
628	///
629	/// let mut b: Vec<_> = receiver.iter() // iterating over the values in the channel
630	/// .collect(); // and collecting them
631	/// b.sort();
632	///
633	/// assert_eq!(a, b);
634	/// ```
635	fn map_with<F, T, R>(self, init: T, map_op: F) -> MapWith<Self, T, F>
636	where
637	F: Fn(&mut T, Self::Item) -> R + Sync + Send,
638	T: Send + Clone,
639	R: Send,
640	{
641	MapWith::new(self, init, map_op)
642	}
643
644	/// Applies `map_op` to a value returned by `init` with each item of this
645	/// iterator, producing a new iterator with the results.
646	///
647	/// The `init` function will be called only as needed for a value to be
648	/// paired with the group of items in each rayon job. There is no
649	/// constraint on that returned type at all!
650	///
651	/// # Examples
652	///
653	/// ```
654	/// use rand::RngExt;
655	/// use rayon::prelude::*;
656	///
657	/// let a: Vec<_> = (1i32..1_000_000)
658	/// .into_par_iter()
659	/// .map_init(
660	/// \|\| rand::rng(), // get the thread-local RNG
661	/// \|rng, x\| if rng.random() { // randomly negate items
662	/// -x
663	/// } else {
664	/// x
665	/// },
666	/// ).collect();
667	///
668	/// // There's a remote chance that this will fail...
669	/// assert!(a.iter().any(\|&x\| x < 0));
670	/// assert!(a.iter().any(\|&x\| x > 0));
671	/// ```
672	fn map_init<F, INIT, T, R>(self, init: INIT, map_op: F) -> MapInit<Self, INIT, F>
673	where
674	F: Fn(&mut T, Self::Item) -> R + Sync + Send,
675	INIT: Fn() -> T + Sync + Send,
676	R: Send,
677	{
678	MapInit::new(self, init, map_op)
679	}
680
681	/// Creates an iterator which clones all of its elements. This may be
682	/// useful when you have an iterator over `&T`, but you need `T`, and
683	/// that type implements `Clone`. See also [`copied()`].
684	///
685	/// [`copied()`]: #method.copied
686	///
687	/// # Examples
688	///
689	/// ```
690	/// use rayon::prelude::*;
691	///
692	/// let a = [1, 2, 3];
693	///
694	/// let v_cloned: Vec<_> = a.par_iter().cloned().collect();
695	///
696	/// // cloned is the same as .map(\|&x\| x), for integers
697	/// let v_map: Vec<_> = a.par_iter().map(\|&x\| x).collect();
698	///
699	/// assert_eq!(v_cloned, vec![1, 2, 3]);
700	/// assert_eq!(v_map, vec![1, 2, 3]);
701	/// ```
702	fn cloned<'a, T>(self) -> Cloned<Self>
703	where
704	T: 'a + Clone + Send,
705	Self: ParallelIterator<Item = &'a T>,
706	{
707	Cloned::new(self)
708	}
709
710	/// Creates an iterator which copies all of its elements. This may be
711	/// useful when you have an iterator over `&T`, but you need `T`, and
712	/// that type implements `Copy`. See also [`cloned()`].
713	///
714	/// [`cloned()`]: #method.cloned
715	///
716	/// # Examples
717	///
718	/// ```
719	/// use rayon::prelude::*;
720	///
721	/// let a = [1, 2, 3];
722	///
723	/// let v_copied: Vec<_> = a.par_iter().copied().collect();
724	///
725	/// // copied is the same as .map(\|&x\| x), for integers
726	/// let v_map: Vec<_> = a.par_iter().map(\|&x\| x).collect();
727	///
728	/// assert_eq!(v_copied, vec![1, 2, 3]);
729	/// assert_eq!(v_map, vec![1, 2, 3]);
730	/// ```
731	fn copied<'a, T>(self) -> Copied<Self>
732	where
733	T: 'a + Copy + Send,
734	Self: ParallelIterator<Item = &'a T>,
735	{
736	Copied::new(self)
737	}
738
739	/// Applies `inspect_op` to a reference to each item of this iterator,
740	/// producing a new iterator passing through the original items. This is
741	/// often useful for debugging to see what's happening in iterator stages.
742	///
743	/// # Examples
744	///
745	/// ```
746	/// use rayon::prelude::*;
747	///
748	/// let a = [1, 4, 2, 3];
749	///
750	/// // this iterator sequence is complex.
751	/// let sum = a.par_iter()
752	/// .cloned()
753	/// .filter(\|&x\| x % 2 == 0)
754	/// .reduce(\|\| 0, \|sum, i\| sum + i);
755	///
756	/// println!("{}", sum);
757	///
758	/// // let's add some inspect() calls to investigate what's happening
759	/// let sum = a.par_iter()
760	/// .cloned()
761	/// .inspect(\|x\| println!("about to filter: {}", x))
762	/// .filter(\|&x\| x % 2 == 0)
763	/// .inspect(\|x\| println!("made it through filter: {}", x))
764	/// .reduce(\|\| 0, \|sum, i\| sum + i);
765	///
766	/// println!("{}", sum);
767	/// ```
768	fn inspect<OP>(self, inspect_op: OP) -> Inspect<Self, OP>
769	where
770	OP: Fn(&Self::Item) + Sync + Send,
771	{
772	Inspect::new(self, inspect_op)
773	}
774
775	/// Mutates each item of this iterator before yielding it.
776	///
777	/// # Examples
778	///
779	/// ```
780	/// use rayon::prelude::*;
781	///
782	/// let par_iter = (0..5).into_par_iter().update(\|x\| {x = 2;});
783	///
784	/// let doubles: Vec<_> = par_iter.collect();
785	///
786	/// assert_eq!(&doubles[..], &[0, 2, 4, 6, 8]);
787	/// ```
788	fn update<F>(self, update_op: F) -> Update<Self, F>
789	where
790	F: Fn(&mut Self::Item) + Sync + Send,
791	{
792	Update::new(self, update_op)
793	}
794
795	/// Applies `filter_op` to each item of this iterator, producing a new
796	/// iterator with only the items that gave `true` results.
797	///
798	/// # Examples
799	///
800	/// ```
801	/// use rayon::prelude::*;
802	///
803	/// let mut par_iter = (0..10).into_par_iter().filter(\|x\| x % 2 == 0);
804	///
805	/// let even_numbers: Vec<_> = par_iter.collect();
806	///
807	/// assert_eq!(&even_numbers[..], &[0, 2, 4, 6, 8]);
808	/// ```
809	fn filter<P>(self, filter_op: P) -> Filter<Self, P>
810	where
811	P: Fn(&Self::Item) -> bool + Sync + Send,
812	{
813	Filter::new(self, filter_op)
814	}
815
816	/// Applies `filter_op` to each item of this iterator to get an `Option`,
817	/// producing a new iterator with only the items from `Some` results.
818	///
819	/// # Examples
820	///
821	/// ```
822	/// use rayon::prelude::*;
823	///
824	/// let mut par_iter = (0..10).into_par_iter()
825	/// .filter_map(\|x\| {
826	/// if x % 2 == 0 { Some(x * 3) }
827	/// else { None }
828	/// });
829	///
830	/// let even_numbers: Vec<_> = par_iter.collect();
831	///
832	/// assert_eq!(&even_numbers[..], &[0, 6, 12, 18, 24]);
833	/// ```
834	fn filter_map<P, R>(self, filter_op: P) -> FilterMap<Self, P>
835	where
836	P: Fn(Self::Item) -> Option<R> + Sync + Send,
837	R: Send,
838	{
839	FilterMap::new(self, filter_op)
840	}
841
842	/// Applies `map_op` to each item of this iterator to get nested parallel iterators,
843	/// producing a new parallel iterator that flattens these back into one.
844	///
845	/// See also [`flat_map_iter`](#method.flat_map_iter).
846	///
847	/// # Examples
848	///
849	/// ```
850	/// use rayon::prelude::*;
851	///
852	/// let a = [[1, 2], [3, 4], [5, 6], [7, 8]];
853	///
854	/// let par_iter = a.par_iter().cloned().flat_map(\|a\| a.to_vec());
855	///
856	/// let vec: Vec<_> = par_iter.collect();
857	///
858	/// assert_eq!(&vec[..], &[1, 2, 3, 4, 5, 6, 7, 8]);
859	/// ```
860	fn flat_map<F, PI>(self, map_op: F) -> FlatMap<Self, F>
861	where
862	F: Fn(Self::Item) -> PI + Sync + Send,
863	PI: IntoParallelIterator,
864	{
865	FlatMap::new(self, map_op)
866	}
867
868	/// Applies `map_op` to each item of this iterator to get nested serial iterators,
869	/// producing a new parallel iterator that flattens these back into one.
870	///
871	/// # `flat_map_iter` versus `flat_map`
872	///
873	/// These two methods are similar but behave slightly differently. With [`flat_map`],
874	/// each of the nested iterators must be a parallel iterator, and they will be further
875	/// split up with nested parallelism. With `flat_map_iter`, each nested iterator is a
876	/// sequential `Iterator`, and we only parallelize _between_ them, while the items
877	/// produced by each nested iterator are processed sequentially.
878	///
879	/// When choosing between these methods, consider whether nested parallelism suits the
880	/// potential iterators at hand. If there's little computation involved, or its length
881	/// is much less than the outer parallel iterator, then it may perform better to avoid
882	/// the overhead of parallelism, just flattening sequentially with `flat_map_iter`.
883	/// If there is a lot of computation, potentially outweighing the outer parallel
884	/// iterator, then the nested parallelism of `flat_map` may be worthwhile.
885	///
886	/// [`flat_map`]: #method.flat_map
887	///
888	/// # Examples
889	///
890	/// ```
891	/// use rayon::prelude::*;
892	/// use std::cell::RefCell;
893	///
894	/// let a = [[1, 2], [3, 4], [5, 6], [7, 8]];
895	///
896	/// let par_iter = a.par_iter().flat_map_iter(\|a\| {
897	/// // The serial iterator doesn't have to be thread-safe, just its items.
898	/// let cell_iter = RefCell::new(a.iter().cloned());
899	/// std::iter::from_fn(move \|\| cell_iter.borrow_mut().next())
900	/// });
901	///
902	/// let vec: Vec<_> = par_iter.collect();
903	///
904	/// assert_eq!(&vec[..], &[1, 2, 3, 4, 5, 6, 7, 8]);
905	/// ```
906	fn flat_map_iter<F, SI>(self, map_op: F) -> FlatMapIter<Self, F>
907	where
908	F: Fn(Self::Item) -> SI + Sync + Send,
909	SI: IntoIterator<Item: Send>,
910	{
911	FlatMapIter::new(self, map_op)
912	}
913
914	/// An adaptor that flattens parallel-iterable `Item`s into one large iterator.
915	///
916	/// See also [`flatten_iter`](#method.flatten_iter).
917	///
918	/// # Examples
919	///
920	/// ```
921	/// use rayon::prelude::*;
922	///
923	/// let x: Vec<Vec<_>> = vec![vec![1, 2], vec![3, 4]];
924	/// let y: Vec<_> = x.into_par_iter().flatten().collect();
925	///
926	/// assert_eq!(y, vec![1, 2, 3, 4]);
927	/// ```
928	fn flatten(self) -> Flatten<Self>
929	where
930	Self::Item: IntoParallelIterator,
931	{
932	Flatten::new(self)
933	}
934
935	/// An adaptor that flattens serial-iterable `Item`s into one large iterator.
936	///
937	/// See also [`flatten`](#method.flatten) and the analogous comparison of
938	/// [`flat_map_iter` versus `flat_map`](#flat_map_iter-versus-flat_map).
939	///
940	/// # Examples
941	///
942	/// ```
943	/// use rayon::prelude::*;
944	///
945	/// let x: Vec<Vec<_>> = vec![vec![1, 2], vec![3, 4]];
946	/// let iters: Vec<_> = x.into_iter().map(Vec::into_iter).collect();
947	/// let y: Vec<_> = iters.into_par_iter().flatten_iter().collect();
948	///
949	/// assert_eq!(y, vec![1, 2, 3, 4]);
950	/// ```
951	fn flatten_iter(self) -> FlattenIter<Self>
952	where
953	Self::Item: IntoIterator<Item: Send>,
954	{
955	FlattenIter::new(self)
956	}
957
958	/// Reduces the items in the iterator into one item using `op`.
959	/// The argument `identity` should be a closure that can produce
960	/// "identity" value which may be inserted into the sequence as
961	/// needed to create opportunities for parallel execution. So, for
962	/// example, if you are doing a summation, then `identity()` ought
963	/// to produce something that represents the zero for your type
964	/// (but consider just calling `sum()` in that case).
965	///
966	/// # Examples
967	///
968	/// ```
969	/// // Iterate over a sequence of pairs `(x0, y0), ..., (xN, yN)`
970	/// // and use reduce to compute one pair `(x0 + ... + xN, y0 + ... + yN)`
971	/// // where the first/second elements are summed separately.
972	/// use rayon::prelude::*;
973	/// let sums = [(0, 1), (5, 6), (16, 2), (8, 9)]
974	/// .par_iter() // iterating over &(i32, i32)
975	/// .cloned() // iterating over (i32, i32)
976	/// .reduce(\|\| (0, 0), // the "identity" is 0 in both columns
977	/// \|a, b\| (a.0 + b.0, a.1 + b.1));
978	/// assert_eq!(sums, (0 + 5 + 16 + 8, 1 + 6 + 2 + 9));
979	/// ```
980	///
981	/// Note: unlike a sequential `fold` operation, the order in
982	/// which `op` will be applied to reduce the result is not fully
983	/// specified. So `op` should be [associative] or else the results
984	/// will be non-deterministic. And of course `identity()` should
985	/// produce a true identity.
986	///
987	/// [associative]: https://en.wikipedia.org/wiki/Associative_property
988	fn reduce<OP, ID>(self, identity: ID, op: OP) -> Self::Item
989	where
990	OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send,
991	ID: Fn() -> Self::Item + Sync + Send,
992	{
993	reduce::reduce(self, identity, op)
994	}
995
996	/// Reduces the items in the iterator into one item using `op`.
997	/// If the iterator is empty, `None` is returned; otherwise,
998	/// `Some` is returned.
999	///
1000	/// This version of `reduce` is simple but somewhat less
1001	/// efficient. If possible, it is better to call `reduce()`, which
1002	/// requires an identity element.
1003	///
1004	/// # Examples
1005	///
1006	/// ```
1007	/// use rayon::prelude::*;
1008	/// let sums = [(0, 1), (5, 6), (16, 2), (8, 9)]
1009	/// .par_iter() // iterating over &(i32, i32)
1010	/// .cloned() // iterating over (i32, i32)
1011	/// .reduce_with(\|a, b\| (a.0 + b.0, a.1 + b.1))
1012	/// .unwrap();
1013	/// assert_eq!(sums, (0 + 5 + 16 + 8, 1 + 6 + 2 + 9));
1014	/// ```
1015	///
1016	/// Note: unlike a sequential `fold` operation, the order in
1017	/// which `op` will be applied to reduce the result is not fully
1018	/// specified. So `op` should be [associative] or else the results
1019	/// will be non-deterministic.
1020	///
1021	/// [associative]: https://en.wikipedia.org/wiki/Associative_property
1022	fn reduce_with<OP>(self, op: OP) -> Option<Self::Item>
1023	where
1024	OP: Fn(Self::Item, Self::Item) -> Self::Item + Sync + Send,
1025	{
1026	fn opt_fold<T>(op: impl Fn(T, T) -> T) -> impl Fn(Option<T>, T) -> Option<T> {
1027	move \|opt_a, b\| match opt_a {
1028	Some(a) => Some(op(a, b)),
1029	None => Some(b),
1030	}
1031	}
1032
1033	fn opt_reduce<T>(op: impl Fn(T, T) -> T) -> impl Fn(Option<T>, Option<T>) -> Option<T> {
1034	move \|opt_a, opt_b\| match (opt_a, opt_b) {
1035	(Some(a), Some(b)) => Some(op(a, b)),
1036	(Some(v), None) \| (None, Some(v)) => Some(v),
1037	(None, None) => None,
1038	}
1039	}
1040
1041	self.fold(<_>::default, opt_fold(&op))
1042	.reduce(<_>::default, opt_reduce(&op))
1043	}
1044
1045	/// Reduces the items in the iterator into one item using a fallible `op`.
1046	/// The `identity` argument is used the same way as in [`reduce()`].
1047	///
1048	/// [`reduce()`]: #method.reduce
1049	///
1050	/// If a `Result::Err` or `Option::None` item is found, or if `op` reduces
1051	/// to one, we will attempt to stop processing the rest of the items in the
1052	/// iterator as soon as possible, and we will return that terminating value.
1053	/// Otherwise, we will return the final reduced `Result::Ok(T)` or
1054	/// `Option::Some(T)`. If there are multiple errors in parallel, it is not
1055	/// specified which will be returned.
1056	///
1057	/// # Examples
1058	///
1059	/// ```
1060	/// use rayon::prelude::*;
1061	///
1062	/// // Compute the sum of squares, being careful about overflow.
1063	/// fn sum_squares<I: IntoParallelIterator<Item = i32>>(iter: I) -> Option<i32> {
1064	/// iter.into_par_iter()
1065	/// .map(\|i\| i.checked_mul(i)) // square each item,
1066	/// .try_reduce(\|\| 0, i32::checked_add) // and add them up!
1067	/// }
1068	/// assert_eq!(sum_squares(0..5), Some(0 + 1 + 4 + 9 + 16));
1069	///
1070	/// // The sum might overflow
1071	/// assert_eq!(sum_squares(0..10_000), None);
1072	///
1073	/// // Or the squares might overflow before it even reaches `try_reduce`
1074	/// assert_eq!(sum_squares(1_000_000..1_000_001), None);
1075	/// ```
1076	#[expect(private_bounds)]
1077	fn try_reduce<T, OP, ID>(self, identity: ID, op: OP) -> Self::Item
1078	where
1079	OP: Fn(T, T) -> Self::Item + Sync + Send,
1080	ID: Fn() -> T + Sync + Send,
1081	Self::Item: Try<Output = T>,
1082	{
1083	try_reduce::try_reduce(self, identity, op)
1084	}
1085
1086	/// Reduces the items in the iterator into one item using a fallible `op`.
1087	///
1088	/// Like [`reduce_with()`], if the iterator is empty, `None` is returned;
1089	/// otherwise, `Some` is returned. Beyond that, it behaves like
1090	/// [`try_reduce()`] for handling `Err`/`None`.
1091	///
1092	/// [`reduce_with()`]: #method.reduce_with
1093	/// [`try_reduce()`]: #method.try_reduce
1094	///
1095	/// For instance, with `Option` items, the return value may be:
1096	/// - `None`, the iterator was empty
1097	/// - `Some(None)`, we stopped after encountering `None`.
1098	/// - `Some(Some(x))`, the entire iterator reduced to `x`.
1099	///
1100	/// With `Result` items, the nesting is more obvious:
1101	/// - `None`, the iterator was empty
1102	/// - `Some(Err(e))`, we stopped after encountering an error `e`.
1103	/// - `Some(Ok(x))`, the entire iterator reduced to `x`.
1104	///
1105	/// # Examples
1106	///
1107	/// ```
1108	/// use rayon::prelude::*;
1109	///
1110	/// let files = ["/dev/null", "/does/not/exist"];
1111	///
1112	/// // Find the biggest file
1113	/// files.into_par_iter()
1114	/// .map(\|path\| std::fs::metadata(path).map(\|m\| (path, m.len())))
1115	/// .try_reduce_with(\|a, b\| {
1116	/// Ok(if a.1 >= b.1 { a } else { b })
1117	/// })
1118	/// .expect("Some value, since the iterator is not empty")
1119	/// .expect_err("not found");
1120	/// ```
1121	#[expect(private_bounds)]
1122	fn try_reduce_with<T, OP>(self, op: OP) -> Option<Self::Item>
1123	where
1124	OP: Fn(T, T) -> Self::Item + Sync + Send,
1125	Self::Item: Try<Output = T>,
1126	{
1127	try_reduce_with::try_reduce_with(self, op)
1128	}
1129
1130	/// Parallel fold is similar to sequential fold except that the
1131	/// sequence of items may be subdivided before it is
1132	/// folded. Consider a list of numbers like `22 3 77 89 46`. If
1133	/// you used sequential fold to add them (`fold(0, \|a,b\| a+b)`,
1134	/// you would wind up first adding 0 + 22, then 22 + 3, then 25 +
1135	/// 77, and so forth. The parallel fold works similarly except
1136	/// that it first breaks up your list into sublists, and hence
1137	/// instead of yielding up a single sum at the end, it yields up
1138	/// multiple sums. The number of results is nondeterministic, as
1139	/// is the point where the breaks occur.
1140	///
1141	/// So if we did the same parallel fold (`fold(0, \|a,b\| a+b)`) on
1142	/// our example list, we might wind up with a sequence of two numbers,
1143	/// like so:
1144	///
1145	/// ```notrust
1146	/// 22 3 77 89 46
1147	/// \| \|
1148	/// 102 135
1149	/// ```
1150	///
1151	/// Or perhaps these three numbers:
1152	///
1153	/// ```notrust
1154	/// 22 3 77 89 46
1155	/// \| \| \|
1156	/// 102 89 46
1157	/// ```
1158	///
1159	/// In general, Rayon will attempt to find good breaking points
1160	/// that keep all of your cores busy.
1161	///
1162	/// ### Fold versus reduce
1163	///
1164	/// The `fold()` and `reduce()` methods each take an identity element
1165	/// and a combining function, but they operate rather differently.
1166	///
1167	/// `reduce()` requires that the identity function has the same
1168	/// type as the things you are iterating over, and it fully
1169	/// reduces the list of items into a single item. So, for example,
1170	/// imagine we are iterating over a list of bytes `bytes: [128_u8,
1171	/// 64_u8, 64_u8]`. If we used `bytes.reduce(\|\| 0_u8, \|a: u8, b:
1172	/// u8\| a + b)`, we would get an overflow. This is because `0`,
1173	/// `a`, and `b` here are all bytes, just like the numbers in the
1174	/// list (I wrote the types explicitly above, but those are the
1175	/// only types you can use). To avoid the overflow, we would need
1176	/// to do something like `bytes.map(\|b\| b as u32).reduce(\|\| 0, \|a,
1177	/// b\| a + b)`, in which case our result would be `256`.
1178	///
1179	/// In contrast, with `fold()`, the identity function does not
1180	/// have to have the same type as the things you are iterating
1181	/// over, and you potentially get back many results. So, if we
1182	/// continue with the `bytes` example from the previous paragraph,
1183	/// we could do `bytes.fold(\|\| 0_u32, \|a, b\| a + (b as u32))` to
1184	/// convert our bytes into `u32`. And of course we might not get
1185	/// back a single sum.
1186	///
1187	/// There is a more subtle distinction as well, though it's
1188	/// actually implied by the above points. When you use `reduce()`,
1189	/// your reduction function is sometimes called with values that
1190	/// were never part of your original parallel iterator (for
1191	/// example, both the left and right might be a partial sum). With
1192	/// `fold()`, in contrast, the left value in the fold function is
1193	/// always the accumulator, and the right value is always from
1194	/// your original sequence.
1195	///
1196	/// ### Fold vs Map/Reduce
1197	///
1198	/// Fold makes sense if you have some operation where it is
1199	/// cheaper to create groups of elements at a time. For example,
1200	/// imagine collecting characters into a string. If you were going
1201	/// to use map/reduce, you might try this:
1202	///
1203	/// ```
1204	/// use rayon::prelude::*;
1205	///
1206	/// let s =
1207	/// ['a', 'b', 'c', 'd', 'e']
1208	/// .par_iter()
1209	/// .map(\|c: &char\| format!("{}", c))
1210	/// .reduce(\|\| String::new(),
1211	/// \|mut a: String, b: String\| { a.push_str(&b); a });
1212	///
1213	/// assert_eq!(s, "abcde");
1214	/// ```
1215	///
1216	/// Because reduce produces the same type of element as its input,
1217	/// you have to first map each character into a string, and then
1218	/// you can reduce them. This means we create one string per
1219	/// element in our iterator -- not so great. Using `fold`, we can
1220	/// do this instead:
1221	///
1222	/// ```
1223	/// use rayon::prelude::*;
1224	///
1225	/// let s =
1226	/// ['a', 'b', 'c', 'd', 'e']
1227	/// .par_iter()
1228	/// .fold(\|\| String::new(),
1229	/// \|mut s: String, c: &char\| { s.push(*c); s })
1230	/// .reduce(\|\| String::new(),
1231	/// \|mut a: String, b: String\| { a.push_str(&b); a });
1232	///
1233	/// assert_eq!(s, "abcde");
1234	/// ```
1235	///
1236	/// Now `fold` will process groups of our characters at a time,
1237	/// and we only make one string per group. We should wind up with
1238	/// some small-ish number of strings roughly proportional to the
1239	/// number of CPUs you have (it will ultimately depend on how busy
1240	/// your processors are). Note that we still need to do a reduce
1241	/// afterwards to combine those groups of strings into a single
1242	/// string.
1243	///
1244	/// You could use a similar trick to save partial results (e.g., a
1245	/// cache) or something similar.
1246	///
1247	/// ### Combining fold with other operations
1248	///
1249	/// You can combine `fold` with `reduce` if you want to produce a
1250	/// single value. This is then roughly equivalent to a map/reduce
1251	/// combination in effect:
1252	///
1253	/// ```
1254	/// use rayon::prelude::*;
1255	///
1256	/// let bytes = 0..22_u8;
1257	/// let sum = bytes.into_par_iter()
1258	/// .fold(\|\| 0_u32, \|a: u32, b: u8\| a + (b as u32))
1259	/// .sum::<u32>();
1260	///
1261	/// assert_eq!(sum, (0..22).sum()); // compare to sequential
1262	/// ```
1263	fn fold<T, ID, F>(self, identity: ID, fold_op: F) -> Fold<Self, ID, F>
1264	where
1265	F: Fn(T, Self::Item) -> T + Sync + Send,
1266	ID: Fn() -> T + Sync + Send,
1267	T: Send,
1268	{
1269	Fold::new(self, identity, fold_op)
1270	}
1271
1272	/// Applies `fold_op` to the given `init` value with each item of this
1273	/// iterator, finally producing the value for further use.
1274	///
1275	/// This works essentially like `fold(\|\| init.clone(), fold_op)`, except
1276	/// it doesn't require the `init` type to be `Sync`, nor any other form
1277	/// of added synchronization.
1278	///
1279	/// # Examples
1280	///
1281	/// ```
1282	/// use rayon::prelude::*;
1283	///
1284	/// let bytes = 0..22_u8;
1285	/// let sum = bytes.into_par_iter()
1286	/// .fold_with(0_u32, \|a: u32, b: u8\| a + (b as u32))
1287	/// .sum::<u32>();
1288	///
1289	/// assert_eq!(sum, (0..22).sum()); // compare to sequential
1290	/// ```
1291	fn fold_with<F, T>(self, init: T, fold_op: F) -> FoldWith<Self, T, F>
1292	where
1293	F: Fn(T, Self::Item) -> T + Sync + Send,
1294	T: Send + Clone,
1295	{
1296	FoldWith::new(self, init, fold_op)
1297	}
1298
1299	/// Performs a fallible parallel fold.
1300	///
1301	/// This is a variation of [`fold()`] for operations which can fail with
1302	/// `Option::None` or `Result::Err`. The first such failure stops
1303	/// processing the local set of items, without affecting other folds in the
1304	/// iterator's subdivisions.
1305	///
1306	/// Often, `try_fold()` will be followed by [`try_reduce()`]
1307	/// for a final reduction and global short-circuiting effect.
1308	///
1309	/// [`fold()`]: #method.fold
1310	/// [`try_reduce()`]: #method.try_reduce
1311	///
1312	/// # Examples
1313	///
1314	/// ```
1315	/// use rayon::prelude::*;
1316	///
1317	/// let bytes = 0..22_u8;
1318	/// let sum = bytes.into_par_iter()
1319	/// .try_fold(\|\| 0_u32, \|a: u32, b: u8\| a.checked_add(b as u32))
1320	/// .try_reduce(\|\| 0, u32::checked_add);
1321	///
1322	/// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
1323	/// ```
1324	#[expect(private_bounds)]
1325	fn try_fold<T, R, ID, F>(self, identity: ID, fold_op: F) -> TryFold<Self, R, ID, F>
1326	where
1327	F: Fn(T, Self::Item) -> R + Sync + Send,
1328	ID: Fn() -> T + Sync + Send,
1329	R: Try<Output = T> + Send,
1330	{
1331	TryFold::new(self, identity, fold_op)
1332	}
1333
1334	/// Performs a fallible parallel fold with a cloneable `init` value.
1335	///
1336	/// This combines the `init` semantics of [`fold_with()`] and the failure
1337	/// semantics of [`try_fold()`].
1338	///
1339	/// [`fold_with()`]: #method.fold_with
1340	/// [`try_fold()`]: #method.try_fold
1341	///
1342	/// ```
1343	/// use rayon::prelude::*;
1344	///
1345	/// let bytes = 0..22_u8;
1346	/// let sum = bytes.into_par_iter()
1347	/// .try_fold_with(0_u32, \|a: u32, b: u8\| a.checked_add(b as u32))
1348	/// .try_reduce(\|\| 0, u32::checked_add);
1349	///
1350	/// assert_eq!(sum, Some((0..22).sum())); // compare to sequential
1351	/// ```
1352	#[expect(private_bounds)]
1353	fn try_fold_with<F, T, R>(self, init: T, fold_op: F) -> TryFoldWith<Self, R, F>
1354	where
1355	F: Fn(T, Self::Item) -> R + Sync + Send,
1356	R: Try<Output = T> + Send,
1357	T: Clone + Send,
1358	{
1359	TryFoldWith::new(self, init, fold_op)
1360	}
1361
1362	/// Sums up the items in the iterator.
1363	///
1364	/// Note that the order in items will be reduced is not specified,
1365	/// so if the `+` operator is not truly [associative] \(as is the
1366	/// case for floating point numbers), then the results are not
1367	/// fully deterministic.
1368	///
1369	/// [associative]: https://en.wikipedia.org/wiki/Associative_property
1370	///
1371	/// Basically equivalent to `self.reduce(\|\| 0, \|a, b\| a + b)`,
1372	/// except that the type of `0` and the `+` operation may vary
1373	/// depending on the type of value being produced.
1374	///
1375	/// # Examples
1376	///
1377	/// ```
1378	/// use rayon::prelude::*;
1379	///
1380	/// let a = [1, 5, 7];
1381	///
1382	/// let sum: i32 = a.par_iter().sum();
1383	///
1384	/// assert_eq!(sum, 13);
1385	/// ```
1386	fn sum<S>(self) -> S
1387	where
1388	S: Send + Sum<Self::Item> + Sum<S>,
1389	{
1390	sum::sum(self)
1391	}
1392
1393	/// Multiplies all the items in the iterator.
1394	///
1395	/// Note that the order in items will be reduced is not specified,
1396	/// so if the `*` operator is not truly [associative] \(as is the
1397	/// case for floating point numbers), then the results are not
1398	/// fully deterministic.
1399	///
1400	/// [associative]: https://en.wikipedia.org/wiki/Associative_property
1401	///
1402	/// Basically equivalent to `self.reduce(\|\| 1, \|a, b\| a * b)`,
1403	/// except that the type of `1` and the `*` operation may vary
1404	/// depending on the type of value being produced.
1405	///
1406	/// # Examples
1407	///
1408	/// ```
1409	/// use rayon::prelude::*;
1410	///
1411	/// fn factorial(n: u32) -> u32 {
1412	/// (1..n+1).into_par_iter().product()
1413	/// }
1414	///
1415	/// assert_eq!(factorial(0), 1);
1416	/// assert_eq!(factorial(1), 1);
1417	/// assert_eq!(factorial(5), 120);
1418	/// ```
1419	fn product<P>(self) -> P
1420	where
1421	P: Send + Product<Self::Item> + Product<P>,
1422	{
1423	product::product(self)
1424	}
1425
1426	/// Computes the minimum of all the items in the iterator. If the
1427	/// iterator is empty, `None` is returned; otherwise, `Some(min)`
1428	/// is returned.
1429	///
1430	/// Note that the order in which the items will be reduced is not
1431	/// specified, so if the `Ord` impl is not truly associative, then
1432	/// the results are not deterministic.
1433	///
1434	/// Basically equivalent to `self.reduce_with(\|a, b\| Ord::min(a, b))`.
1435	///
1436	/// # Examples
1437	///
1438	/// ```
1439	/// use rayon::prelude::*;
1440	///
1441	/// let a = [45, 74, 32];
1442	///
1443	/// assert_eq!(a.par_iter().min(), Some(&32));
1444	///
1445	/// let b: [i32; 0] = [];
1446	///
1447	/// assert_eq!(b.par_iter().min(), None);
1448	/// ```
1449	fn min(self) -> Option<Self::Item>
1450	where
1451	Self::Item: Ord,
1452	{
1453	self.reduce_with(Ord::min)
1454	}
1455
1456	/// Computes the minimum of all the items in the iterator with respect to
1457	/// the given comparison function. If the iterator is empty, `None` is
1458	/// returned; otherwise, `Some(min)` is returned.
1459	///
1460	/// Note that the order in which the items will be reduced is not
1461	/// specified, so if the comparison function is not associative, then
1462	/// the results are not deterministic.
1463	///
1464	/// # Examples
1465	///
1466	/// ```
1467	/// use rayon::prelude::*;
1468	///
1469	/// let a = [-3_i32, 77, 53, 240, -1];
1470	///
1471	/// assert_eq!(a.par_iter().min_by(\|x, y\| x.cmp(y)), Some(&-3));
1472	/// ```
1473	fn min_by<F>(self, f: F) -> Option<Self::Item>
1474	where
1475	F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering,
1476	{
1477	fn min<T>(f: impl Fn(&T, &T) -> Ordering) -> impl Fn(T, T) -> T {
1478	move \|a, b\| match f(&a, &b) {
1479	Ordering::Greater => b,
1480	_ => a,
1481	}
1482	}
1483
1484	self.reduce_with(min(f))
1485	}
1486
1487	/// Computes the item that yields the minimum value for the given
1488	/// function. If the iterator is empty, `None` is returned;
1489	/// otherwise, `Some(item)` is returned.
1490	///
1491	/// Note that the order in which the items will be reduced is not
1492	/// specified, so if the `Ord` impl is not truly associative, then
1493	/// the results are not deterministic.
1494	///
1495	/// # Examples
1496	///
1497	/// ```
1498	/// use rayon::prelude::*;
1499	///
1500	/// let a = [-3_i32, 34, 2, 5, -10, -3, -23];
1501	///
1502	/// assert_eq!(a.par_iter().min_by_key(\|x\| x.abs()), Some(&2));
1503	/// ```
1504	fn min_by_key<K, F>(self, f: F) -> Option<Self::Item>
1505	where
1506	K: Ord + Send,
1507	F: Sync + Send + Fn(&Self::Item) -> K,
1508	{
1509	fn key<T, K>(f: impl Fn(&T) -> K) -> impl Fn(T) -> (K, T) {
1510	move \|x\| (f(&x), x)
1511	}
1512
1513	fn min_key<T, K: Ord>(a: (K, T), b: (K, T)) -> (K, T) {
1514	match (a.0).cmp(&b.0) {
1515	Ordering::Greater => b,
1516	_ => a,
1517	}
1518	}
1519
1520	let (_, x) = self.map(key(f)).reduce_with(min_key)?;
1521	Some(x)
1522	}
1523
1524	/// Computes the maximum of all the items in the iterator. If the
1525	/// iterator is empty, `None` is returned; otherwise, `Some(max)`
1526	/// is returned.
1527	///
1528	/// Note that the order in which the items will be reduced is not
1529	/// specified, so if the `Ord` impl is not truly associative, then
1530	/// the results are not deterministic.
1531	///
1532	/// Basically equivalent to `self.reduce_with(\|a, b\| Ord::max(a, b))`.
1533	///
1534	/// # Examples
1535	///
1536	/// ```
1537	/// use rayon::prelude::*;
1538	///
1539	/// let a = [45, 74, 32];
1540	///
1541	/// assert_eq!(a.par_iter().max(), Some(&74));
1542	///
1543	/// let b: [i32; 0] = [];
1544	///
1545	/// assert_eq!(b.par_iter().max(), None);
1546	/// ```
1547	fn max(self) -> Option<Self::Item>
1548	where
1549	Self::Item: Ord,
1550	{
1551	self.reduce_with(Ord::max)
1552	}
1553
1554	/// Computes the maximum of all the items in the iterator with respect to
1555	/// the given comparison function. If the iterator is empty, `None` is
1556	/// returned; otherwise, `Some(max)` is returned.
1557	///
1558	/// Note that the order in which the items will be reduced is not
1559	/// specified, so if the comparison function is not associative, then
1560	/// the results are not deterministic.
1561	///
1562	/// # Examples
1563	///
1564	/// ```
1565	/// use rayon::prelude::*;
1566	///
1567	/// let a = [-3_i32, 77, 53, 240, -1];
1568	///
1569	/// assert_eq!(a.par_iter().max_by(\|x, y\| x.abs().cmp(&y.abs())), Some(&240));
1570	/// ```
1571	fn max_by<F>(self, f: F) -> Option<Self::Item>
1572	where
1573	F: Sync + Send + Fn(&Self::Item, &Self::Item) -> Ordering,
1574	{
1575	fn max<T>(f: impl Fn(&T, &T) -> Ordering) -> impl Fn(T, T) -> T {
1576	move \|a, b\| match f(&a, &b) {
1577	Ordering::Greater => a,
1578	_ => b,
1579	}
1580	}
1581
1582	self.reduce_with(max(f))
1583	}
1584
1585	/// Computes the item that yields the maximum value for the given
1586	/// function. If the iterator is empty, `None` is returned;
1587	/// otherwise, `Some(item)` is returned.
1588	///
1589	/// Note that the order in which the items will be reduced is not
1590	/// specified, so if the `Ord` impl is not truly associative, then
1591	/// the results are not deterministic.
1592	///
1593	/// # Examples
1594	///
1595	/// ```
1596	/// use rayon::prelude::*;
1597	///
1598	/// let a = [-3_i32, 34, 2, 5, -10, -3, -23];
1599	///
1600	/// assert_eq!(a.par_iter().max_by_key(\|x\| x.abs()), Some(&34));
1601	/// ```
1602	fn max_by_key<K, F>(self, f: F) -> Option<Self::Item>
1603	where
1604	K: Ord + Send,
1605	F: Sync + Send + Fn(&Self::Item) -> K,
1606	{
1607	fn key<T, K>(f: impl Fn(&T) -> K) -> impl Fn(T) -> (K, T) {
1608	move \|x\| (f(&x), x)
1609	}
1610
1611	fn max_key<T, K: Ord>(a: (K, T), b: (K, T)) -> (K, T) {
1612	match (a.0).cmp(&b.0) {
1613	Ordering::Greater => a,
1614	_ => b,
1615	}
1616	}
1617
1618	let (_, x) = self.map(key(f)).reduce_with(max_key)?;
1619	Some(x)
1620	}
1621
1622	/// Takes two iterators and creates a new iterator over both.
1623	///
1624	/// # Examples
1625	///
1626	/// ```
1627	/// use rayon::prelude::*;
1628	///
1629	/// let a = [0, 1, 2];
1630	/// let b = [9, 8, 7];
1631	///
1632	/// let par_iter = a.par_iter().chain(b.par_iter());
1633	///
1634	/// let chained: Vec<_> = par_iter.cloned().collect();
1635	///
1636	/// assert_eq!(&chained[..], &[0, 1, 2, 9, 8, 7]);
1637	/// ```
1638	fn chain<C>(self, chain: C) -> Chain<Self, C::Iter>
1639	where
1640	C: IntoParallelIterator<Item = Self::Item>,
1641	{
1642	Chain::new(self, chain.into_par_iter())
1643	}
1644
1645	/// Searches for some item in the parallel iterator that
1646	/// matches the given predicate and returns it. This operation
1647	/// is similar to [`find` on sequential iterators][find] but
1648	/// the item returned may not be the first one in the parallel
1649	/// sequence which matches, since we search the entire sequence in parallel.
1650	///
1651	/// Once a match is found, we will attempt to stop processing
1652	/// the rest of the items in the iterator as soon as possible
1653	/// (just as `find` stops iterating once a match is found).
1654	///
1655	/// [find]: Iterator::find()
1656	///
1657	/// # Examples
1658	///
1659	/// ```
1660	/// use rayon::prelude::*;
1661	///
1662	/// let a = [1, 2, 3, 3];
1663	///
1664	/// assert_eq!(a.par_iter().find_any(\|&&x\| x == 3), Some(&3));
1665	///
1666	/// assert_eq!(a.par_iter().find_any(\|&&x\| x == 100), None);
1667	/// ```
1668	fn find_any<P>(self, predicate: P) -> Option<Self::Item>
1669	where
1670	P: Fn(&Self::Item) -> bool + Sync + Send,
1671	{
1672	find::find(self, predicate)
1673	}
1674
1675	/// Searches for the sequentially first item in the parallel iterator
1676	/// that matches the given predicate and returns it.
1677	///
1678	/// Once a match is found, all attempts to the right of the match
1679	/// will be stopped, while attempts to the left must continue in case
1680	/// an earlier match is found.
1681	///
1682	/// For added performance, you might consider using `find_first` in conjunction with
1683	/// [`by_exponential_blocks()`][IndexedParallelIterator::by_exponential_blocks].
1684	///
1685	/// Note that not all parallel iterators have a useful order, much like
1686	/// sequential `HashMap` iteration, so "first" may be nebulous. If you
1687	/// just want the first match that discovered anywhere in the iterator,
1688	/// `find_any` is a better choice.
1689	///
1690	/// # Examples
1691	///
1692	/// ```
1693	/// use rayon::prelude::*;
1694	///
1695	/// let a = [1, 2, 3, 3];
1696	///
1697	/// assert_eq!(a.par_iter().find_first(\|&&x\| x == 3), Some(&3));
1698	///
1699	/// assert_eq!(a.par_iter().find_first(\|&&x\| x == 100), None);
1700	/// ```
1701	fn find_first<P>(self, predicate: P) -> Option<Self::Item>
1702	where
1703	P: Fn(&Self::Item) -> bool + Sync + Send,
1704	{
1705	find_first_last::find_first(self, predicate)
1706	}
1707
1708	/// Searches for the sequentially last item in the parallel iterator
1709	/// that matches the given predicate and returns it.
1710	///
1711	/// Once a match is found, all attempts to the left of the match
1712	/// will be stopped, while attempts to the right must continue in case
1713	/// a later match is found.
1714	///
1715	/// Note that not all parallel iterators have a useful order, much like
1716	/// sequential `HashMap` iteration, so "last" may be nebulous. When the
1717	/// order doesn't actually matter to you, `find_any` is a better choice.
1718	///
1719	/// # Examples
1720	///
1721	/// ```
1722	/// use rayon::prelude::*;
1723	///
1724	/// let a = [1, 2, 3, 3];
1725	///
1726	/// assert_eq!(a.par_iter().find_last(\|&&x\| x == 3), Some(&3));
1727	///
1728	/// assert_eq!(a.par_iter().find_last(\|&&x\| x == 100), None);
1729	/// ```
1730	fn find_last<P>(self, predicate: P) -> Option<Self::Item>
1731	where
1732	P: Fn(&Self::Item) -> bool + Sync + Send,
1733	{
1734	find_first_last::find_last(self, predicate)
1735	}
1736
1737	/// Applies the given predicate to the items in the parallel iterator
1738	/// and returns any non-None result of the map operation.
1739	///
1740	/// Once a non-None value is produced from the map operation, we will
1741	/// attempt to stop processing the rest of the items in the iterator
1742	/// as soon as possible.
1743	///
1744	/// Note that this method only returns some item in the parallel
1745	/// iterator that is not None from the map predicate. The item returned
1746	/// may not be the first non-None value produced in the parallel
1747	/// sequence, since the entire sequence is mapped over in parallel.
1748	///
1749	/// # Examples
1750	///
1751	/// ```
1752	/// use rayon::prelude::*;
1753	///
1754	/// let c = ["lol", "NaN", "5", "5"];
1755	///
1756	/// let found_number = c.par_iter().find_map_any(\|s\| s.parse().ok());
1757	///
1758	/// assert_eq!(found_number, Some(5));
1759	/// ```
1760	fn find_map_any<P, R>(self, predicate: P) -> Option<R>
1761	where
1762	P: Fn(Self::Item) -> Option<R> + Sync + Send,
1763	R: Send,
1764	{
1765	fn yes<T>(_: &T) -> bool {
1766	true
1767	}
1768	self.filter_map(predicate).find_any(yes)
1769	}
1770
1771	/// Applies the given predicate to the items in the parallel iterator and
1772	/// returns the sequentially first non-None result of the map operation.
1773	///
1774	/// Once a non-None value is produced from the map operation, all attempts
1775	/// to the right of the match will be stopped, while attempts to the left
1776	/// must continue in case an earlier match is found.
1777	///
1778	/// Note that not all parallel iterators have a useful order, much like
1779	/// sequential `HashMap` iteration, so "first" may be nebulous. If you
1780	/// just want the first non-None value discovered anywhere in the iterator,
1781	/// `find_map_any` is a better choice.
1782	///
1783	/// # Examples
1784	///
1785	/// ```
1786	/// use rayon::prelude::*;
1787	///
1788	/// let c = ["lol", "NaN", "2", "5"];
1789	///
1790	/// let first_number = c.par_iter().find_map_first(\|s\| s.parse().ok());
1791	///
1792	/// assert_eq!(first_number, Some(2));
1793	/// ```
1794	fn find_map_first<P, R>(self, predicate: P) -> Option<R>
1795	where
1796	P: Fn(Self::Item) -> Option<R> + Sync + Send,
1797	R: Send,
1798	{
1799	fn yes<T>(_: &T) -> bool {
1800	true
1801	}
1802	self.filter_map(predicate).find_first(yes)
1803	}
1804
1805	/// Applies the given predicate to the items in the parallel iterator and
1806	/// returns the sequentially last non-None result of the map operation.
1807	///
1808	/// Once a non-None value is produced from the map operation, all attempts
1809	/// to the left of the match will be stopped, while attempts to the right
1810	/// must continue in case a later match is found.
1811	///
1812	/// Note that not all parallel iterators have a useful order, much like
1813	/// sequential `HashMap` iteration, so "first" may be nebulous. If you
1814	/// just want the first non-None value discovered anywhere in the iterator,
1815	/// `find_map_any` is a better choice.
1816	///
1817	/// # Examples
1818	///
1819	/// ```
1820	/// use rayon::prelude::*;
1821	///
1822	/// let c = ["lol", "NaN", "2", "5"];
1823	///
1824	/// let last_number = c.par_iter().find_map_last(\|s\| s.parse().ok());
1825	///
1826	/// assert_eq!(last_number, Some(5));
1827	/// ```
1828	fn find_map_last<P, R>(self, predicate: P) -> Option<R>
1829	where
1830	P: Fn(Self::Item) -> Option<R> + Sync + Send,
1831	R: Send,
1832	{
1833	fn yes<T>(_: &T) -> bool {
1834	true
1835	}
1836	self.filter_map(predicate).find_last(yes)
1837	}
1838
1839	#[doc(hidden)]
1840	#[deprecated(note = "parallel `find` does not search in order -- use `find_any`, \\
1841	`find_first`, or `find_last`")]
1842	fn find<P>(self, predicate: P) -> Option<Self::Item>
1843	where
1844	P: Fn(&Self::Item) -> bool + Sync + Send,
1845	{
1846	self.find_any(predicate)
1847	}
1848
1849	/// Searches for some item in the parallel iterator that
1850	/// matches the given predicate, and if so returns true. Once
1851	/// a match is found, we'll attempt to stop process the rest
1852	/// of the items. Proving that there's no match, returning false,
1853	/// does require visiting every item.
1854	///
1855	/// # Examples
1856	///
1857	/// ```
1858	/// use rayon::prelude::*;
1859	///
1860	/// let a = [0, 12, 3, 4, 0, 23, 0];
1861	///
1862	/// let is_valid = a.par_iter().any(\|&x\| x > 10);
1863	///
1864	/// assert!(is_valid);
1865	/// ```
1866	fn any<P>(self, predicate: P) -> bool
1867	where
1868	P: Fn(Self::Item) -> bool + Sync + Send,
1869	{
1870	self.map(predicate).find_any(bool::clone).is_some()
1871	}
1872
1873	/// Tests that every item in the parallel iterator matches the given
1874	/// predicate, and if so returns true. If a counter-example is found,
1875	/// we'll attempt to stop processing more items, then return false.
1876	///
1877	/// # Examples
1878	///
1879	/// ```
1880	/// use rayon::prelude::*;
1881	///
1882	/// let a = [0, 12, 3, 4, 0, 23, 0];
1883	///
1884	/// let is_valid = a.par_iter().all(\|&x\| x > 10);
1885	///
1886	/// assert!(!is_valid);
1887	/// ```
1888	fn all<P>(self, predicate: P) -> bool
1889	where
1890	P: Fn(Self::Item) -> bool + Sync + Send,
1891	{
1892	#[inline]
1893	fn is_false(x: &bool) -> bool {
1894	!x
1895	}
1896
1897	self.map(predicate).find_any(is_false).is_none()
1898	}
1899
1900	/// Creates an iterator over the `Some` items of this iterator, halting
1901	/// as soon as any `None` is found.
1902	///
1903	/// # Examples
1904	///
1905	/// ```
1906	/// use rayon::prelude::*;
1907	/// use std::sync::atomic::{AtomicUsize, Ordering};
1908	///
1909	/// let counter = AtomicUsize::new(0);
1910	/// let value = (0_i32..2048)
1911	/// .into_par_iter()
1912	/// .map(\|x\| {
1913	/// counter.fetch_add(1, Ordering::SeqCst);
1914	/// if x < 1024 { Some(x) } else { None }
1915	/// })
1916	/// .while_some()
1917	/// .max();
1918	///
1919	/// assert!(value < Some(1024));
1920	/// assert!(counter.load(Ordering::SeqCst) < 2048); // should not have visited every single one
1921	/// ```
1922	fn while_some<T>(self) -> WhileSome<Self>
1923	where
1924	Self: ParallelIterator<Item = Option<T>>,
1925	T: Send,
1926	{
1927	WhileSome::new(self)
1928	}
1929
1930	/// Wraps an iterator with a fuse in case of panics, to halt all threads
1931	/// as soon as possible.
1932	///
1933	/// Panics within parallel iterators are always propagated to the caller,
1934	/// but they don't always halt the rest of the iterator right away, due to
1935	/// the internal semantics of [`join`]. This adaptor makes a greater effort
1936	/// to stop processing other items sooner, with the cost of additional
1937	/// synchronization overhead, which may also inhibit some optimizations.
1938	///
1939	/// [`join`]: crate::join()#panics
1940	///
1941	/// # Examples
1942	///
1943	/// If this code didn't use `panic_fuse()`, it would continue processing
1944	/// many more items in other threads (with long sleep delays) before the
1945	/// panic is finally propagated.
1946	///
1947	/// ```should_panic
1948	/// use rayon::prelude::*;
1949	/// use std::{thread, time};
1950	///
1951	/// (0..1_000_000)
1952	/// .into_par_iter()
1953	/// .panic_fuse()
1954	/// .for_each(\|i\| {
1955	/// // simulate some work
1956	/// thread::sleep(time::Duration::from_secs(1));
1957	/// assert!(i > 0); // oops!
1958	/// });
1959	/// ```
1960	fn panic_fuse(self) -> PanicFuse<Self> {
1961	PanicFuse::new(self)
1962	}
1963
1964	/// Creates a fresh collection containing all the elements produced
1965	/// by this parallel iterator.
1966	///
1967	/// You may prefer [`collect_into_vec()`] implemented on
1968	/// [`IndexedParallelIterator`], if your underlying iterator also implements
1969	/// it. [`collect_into_vec()`] allocates efficiently with precise knowledge
1970	/// of how many elements the iterator contains, and even allows you to reuse
1971	/// an existing vector's backing store rather than allocating a fresh vector.
1972	///
1973	/// See also [`collect_vec_list()`] for collecting into a
1974	/// `LinkedList<Vec<T>>`.
1975	///
1976	/// [`collect_into_vec()`]: IndexedParallelIterator::collect_into_vec()
1977	/// [`collect_vec_list()`]: Self::collect_vec_list()
1978	///
1979	/// # Examples
1980	///
1981	/// ```
1982	/// use rayon::prelude::*;
1983	///
1984	/// let sync_vec: Vec<_> = (0..100).into_iter().collect();
1985	///
1986	/// let async_vec: Vec<_> = (0..100).into_par_iter().collect();
1987	///
1988	/// assert_eq!(sync_vec, async_vec);
1989	/// ```
1990	///
1991	/// You can collect a pair of collections like [`unzip`](#method.unzip)
1992	/// for paired items:
1993	///
1994	/// ```
1995	/// use rayon::prelude::*;
1996	///
1997	/// let a = [(0, 1), (1, 2), (2, 3), (3, 4)];
1998	/// let (first, second): (Vec<_>, Vec<_>) = a.into_par_iter().collect();
1999	///
2000	/// assert_eq!(first, [0, 1, 2, 3]);
2001	/// assert_eq!(second, [1, 2, 3, 4]);
2002	/// ```
2003	///
2004	/// Or like [`partition_map`](#method.partition_map) for `Either` items:
2005	///
2006	/// ```
2007	/// use rayon::prelude::*;
2008	/// use rayon::iter::Either;
2009	///
2010	/// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter().map(\|x\| {
2011	/// if x % 2 == 0 {
2012	/// Either::Left(x * 4)
2013	/// } else {
2014	/// Either::Right(x * 3)
2015	/// }
2016	/// }).collect();
2017	///
2018	/// assert_eq!(left, [0, 8, 16, 24]);
2019	/// assert_eq!(right, [3, 9, 15, 21]);
2020	/// ```
2021	///
2022	/// You can even collect an arbitrarily-nested combination of pairs and `Either`:
2023	///
2024	/// ```
2025	/// use rayon::prelude::*;
2026	/// use rayon::iter::Either;
2027	///
2028	/// let (first, (left, right)): (Vec<_>, (Vec<_>, Vec<_>))
2029	/// = (0..8).into_par_iter().map(\|x\| {
2030	/// if x % 2 == 0 {
2031	/// (x, Either::Left(x * 4))
2032	/// } else {
2033	/// (-x, Either::Right(x * 3))
2034	/// }
2035	/// }).collect();
2036	///
2037	/// assert_eq!(first, [0, -1, 2, -3, 4, -5, 6, -7]);
2038	/// assert_eq!(left, [0, 8, 16, 24]);
2039	/// assert_eq!(right, [3, 9, 15, 21]);
2040	/// ```
2041	///
2042	/// All of that can _also_ be combined with short-circuiting collection of
2043	/// `Result` or `Option` types:
2044	///
2045	/// ```
2046	/// use rayon::prelude::*;
2047	/// use rayon::iter::Either;
2048	///
2049	/// let result: Result<(Vec<_>, (Vec<_>, Vec<_>)), _>
2050	/// = (0..8).into_par_iter().map(\|x\| {
2051	/// if x > 5 {
2052	/// Err(x)
2053	/// } else if x % 2 == 0 {
2054	/// Ok((x, Either::Left(x * 4)))
2055	/// } else {
2056	/// Ok((-x, Either::Right(x * 3)))
2057	/// }
2058	/// }).collect();
2059	///
2060	/// let error = result.unwrap_err();
2061	/// assert!(error == 6 \|\| error == 7);
2062	/// ```
2063	fn collect<C>(self) -> C
2064	where
2065	C: FromParallelIterator<Self::Item>,
2066	{
2067	C::from_par_iter(self)
2068	}
2069
2070	/// Unzips the items of a parallel iterator into a pair of arbitrary
2071	/// `ParallelExtend` containers.
2072	///
2073	/// You may prefer to use `unzip_into_vecs()`, which allocates more
2074	/// efficiently with precise knowledge of how many elements the
2075	/// iterator contains, and even allows you to reuse existing
2076	/// vectors' backing stores rather than allocating fresh vectors.
2077	///
2078	/// # Examples
2079	///
2080	/// ```
2081	/// use rayon::prelude::*;
2082	///
2083	/// let a = [(0, 1), (1, 2), (2, 3), (3, 4)];
2084	///
2085	/// let (left, right): (Vec<_>, Vec<_>) = a.par_iter().cloned().unzip();
2086	///
2087	/// assert_eq!(left, [0, 1, 2, 3]);
2088	/// assert_eq!(right, [1, 2, 3, 4]);
2089	/// ```
2090	///
2091	/// Nested pairs can be unzipped too.
2092	///
2093	/// ```
2094	/// use rayon::prelude::*;
2095	///
2096	/// let (values, (squares, cubes)): (Vec<_>, (Vec<_>, Vec<_>)) = (0..4).into_par_iter()
2097	/// .map(\|i\| (i, (i * i, i * i * i)))
2098	/// .unzip();
2099	///
2100	/// assert_eq!(values, [0, 1, 2, 3]);
2101	/// assert_eq!(squares, [0, 1, 4, 9]);
2102	/// assert_eq!(cubes, [0, 1, 8, 27]);
2103	/// ```
2104	fn unzip<A, B, FromA, FromB>(self) -> (FromA, FromB)
2105	where
2106	Self: ParallelIterator<Item = (A, B)>,
2107	FromA: Default + Send + ParallelExtend<A>,
2108	FromB: Default + Send + ParallelExtend<B>,
2109	A: Send,
2110	B: Send,
2111	{
2112	unzip::unzip(self)
2113	}
2114
2115	/// Partitions the items of a parallel iterator into a pair of arbitrary
2116	/// `ParallelExtend` containers. Items for which the `predicate` returns
2117	/// true go into the first container, and the rest go into the second.
2118	///
2119	/// Note: unlike the standard `Iterator::partition`, this allows distinct
2120	/// collection types for the left and right items. This is more flexible,
2121	/// but may require new type annotations when converting sequential code
2122	/// that used type inference assuming the two were the same.
2123	///
2124	/// # Examples
2125	///
2126	/// ```
2127	/// use rayon::prelude::*;
2128	///
2129	/// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter().partition(\|x\| x % 2 == 0);
2130	///
2131	/// assert_eq!(left, [0, 2, 4, 6]);
2132	/// assert_eq!(right, [1, 3, 5, 7]);
2133	/// ```
2134	fn partition<A, B, P>(self, predicate: P) -> (A, B)
2135	where
2136	A: Default + Send + ParallelExtend<Self::Item>,
2137	B: Default + Send + ParallelExtend<Self::Item>,
2138	P: Fn(&Self::Item) -> bool + Sync + Send,
2139	{
2140	unzip::partition(self, predicate)
2141	}
2142
2143	/// Partitions and maps the items of a parallel iterator into a pair of
2144	/// arbitrary `ParallelExtend` containers. `Either::Left` items go into
2145	/// the first container, and `Either::Right` items go into the second.
2146	///
2147	/// # Examples
2148	///
2149	/// ```
2150	/// use rayon::prelude::*;
2151	/// use rayon::iter::Either;
2152	///
2153	/// let (left, right): (Vec<_>, Vec<_>) = (0..8).into_par_iter()
2154	/// .partition_map(\|x\| {
2155	/// if x % 2 == 0 {
2156	/// Either::Left(x * 4)
2157	/// } else {
2158	/// Either::Right(x * 3)
2159	/// }
2160	/// });
2161	///
2162	/// assert_eq!(left, [0, 8, 16, 24]);
2163	/// assert_eq!(right, [3, 9, 15, 21]);
2164	/// ```
2165	///
2166	/// Nested `Either` enums can be split as well.
2167	///
2168	/// ```
2169	/// use rayon::prelude::*;
2170	/// use rayon::iter::Either::*;
2171	///
2172	/// let ((fizzbuzz, fizz), (buzz, other)): ((Vec<_>, Vec<_>), (Vec<_>, Vec<_>)) = (1..20)
2173	/// .into_par_iter()
2174	/// .partition_map(\|x\| match (x % 3, x % 5) {
2175	/// (0, 0) => Left(Left(x)),
2176	/// (0, _) => Left(Right(x)),
2177	/// (_, 0) => Right(Left(x)),
2178	/// (_, _) => Right(Right(x)),
2179	/// });
2180	///
2181	/// assert_eq!(fizzbuzz, [15]);
2182	/// assert_eq!(fizz, [3, 6, 9, 12, 18]);
2183	/// assert_eq!(buzz, [5, 10]);
2184	/// assert_eq!(other, [1, 2, 4, 7, 8, 11, 13, 14, 16, 17, 19]);
2185	/// ```
2186	fn partition_map<A, B, P, L, R>(self, predicate: P) -> (A, B)
2187	where
2188	A: Default + Send + ParallelExtend<L>,
2189	B: Default + Send + ParallelExtend<R>,
2190	P: Fn(Self::Item) -> Either<L, R> + Sync + Send,
2191	L: Send,
2192	R: Send,
2193	{
2194	unzip::partition_map(self, predicate)
2195	}
2196
2197	/// Intersperses clones of an element between items of this iterator.
2198	///
2199	/// # Examples
2200	///
2201	/// ```
2202	/// use rayon::prelude::*;
2203	///
2204	/// let x = vec![1, 2, 3];
2205	/// let r: Vec<_> = x.into_par_iter().intersperse(-1).collect();
2206	///
2207	/// assert_eq!(r, vec![1, -1, 2, -1, 3]);
2208	/// ```
2209	fn intersperse(self, element: Self::Item) -> Intersperse<Self>
2210	where
2211	Self::Item: Clone,
2212	{
2213	Intersperse::new(self, element)
2214	}
2215
2216	/// Creates an iterator that yields `n` elements from anywhere in the original iterator.
2217	///
2218	/// This is similar to [`IndexedParallelIterator::take`] without being
2219	/// constrained to the "first" `n` of the original iterator order. The
2220	/// taken items will still maintain their relative order where that is
2221	/// visible in `collect`, `reduce`, and similar outputs.
2222	///
2223	/// # Examples
2224	///
2225	/// ```
2226	/// use rayon::prelude::*;
2227	///
2228	/// let result: Vec<_> = (0..100)
2229	/// .into_par_iter()
2230	/// .filter(\|&x\| x % 2 == 0)
2231	/// .take_any(5)
2232	/// .collect();
2233	///
2234	/// assert_eq!(result.len(), 5);
2235	/// assert!(result.is_sorted());
2236	/// ```
2237	fn take_any(self, n: usize) -> TakeAny<Self> {
2238	TakeAny::new(self, n)
2239	}
2240
2241	/// Creates an iterator that skips `n` elements from anywhere in the original iterator.
2242	///
2243	/// This is similar to [`IndexedParallelIterator::skip`] without being
2244	/// constrained to the "first" `n` of the original iterator order. The
2245	/// remaining items will still maintain their relative order where that is
2246	/// visible in `collect`, `reduce`, and similar outputs.
2247	///
2248	/// # Examples
2249	///
2250	/// ```
2251	/// use rayon::prelude::*;
2252	///
2253	/// let result: Vec<_> = (0..100)
2254	/// .into_par_iter()
2255	/// .filter(\|&x\| x % 2 == 0)
2256	/// .skip_any(5)
2257	/// .collect();
2258	///
2259	/// assert_eq!(result.len(), 45);
2260	/// assert!(result.is_sorted());
2261	/// ```
2262	fn skip_any(self, n: usize) -> SkipAny<Self> {
2263	SkipAny::new(self, n)
2264	}
2265
2266	/// Creates an iterator that takes elements from anywhere in the original iterator
2267	/// until the given `predicate` returns `false`.
2268	///
2269	/// The `predicate` may be anything -- e.g. it could be checking a fact about the item, a
2270	/// global condition unrelated to the item itself, or some combination thereof.
2271	///
2272	/// If parallel calls to the `predicate` race and give different results, then the
2273	/// `true` results will still take those particular items, while respecting the `false`
2274	/// result from elsewhere to skip any further items.
2275	///
2276	/// This is similar to [`Iterator::take_while`] without being constrained to the original
2277	/// iterator order. The taken items will still maintain their relative order where that is
2278	/// visible in `collect`, `reduce`, and similar outputs.
2279	///
2280	/// # Examples
2281	///
2282	/// ```
2283	/// use rayon::prelude::*;
2284	///
2285	/// let result: Vec<_> = (0..100)
2286	/// .into_par_iter()
2287	/// .take_any_while(\|x\| *x < 50)
2288	/// .collect();
2289	///
2290	/// assert!(result.len() <= 50);
2291	/// assert!(result.is_sorted());
2292	/// ```
2293	///
2294	/// ```
2295	/// use rayon::prelude::*;
2296	/// use std::sync::atomic::AtomicUsize;
2297	/// use std::sync::atomic::Ordering::Relaxed;
2298	///
2299	/// // Collect any group of items that sum <= 1000
2300	/// let quota = AtomicUsize::new(1000);
2301	/// let result: Vec<_> = (0_usize..100)
2302	/// .into_par_iter()
2303	/// .take_any_while(\|&x\| {
2304	/// quota.fetch_update(Relaxed, Relaxed, \|q\| q.checked_sub(x))
2305	/// .is_ok()
2306	/// })
2307	/// .collect();
2308	///
2309	/// let sum = result.iter().sum::<usize>();
2310	/// assert!(matches!(sum, 902..=1000));
2311	/// ```
2312	fn take_any_while<P>(self, predicate: P) -> TakeAnyWhile<Self, P>
2313	where
2314	P: Fn(&Self::Item) -> bool + Sync + Send,
2315	{
2316	TakeAnyWhile::new(self, predicate)
2317	}
2318
2319	/// Creates an iterator that skips elements from anywhere in the original iterator
2320	/// until the given `predicate` returns `false`.
2321	///
2322	/// The `predicate` may be anything -- e.g. it could be checking a fact about the item, a
2323	/// global condition unrelated to the item itself, or some combination thereof.
2324	///
2325	/// If parallel calls to the `predicate` race and give different results, then the
2326	/// `true` results will still skip those particular items, while respecting the `false`
2327	/// result from elsewhere to skip any further items.
2328	///
2329	/// This is similar to [`Iterator::skip_while`] without being constrained to the original
2330	/// iterator order. The remaining items will still maintain their relative order where that is
2331	/// visible in `collect`, `reduce`, and similar outputs.
2332	///
2333	/// # Examples
2334	///
2335	/// ```
2336	/// use rayon::prelude::*;
2337	///
2338	/// let result: Vec<_> = (0..100)
2339	/// .into_par_iter()
2340	/// .skip_any_while(\|x\| *x < 50)
2341	/// .collect();
2342	///
2343	/// assert!(result.len() >= 50);
2344	/// assert!(result.is_sorted());
2345	/// ```
2346	fn skip_any_while<P>(self, predicate: P) -> SkipAnyWhile<Self, P>
2347	where
2348	P: Fn(&Self::Item) -> bool + Sync + Send,
2349	{
2350	SkipAnyWhile::new(self, predicate)
2351	}
2352
2353	/// Collects this iterator into a linked list of vectors.
2354	///
2355	/// This is useful when you need to condense a parallel iterator into a collection,
2356	/// but have no specific requirements for what that collection should be. If you
2357	/// plan to store the collection longer-term, `Vec<T>` is, as always, likely the
2358	/// best default choice, despite the overhead that comes from concatenating each
2359	/// vector. Or, if this is an `IndexedParallelIterator`, you should also prefer to
2360	/// just collect to a `Vec<T>`.
2361	///
2362	/// Internally, most [`FromParallelIterator`]/[`ParallelExtend`] implementations
2363	/// use this strategy; each job collecting their chunk of the iterator to a `Vec<T>`
2364	/// and those chunks getting merged into a `LinkedList`, before then extending the
2365	/// collection with each vector. This is a very efficient way to collect an
2366	/// unindexed parallel iterator, without much intermediate data movement.
2367	///
2368	/// # Examples
2369	///
2370	/// ```
2371	/// # use std::collections::LinkedList;
2372	/// use rayon::prelude::*;
2373	///
2374	/// let result: LinkedList<Vec<_>> = (0..=100)
2375	/// .into_par_iter()
2376	/// .filter(\|x\| x % 2 == 0)
2377	/// .flat_map(\|x\| 0..x)
2378	/// .collect_vec_list();
2379	///
2380	/// // `par_iter.collect_vec_list().into_iter().flatten()` turns
2381	/// // a parallel iterator into a serial one
2382	/// let total_len = result.into_iter().flatten().count();
2383	/// assert_eq!(total_len, 2550);
2384	/// ```
2385	fn collect_vec_list(self) -> LinkedList<Vec<Self::Item>> {
2386	match extend::fast_collect(self) {
2387	Either::Left(vec) => {
2388	let mut list = LinkedList::new();
2389	if !vec.is_empty() {
2390	list.push_back(vec);
2391	}
2392	list
2393	}
2394	Either::Right(list) => list,
2395	}
2396	}
2397
2398	/// Internal method used to define the behavior of this parallel
2399	/// iterator. You should not need to call this directly.
2400	///
2401	/// This method causes the iterator `self` to start producing
2402	/// items and to feed them to the consumer `consumer` one by one.
2403	/// It may split the consumer before doing so to create the
2404	/// opportunity to produce in parallel.
2405	///
2406	/// See the [README] for more details on the internals of parallel
2407	/// iterators.
2408	///
2409	/// [README]: https://github.com/rayon-rs/rayon/blob/main/src/iter/plumbing/README.md
2410	fn drive_unindexed<C>(self, consumer: C) -> C::Result
2411	where
2412	C: UnindexedConsumer<Self::Item>;
2413
2414	/// Internal method used to define the behavior of this parallel
2415	/// iterator. You should not need to call this directly.
2416	///
2417	/// Returns the number of items produced by this iterator, if known
2418	/// statically. This can be used by consumers to trigger special fast
2419	/// paths. Therefore, if `Some(_)` is returned, this iterator must only
2420	/// use the (indexed) `Consumer` methods when driving a consumer, such
2421	/// as `split_at()`. Calling `UnindexedConsumer::split_off_left()` or
2422	/// other `UnindexedConsumer` methods -- or returning an inaccurate
2423	/// value -- may result in panics.
2424	///
2425	/// This method is currently used to optimize `collect` for want
2426	/// of true Rust specialization; it may be removed when
2427	/// specialization is stable.
2428	fn opt_len(&self) -> Option<usize> {
2429	None
2430	}
2431	}
2432
2433	impl<T: ParallelIterator> IntoParallelIterator for T {
2434	type Iter = T;
2435	type Item = T::Item;
2436
2437	fn into_par_iter(self) -> T {
2438	self
2439	}
2440	}
2441
2442	/// An iterator that supports "random access" to its data, meaning
2443	/// that you can split it at arbitrary indices and draw data from
2444	/// those points.
2445	///
2446	/// Note: Not implemented for `u64`, `i64`, `u128`, or `i128` ranges
2447	// Waiting for `ExactSizeIterator::is_empty` to be stabilized. See rust-lang/rust#35428
2448	#[expect(clippy::len_without_is_empty)]
2449	pub trait IndexedParallelIterator: ParallelIterator {
2450	/// Divides an iterator into sequential blocks of exponentially-increasing size.
2451	///
2452	/// Normally, parallel iterators are recursively divided into tasks in parallel.
2453	/// This adaptor changes the default behavior by splitting the iterator into a sequence
2454	/// of parallel iterators of increasing sizes.
2455	/// Sizes grow exponentially in order to avoid creating
2456	/// too many blocks. This also allows to balance the current block with all previous ones.
2457	///
2458	/// This can have many applications but the most notable ones are:
2459	/// - better performance with [`find_first()`][ParallelIterator::find_first]
2460	/// - more predictable performance with [`find_any()`][ParallelIterator::find_any]
2461	/// or any interruptible computation
2462	///
2463	/// # Examples
2464	///
2465	/// ```
2466	/// use rayon::prelude::*;
2467	/// assert_eq!((0..10_000).into_par_iter()
2468	/// .by_exponential_blocks()
2469	/// .find_first(\|&e\| e==4_999), Some(4_999))
2470	/// ```
2471	///
2472	/// In this example, without blocks, rayon will split the initial range into two but all work
2473	/// on the right hand side (from 5,000 onwards) is useless since the sequential algorithm
2474	/// never goes there. This means that if two threads are used there will be no speedup **at
2475	/// all**.
2476	///
2477	/// `by_exponential_blocks` on the other hand will start with the leftmost range from 0
2478	/// to `p` (threads number), continue with p to 3p, the 3p to 7p...
2479	///
2480	/// Each subrange is treated in parallel, while all subranges are treated sequentially.
2481	/// We therefore ensure a logarithmic number of blocks (and overhead) while guaranteeing
2482	/// we stop at the first block containing the searched data.
2483	fn by_exponential_blocks(self) -> ExponentialBlocks<Self> {
2484	ExponentialBlocks::new(self)
2485	}
2486
2487	/// Divides an iterator into sequential blocks of the given size.
2488	///
2489	/// Normally, parallel iterators are recursively divided into tasks in parallel.
2490	/// This adaptor changes the default behavior by splitting the iterator into a sequence
2491	/// of parallel iterators of given `block_size`.
2492	/// The main application is to obtain better
2493	/// memory locality (especially if the reduce operation re-use folded data).
2494	///
2495	/// Panics if `block_size` is 0.
2496	///
2497	/// # Example
2498	/// ```
2499	/// use rayon::prelude::*;
2500	/// // during most reductions v1 and v2 fit the cache
2501	/// let v = (0u32..10_000_000)
2502	/// .into_par_iter()
2503	/// .by_uniform_blocks(1_000_000)
2504	/// .fold(Vec::new, \|mut v, e\| { v.push(e); v})
2505	/// .reduce(Vec::new, \|mut v1, mut v2\| { v1.append(&mut v2); v1});
2506	/// assert_eq!(v, (0u32..10_000_000).collect::<Vec<u32>>());
2507	/// ```
2508	#[track_caller]
2509	fn by_uniform_blocks(self, block_size: usize) -> UniformBlocks<Self> {
2510	assert!(block_size != 0, "block_size must not be zero");
2511	UniformBlocks::new(self, block_size)
2512	}
2513
2514	/// Collects the results of the iterator into the specified
2515	/// vector. The vector is always cleared before execution
2516	/// begins. If possible, reusing the vector across calls can lead
2517	/// to better performance since it reuses the same backing buffer.
2518	///
2519	/// # Examples
2520	///
2521	/// ```
2522	/// use rayon::prelude::*;
2523	///
2524	/// // any prior data will be cleared
2525	/// let mut vec = vec![-1, -2, -3];
2526	///
2527	/// (0..5).into_par_iter()
2528	/// .collect_into_vec(&mut vec);
2529	///
2530	/// assert_eq!(vec, [0, 1, 2, 3, 4]);
2531	/// ```
2532	fn collect_into_vec(self, target: &mut Vec<Self::Item>) {
2533	collect::collect_into_vec(self, target);
2534	}
2535
2536	/// Unzips the results of the iterator into the specified
2537	/// vectors. The vectors are always cleared before execution
2538	/// begins. If possible, reusing the vectors across calls can lead
2539	/// to better performance since they reuse the same backing buffer.
2540	///
2541	/// # Examples
2542	///
2543	/// ```
2544	/// use rayon::prelude::*;
2545	///
2546	/// // any prior data will be cleared
2547	/// let mut left = vec![42; 10];
2548	/// let mut right = vec![-1; 10];
2549	///
2550	/// (10..15).into_par_iter()
2551	/// .enumerate()
2552	/// .unzip_into_vecs(&mut left, &mut right);
2553	///
2554	/// assert_eq!(left, [0, 1, 2, 3, 4]);
2555	/// assert_eq!(right, [10, 11, 12, 13, 14]);
2556	/// ```
2557	fn unzip_into_vecs<A, B>(self, left: &mut Vec<A>, right: &mut Vec<B>)
2558	where
2559	Self: IndexedParallelIterator<Item = (A, B)>,
2560	A: Send,
2561	B: Send,
2562	{
2563	collect::unzip_into_vecs(self, left, right);
2564	}
2565
2566	/// Iterates over tuples `(A, B)`, where the items `A` are from
2567	/// this iterator and `B` are from the iterator given as argument.
2568	/// Like the `zip` method on ordinary iterators, if the two
2569	/// iterators are of unequal length, you only get the items they
2570	/// have in common.
2571	///
2572	/// # Examples
2573	///
2574	/// ```
2575	/// use rayon::prelude::*;
2576	///
2577	/// let result: Vec<_> = (1..4)
2578	/// .into_par_iter()
2579	/// .zip(vec!['a', 'b', 'c'])
2580	/// .collect();
2581	///
2582	/// assert_eq!(result, [(1, 'a'), (2, 'b'), (3, 'c')]);
2583	/// ```
2584	fn zip<Z>(self, zip_op: Z) -> Zip<Self, Z::Iter>
2585	where
2586	Z: IntoParallelIterator<Iter: IndexedParallelIterator>,
2587	{
2588	Zip::new(self, zip_op.into_par_iter())
2589	}
2590
2591	/// The same as `Zip`, but requires that both iterators have the same length.
2592	///
2593	/// # Panics
2594	/// Will panic if `self` and `zip_op` are not the same length.
2595	///
2596	/// ```should_panic
2597	/// use rayon::prelude::*;
2598	///
2599	/// let one = [1u8];
2600	/// let two = [2u8, 2];
2601	/// let one_iter = one.par_iter();
2602	/// let two_iter = two.par_iter();
2603	///
2604	/// // this will panic
2605	/// let zipped: Vec<(&u8, &u8)> = one_iter.zip_eq(two_iter).collect();
2606	///
2607	/// // we should never get here
2608	/// assert_eq!(1, zipped.len());
2609	/// ```
2610	#[track_caller]
2611	fn zip_eq<Z>(self, zip_op: Z) -> ZipEq<Self, Z::Iter>
2612	where
2613	Z: IntoParallelIterator<Iter: IndexedParallelIterator>,
2614	{
2615	let zip_op_iter = zip_op.into_par_iter();
2616	assert_eq!(
2617	self.len(),
2618	zip_op_iter.len(),
2619	"iterators must have the same length"
2620	);
2621	ZipEq::new(self, zip_op_iter)
2622	}
2623
2624	/// Interleaves elements of this iterator and the other given
2625	/// iterator. Alternately yields elements from this iterator and
2626	/// the given iterator, until both are exhausted. If one iterator
2627	/// is exhausted before the other, the last elements are provided
2628	/// from the other.
2629	///
2630	/// # Examples
2631	///
2632	/// ```
2633	/// use rayon::prelude::*;
2634	/// let (x, y) = (vec![1, 2], vec![3, 4, 5, 6]);
2635	/// let r: Vec<i32> = x.into_par_iter().interleave(y).collect();
2636	/// assert_eq!(r, vec![1, 3, 2, 4, 5, 6]);
2637	/// ```
2638	fn interleave<I>(self, other: I) -> Interleave<Self, I::Iter>
2639	where
2640	I: IntoParallelIterator<Item = Self::Item, Iter: IndexedParallelIterator>,
2641	{
2642	Interleave::new(self, other.into_par_iter())
2643	}
2644
2645	/// Interleaves elements of this iterator and the other given
2646	/// iterator, until one is exhausted.
2647	///
2648	/// # Examples
2649	///
2650	/// ```
2651	/// use rayon::prelude::*;
2652	/// let (x, y) = (vec![1, 2, 3, 4], vec![5, 6]);
2653	/// let r: Vec<i32> = x.into_par_iter().interleave_shortest(y).collect();
2654	/// assert_eq!(r, vec![1, 5, 2, 6, 3]);
2655	/// ```
2656	fn interleave_shortest<I>(self, other: I) -> InterleaveShortest<Self, I::Iter>
2657	where
2658	I: IntoParallelIterator<Item = Self::Item, Iter: IndexedParallelIterator>,
2659	{
2660	InterleaveShortest::new(self, other.into_par_iter())
2661	}
2662
2663	/// Splits an iterator up into fixed-size chunks.
2664	///
2665	/// Returns an iterator that returns `Vec`s of the given number of elements.
2666	/// If the number of elements in the iterator is not divisible by `chunk_size`,
2667	/// the last chunk may be shorter than `chunk_size`.
2668	///
2669	/// See also [`par_chunks()`] and [`par_chunks_mut()`] for similar behavior on
2670	/// slices, without having to allocate intermediate `Vec`s for the chunks.
2671	///
2672	/// [`par_chunks()`]: crate::slice::ParallelSlice::par_chunks()
2673	/// [`par_chunks_mut()`]: crate::slice::ParallelSliceMut::par_chunks_mut()
2674	///
2675	/// Panics if `chunk_size` is 0.
2676	///
2677	/// # Examples
2678	///
2679	/// ```
2680	/// use rayon::prelude::*;
2681	/// let a = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
2682	/// let r: Vec<Vec<i32>> = a.into_par_iter().chunks(3).collect();
2683	/// assert_eq!(r, vec![vec![1,2,3], vec![4,5,6], vec![7,8,9], vec![10]]);
2684	/// ```
2685	#[track_caller]
2686	fn chunks(self, chunk_size: usize) -> Chunks<Self> {
2687	assert!(chunk_size != 0, "chunk_size must not be zero");
2688	Chunks::new(self, chunk_size)
2689	}
2690
2691	/// Splits an iterator into fixed-size chunks, performing a sequential [`fold()`] on
2692	/// each chunk.
2693	///
2694	/// Returns an iterator that produces a folded result for each chunk of items
2695	/// produced by this iterator.
2696	///
2697	/// This works essentially like:
2698	///
2699	/// ```text
2700	/// iter.chunks(chunk_size)
2701	/// .map(\|chunk\|
2702	/// chunk.into_iter()
2703	/// .fold(identity, fold_op)
2704	/// )
2705	/// ```
2706	///
2707	/// except there is no per-chunk allocation overhead.
2708	///
2709	/// [`fold()`]: std::iter::Iterator#method.fold
2710	///
2711	/// Panics if `chunk_size` is 0.
2712	///
2713	/// # Examples
2714	///
2715	/// ```
2716	/// use rayon::prelude::*;
2717	/// let nums = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
2718	/// let chunk_sums = nums.into_par_iter().fold_chunks(2, \|\| 0, \|a, n\| a + n).collect::<Vec<_>>();
2719	/// assert_eq!(chunk_sums, vec![3, 7, 11, 15, 19]);
2720	/// ```
2721	#[track_caller]
2722	fn fold_chunks<T, ID, F>(
2723	self,
2724	chunk_size: usize,
2725	identity: ID,
2726	fold_op: F,
2727	) -> FoldChunks<Self, ID, F>
2728	where
2729	ID: Fn() -> T + Send + Sync,
2730	F: Fn(T, Self::Item) -> T + Send + Sync,
2731	T: Send,
2732	{
2733	assert!(chunk_size != 0, "chunk_size must not be zero");
2734	FoldChunks::new(self, chunk_size, identity, fold_op)
2735	}
2736
2737	/// Splits an iterator into fixed-size chunks, performing a sequential [`fold()`] on
2738	/// each chunk.
2739	///
2740	/// Returns an iterator that produces a folded result for each chunk of items
2741	/// produced by this iterator.
2742	///
2743	/// This works essentially like `fold_chunks(chunk_size, \|\| init.clone(), fold_op)`,
2744	/// except it doesn't require the `init` type to be `Sync`, nor any other form of
2745	/// added synchronization.
2746	///
2747	/// [`fold()`]: std::iter::Iterator#method.fold
2748	///
2749	/// Panics if `chunk_size` is 0.
2750	///
2751	/// # Examples
2752	///
2753	/// ```
2754	/// use rayon::prelude::*;
2755	/// let nums = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
2756	/// let chunk_sums = nums.into_par_iter().fold_chunks_with(2, 0, \|a, n\| a + n).collect::<Vec<_>>();
2757	/// assert_eq!(chunk_sums, vec![3, 7, 11, 15, 19]);
2758	/// ```
2759	#[track_caller]
2760	fn fold_chunks_with<T, F>(
2761	self,
2762	chunk_size: usize,
2763	init: T,
2764	fold_op: F,
2765	) -> FoldChunksWith<Self, T, F>
2766	where
2767	T: Send + Clone,
2768	F: Fn(T, Self::Item) -> T + Send + Sync,
2769	{
2770	assert!(chunk_size != 0, "chunk_size must not be zero");
2771	FoldChunksWith::new(self, chunk_size, init, fold_op)
2772	}
2773
2774	/// Lexicographically compares the elements of this `ParallelIterator` with those of
2775	/// another.
2776	///
2777	/// # Examples
2778	///
2779	/// ```
2780	/// use rayon::prelude::*;
2781	/// use std::cmp::Ordering::*;
2782	///
2783	/// let x = vec![1, 2, 3];
2784	/// assert_eq!(x.par_iter().cmp(&vec![1, 3, 0]), Less);
2785	/// assert_eq!(x.par_iter().cmp(&vec![1, 2, 3]), Equal);
2786	/// assert_eq!(x.par_iter().cmp(&vec![1, 2]), Greater);
2787	/// ```
2788	fn cmp<I>(self, other: I) -> Ordering
2789	where
2790	I: IntoParallelIterator<Item = Self::Item, Iter: IndexedParallelIterator>,
2791	Self::Item: Ord,
2792	{
2793	#[inline]
2794	fn ordering<T: Ord>((x, y): (T, T)) -> Ordering {
2795	Ord::cmp(&x, &y)
2796	}
2797
2798	#[inline]
2799	fn inequal(&ord: &Ordering) -> bool {
2800	ord != Ordering::Equal
2801	}
2802
2803	let other = other.into_par_iter();
2804	let ord_len = self.len().cmp(&other.len());
2805	self.zip(other)
2806	.map(ordering)
2807	.find_first(inequal)
2808	.unwrap_or(ord_len)
2809	}
2810
2811	/// Lexicographically compares the elements of this `ParallelIterator` with those of
2812	/// another.
2813	///
2814	/// # Examples
2815	///
2816	/// ```
2817	/// use rayon::prelude::*;
2818	/// use std::cmp::Ordering::*;
2819	///
2820	/// let x = vec![1.0, 2.0, 3.0];
2821	/// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 3.0, 0.0]), Some(Less));
2822	/// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 2.0, 3.0]), Some(Equal));
2823	/// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, 2.0]), Some(Greater));
2824	/// assert_eq!(x.par_iter().partial_cmp(&vec![1.0, f64::NAN]), None);
2825	/// ```
2826	fn partial_cmp<I>(self, other: I) -> Option<Ordering>
2827	where
2828	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2829	Self::Item: PartialOrd<I::Item>,
2830	{
2831	#[inline]
2832	fn ordering<T: PartialOrd<U>, U>((x, y): (T, U)) -> Option<Ordering> {
2833	PartialOrd::partial_cmp(&x, &y)
2834	}
2835
2836	#[inline]
2837	fn inequal(&ord: &Option<Ordering>) -> bool {
2838	ord != Some(Ordering::Equal)
2839	}
2840
2841	let other = other.into_par_iter();
2842	let ord_len = self.len().cmp(&other.len());
2843	self.zip(other)
2844	.map(ordering)
2845	.find_first(inequal)
2846	.unwrap_or(Some(ord_len))
2847	}
2848
2849	/// Determines if the elements of this `ParallelIterator`
2850	/// are equal to those of another
2851	fn eq<I>(self, other: I) -> bool
2852	where
2853	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2854	Self::Item: PartialEq<I::Item>,
2855	{
2856	#[inline]
2857	fn eq<T: PartialEq<U>, U>((x, y): (T, U)) -> bool {
2858	PartialEq::eq(&x, &y)
2859	}
2860
2861	let other = other.into_par_iter();
2862	self.len() == other.len() && self.zip(other).all(eq)
2863	}
2864
2865	/// Determines if the elements of this `ParallelIterator`
2866	/// are unequal to those of another
2867	fn ne<I>(self, other: I) -> bool
2868	where
2869	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2870	Self::Item: PartialEq<I::Item>,
2871	{
2872	!self.eq(other)
2873	}
2874
2875	/// Determines if the elements of this `ParallelIterator`
2876	/// are lexicographically less than those of another.
2877	fn lt<I>(self, other: I) -> bool
2878	where
2879	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2880	Self::Item: PartialOrd<I::Item>,
2881	{
2882	self.partial_cmp(other) == Some(Ordering::Less)
2883	}
2884
2885	/// Determines if the elements of this `ParallelIterator`
2886	/// are less than or equal to those of another.
2887	fn le<I>(self, other: I) -> bool
2888	where
2889	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2890	Self::Item: PartialOrd<I::Item>,
2891	{
2892	let ord = self.partial_cmp(other);
2893	ord == Some(Ordering::Equal) \|\| ord == Some(Ordering::Less)
2894	}
2895
2896	/// Determines if the elements of this `ParallelIterator`
2897	/// are lexicographically greater than those of another.
2898	fn gt<I>(self, other: I) -> bool
2899	where
2900	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2901	Self::Item: PartialOrd<I::Item>,
2902	{
2903	self.partial_cmp(other) == Some(Ordering::Greater)
2904	}
2905
2906	/// Determines if the elements of this `ParallelIterator`
2907	/// are greater than or equal to those of another.
2908	fn ge<I>(self, other: I) -> bool
2909	where
2910	I: IntoParallelIterator<Iter: IndexedParallelIterator>,
2911	Self::Item: PartialOrd<I::Item>,
2912	{
2913	let ord = self.partial_cmp(other);
2914	ord == Some(Ordering::Equal) \|\| ord == Some(Ordering::Greater)
2915	}
2916
2917	/// Yields an index along with each item.
2918	///
2919	/// # Examples
2920	///
2921	/// ```
2922	/// use rayon::prelude::*;
2923	///
2924	/// let chars = vec!['a', 'b', 'c'];
2925	/// let result: Vec<_> = chars
2926	/// .into_par_iter()
2927	/// .enumerate()
2928	/// .collect();
2929	///
2930	/// assert_eq!(result, [(0, 'a'), (1, 'b'), (2, 'c')]);
2931	/// ```
2932	fn enumerate(self) -> Enumerate<Self> {
2933	Enumerate::new(self)
2934	}
2935
2936	/// Creates an iterator that steps by the given amount
2937	///
2938	/// # Examples
2939	///
2940	/// ```
2941	///use rayon::prelude::*;
2942	///
2943	/// let range = (3..10);
2944	/// let result: Vec<i32> = range
2945	/// .into_par_iter()
2946	/// .step_by(3)
2947	/// .collect();
2948	///
2949	/// assert_eq!(result, [3, 6, 9])
2950	/// ```
2951	fn step_by(self, step: usize) -> StepBy<Self> {
2952	StepBy::new(self, step)
2953	}
2954
2955	/// Creates an iterator that skips the first `n` elements.
2956	///
2957	/// # Examples
2958	///
2959	/// ```
2960	/// use rayon::prelude::*;
2961	///
2962	/// let result: Vec<_> = (0..100)
2963	/// .into_par_iter()
2964	/// .skip(95)
2965	/// .collect();
2966	///
2967	/// assert_eq!(result, [95, 96, 97, 98, 99]);
2968	/// ```
2969	fn skip(self, n: usize) -> Skip<Self> {
2970	Skip::new(self, n)
2971	}
2972
2973	/// Creates an iterator that yields the first `n` elements.
2974	///
2975	/// # Examples
2976	///
2977	/// ```
2978	/// use rayon::prelude::*;
2979	///
2980	/// let result: Vec<_> = (0..100)
2981	/// .into_par_iter()
2982	/// .take(5)
2983	/// .collect();
2984	///
2985	/// assert_eq!(result, [0, 1, 2, 3, 4]);
2986	/// ```
2987	fn take(self, n: usize) -> Take<Self> {
2988	Take::new(self, n)
2989	}
2990
2991	/// Searches for some item in the parallel iterator that
2992	/// matches the given predicate, and returns its index. Like
2993	/// `ParallelIterator::find_any`, the parallel search will not
2994	/// necessarily find the first match, and once a match is
2995	/// found we'll attempt to stop processing any more.
2996	///
2997	/// # Examples
2998	///
2999	/// ```
3000	/// use rayon::prelude::*;
3001	///
3002	/// let a = [1, 2, 3, 3];
3003	///
3004	/// let i = a.par_iter().position_any(\|&x\| x == 3).expect("found");
3005	/// assert!(i == 2 \|\| i == 3);
3006	///
3007	/// assert_eq!(a.par_iter().position_any(\|&x\| x == 100), None);
3008	/// ```
3009	fn position_any<P>(self, predicate: P) -> Option<usize>
3010	where
3011	P: Fn(Self::Item) -> bool + Sync + Send,
3012	{
3013	#[inline]
3014	fn check(&(_, p): &(usize, bool)) -> bool {
3015	p
3016	}
3017
3018	let (i, _) = self.map(predicate).enumerate().find_any(check)?;
3019	Some(i)
3020	}
3021
3022	/// Searches for the sequentially first item in the parallel iterator
3023	/// that matches the given predicate, and returns its index.
3024	///
3025	/// Like `ParallelIterator::find_first`, once a match is found,
3026	/// all attempts to the right of the match will be stopped, while
3027	/// attempts to the left must continue in case an earlier match
3028	/// is found.
3029	///
3030	/// Note that not all parallel iterators have a useful order, much like
3031	/// sequential `HashMap` iteration, so "first" may be nebulous. If you
3032	/// just want the first match that discovered anywhere in the iterator,
3033	/// `position_any` is a better choice.
3034	///
3035	/// # Examples
3036	///
3037	/// ```
3038	/// use rayon::prelude::*;
3039	///
3040	/// let a = [1, 2, 3, 3];
3041	///
3042	/// assert_eq!(a.par_iter().position_first(\|&x\| x == 3), Some(2));
3043	///
3044	/// assert_eq!(a.par_iter().position_first(\|&x\| x == 100), None);
3045	/// ```
3046	fn position_first<P>(self, predicate: P) -> Option<usize>
3047	where
3048	P: Fn(Self::Item) -> bool + Sync + Send,
3049	{
3050	#[inline]
3051	fn check(&(_, p): &(usize, bool)) -> bool {
3052	p
3053	}
3054
3055	let (i, _) = self.map(predicate).enumerate().find_first(check)?;
3056	Some(i)
3057	}
3058
3059	/// Searches for the sequentially last item in the parallel iterator
3060	/// that matches the given predicate, and returns its index.
3061	///
3062	/// Like `ParallelIterator::find_last`, once a match is found,
3063	/// all attempts to the left of the match will be stopped, while
3064	/// attempts to the right must continue in case a later match
3065	/// is found.
3066	///
3067	/// Note that not all parallel iterators have a useful order, much like
3068	/// sequential `HashMap` iteration, so "last" may be nebulous. When the
3069	/// order doesn't actually matter to you, `position_any` is a better
3070	/// choice.
3071	///
3072	/// # Examples
3073	///
3074	/// ```
3075	/// use rayon::prelude::*;
3076	///
3077	/// let a = [1, 2, 3, 3];
3078	///
3079	/// assert_eq!(a.par_iter().position_last(\|&x\| x == 3), Some(3));
3080	///
3081	/// assert_eq!(a.par_iter().position_last(\|&x\| x == 100), None);
3082	/// ```
3083	fn position_last<P>(self, predicate: P) -> Option<usize>
3084	where
3085	P: Fn(Self::Item) -> bool + Sync + Send,
3086	{
3087	#[inline]
3088	fn check(&(_, p): &(usize, bool)) -> bool {
3089	p
3090	}
3091
3092	let (i, _) = self.map(predicate).enumerate().find_last(check)?;
3093	Some(i)
3094	}
3095
3096	#[doc(hidden)]
3097	#[deprecated(
3098	note = "parallel `position` does not search in order -- use `position_any`, \\
3099	`position_first`, or `position_last`"
3100	)]
3101	fn position<P>(self, predicate: P) -> Option<usize>
3102	where
3103	P: Fn(Self::Item) -> bool + Sync + Send,
3104	{
3105	self.position_any(predicate)
3106	}
3107
3108	/// Searches for items in the parallel iterator that match the given
3109	/// predicate, and returns their indices.
3110	///
3111	/// # Examples
3112	///
3113	/// ```
3114	/// use rayon::prelude::*;
3115	///
3116	/// let primes = vec![2, 3, 5, 7, 11, 13, 17, 19, 23, 29];
3117	///
3118	/// // Find the positions of primes congruent to 1 modulo 6
3119	/// let p1mod6: Vec<_> = primes.par_iter().positions(\|&p\| p % 6 == 1).collect();
3120	/// assert_eq!(p1mod6, [3, 5, 7]); // primes 7, 13, and 19
3121	///
3122	/// // Find the positions of primes congruent to 5 modulo 6
3123	/// let p5mod6: Vec<_> = primes.par_iter().positions(\|&p\| p % 6 == 5).collect();
3124	/// assert_eq!(p5mod6, [2, 4, 6, 8, 9]); // primes 5, 11, 17, 23, and 29
3125	/// ```
3126	fn positions<P>(self, predicate: P) -> Positions<Self, P>
3127	where
3128	P: Fn(Self::Item) -> bool + Sync + Send,
3129	{
3130	Positions::new(self, predicate)
3131	}
3132
3133	/// Produces a new iterator with the elements of this iterator in
3134	/// reverse order.
3135	///
3136	/// # Examples
3137	///
3138	/// ```
3139	/// use rayon::prelude::*;
3140	///
3141	/// let result: Vec<_> = (0..5)
3142	/// .into_par_iter()
3143	/// .rev()
3144	/// .collect();
3145	///
3146	/// assert_eq!(result, [4, 3, 2, 1, 0]);
3147	/// ```
3148	fn rev(self) -> Rev<Self> {
3149	Rev::new(self)
3150	}
3151
3152	/// Sets the minimum length of iterators desired to process in each
3153	/// rayon job. Rayon will not split any smaller than this length, but
3154	/// of course an iterator could already be smaller to begin with.
3155	///
3156	/// Producers like `zip` and `interleave` will use greater of the two
3157	/// minimums.
3158	/// Chained iterators and iterators inside `flat_map` may each use
3159	/// their own minimum length.
3160	///
3161	/// # Examples
3162	///
3163	/// ```
3164	/// use rayon::prelude::*;
3165	///
3166	/// let min = (0..1_000_000)
3167	/// .into_par_iter()
3168	/// .with_min_len(1234)
3169	/// .fold(\|\| 0, \|acc, _\| acc + 1) // count how many are in this segment
3170	/// .min().unwrap();
3171	///
3172	/// assert!(min >= 1234);
3173	/// ```
3174	fn with_min_len(self, min: usize) -> MinLen<Self> {
3175	MinLen::new(self, min)
3176	}
3177
3178	/// Sets the maximum length of iterators desired to process in each
3179	/// rayon job. Rayon will try to split at least below this length,
3180	/// unless that would put it below the length from `with_min_len()`.
3181	/// For example, given min=10 and max=15, a length of 16 will not be
3182	/// split any further.
3183	///
3184	/// Producers like `zip` and `interleave` will use lesser of the two
3185	/// maximums.
3186	/// Chained iterators and iterators inside `flat_map` may each use
3187	/// their own maximum length.
3188	///
3189	/// # Examples
3190	///
3191	/// ```
3192	/// use rayon::prelude::*;
3193	///
3194	/// let max = (0..1_000_000)
3195	/// .into_par_iter()
3196	/// .with_max_len(1234)
3197	/// .fold(\|\| 0, \|acc, _\| acc + 1) // count how many are in this segment
3198	/// .max().unwrap();
3199	///
3200	/// assert!(max <= 1234);
3201	/// ```
3202	fn with_max_len(self, max: usize) -> MaxLen<Self> {
3203	MaxLen::new(self, max)
3204	}
3205
3206	/// Produces an exact count of how many items this iterator will
3207	/// produce, presuming no panic occurs.
3208	///
3209	/// # Examples
3210	///
3211	/// ```
3212	/// use rayon::prelude::*;
3213	///
3214	/// let par_iter = (0..100).into_par_iter().zip(vec![0; 10]);
3215	/// assert_eq!(par_iter.len(), 10);
3216	///
3217	/// let vec: Vec<_> = par_iter.collect();
3218	/// assert_eq!(vec.len(), 10);
3219	/// ```
3220	fn len(&self) -> usize;
3221
3222	/// Internal method used to define the behavior of this parallel
3223	/// iterator. You should not need to call this directly.
3224	///
3225	/// This method causes the iterator `self` to start producing
3226	/// items and to feed them to the consumer `consumer` one by one.
3227	/// It may split the consumer before doing so to create the
3228	/// opportunity to produce in parallel. If a split does happen, it
3229	/// will inform the consumer of the index where the split should
3230	/// occur (unlike `ParallelIterator::drive_unindexed()`).
3231	///
3232	/// See the [README] for more details on the internals of parallel
3233	/// iterators.
3234	///
3235	/// [README]: https://github.com/rayon-rs/rayon/blob/main/src/iter/plumbing/README.md
3236	fn drive<C: Consumer<Self::Item>>(self, consumer: C) -> C::Result;
3237
3238	/// Internal method used to define the behavior of this parallel
3239	/// iterator. You should not need to call this directly.
3240	///
3241	/// This method converts the iterator into a producer P and then
3242	/// invokes `callback.callback()` with P. Note that the type of
3243	/// this producer is not defined as part of the API, since
3244	/// `callback` must be defined generically for all producers. This
3245	/// allows the producer type to contain references; it also means
3246	/// that parallel iterators can adjust that type without causing a
3247	/// breaking change.
3248	///
3249	/// See the [README] for more details on the internals of parallel
3250	/// iterators.
3251	///
3252	/// [README]: https://github.com/rayon-rs/rayon/blob/main/src/iter/plumbing/README.md
3253	fn with_producer<CB: ProducerCallback<Self::Item>>(self, callback: CB) -> CB::Output;
3254	}
3255
3256	/// `FromParallelIterator` implements the creation of a collection
3257	/// from a [`ParallelIterator`]. By implementing
3258	/// `FromParallelIterator` for a given type, you define how it will be
3259	/// created from an iterator.
3260	///
3261	/// `FromParallelIterator` is used through [`ParallelIterator`]'s [`collect()`] method.
3262	///
3263	/// [`collect()`]: ParallelIterator::collect()
3264	///
3265	/// # Examples
3266	///
3267	/// Implementing `FromParallelIterator` for your type:
3268	///
3269	/// ```
3270	/// use rayon::prelude::*;
3271	///
3272	/// struct BlackHole {
3273	/// mass: usize,
3274	/// }
3275	///
3276	/// impl<T: Send> FromParallelIterator<T> for BlackHole {
3277	/// fn from_par_iter<I>(par_iter: I) -> Self
3278	/// where I: IntoParallelIterator<Item = T>
3279	/// {
3280	/// let par_iter = par_iter.into_par_iter();
3281	/// BlackHole {
3282	/// mass: par_iter.count() * size_of::<T>(),
3283	/// }
3284	/// }
3285	/// }
3286	///
3287	/// let bh: BlackHole = (0i32..1000).into_par_iter().collect();
3288	/// assert_eq!(bh.mass, 4000);
3289	/// ```
3290	pub trait FromParallelIterator<T>
3291	where
3292	T: Send,
3293	{
3294	/// Creates an instance of the collection from the parallel iterator `par_iter`.
3295	///
3296	/// If your collection is not naturally parallel, the easiest (and
3297	/// fastest) way to do this is often to collect `par_iter` into a
3298	/// [`LinkedList`] (via [`collect_vec_list`]) or another intermediate
3299	/// data structure and then sequentially extend your collection. However,
3300	/// a more 'native' technique is to use the [`par_iter.fold`] or
3301	/// [`par_iter.fold_with`] methods to create the collection.
3302	/// Alternatively, if your collection is 'natively' parallel, you
3303	/// can use [`par_iter.for_each`] to process each element in turn.
3304	///
3305	/// [`LinkedList`]: std::collections::LinkedList
3306	/// [`collect_vec_list`]: ParallelIterator::collect_vec_list
3307	/// [`par_iter.fold`]: ParallelIterator::fold()
3308	/// [`par_iter.fold_with`]: ParallelIterator::fold_with()
3309	/// [`par_iter.for_each`]: ParallelIterator::for_each()
3310	fn from_par_iter<I>(par_iter: I) -> Self
3311	where
3312	I: IntoParallelIterator<Item = T>;
3313	}
3314
3315	/// `ParallelExtend` extends an existing collection with items from a [`ParallelIterator`].
3316	///
3317	/// # Examples
3318	///
3319	/// Implementing `ParallelExtend` for your type:
3320	///
3321	/// ```
3322	/// use rayon::prelude::*;
3323	///
3324	/// struct BlackHole {
3325	/// mass: usize,
3326	/// }
3327	///
3328	/// impl<T: Send> ParallelExtend<T> for BlackHole {
3329	/// fn par_extend<I>(&mut self, par_iter: I)
3330	/// where I: IntoParallelIterator<Item = T>
3331	/// {
3332	/// let par_iter = par_iter.into_par_iter();
3333	/// self.mass += par_iter.count() * size_of::<T>();
3334	/// }
3335	/// }
3336	///
3337	/// let mut bh = BlackHole { mass: 0 };
3338	/// bh.par_extend(0i32..1000);
3339	/// assert_eq!(bh.mass, 4000);
3340	/// bh.par_extend(0i64..10);
3341	/// assert_eq!(bh.mass, 4080);
3342	/// ```
3343	pub trait ParallelExtend<T>
3344	where
3345	T: Send,
3346	{
3347	/// Extends an instance of the collection with the elements drawn
3348	/// from the parallel iterator `par_iter`.
3349	///
3350	/// # Examples
3351	///
3352	/// ```
3353	/// use rayon::prelude::*;
3354	///
3355	/// let mut vec = vec![];
3356	/// vec.par_extend(0..5);
3357	/// vec.par_extend((0..5).into_par_iter().map(\|i\| i * i));
3358	/// assert_eq!(vec, [0, 1, 2, 3, 4, 0, 1, 4, 9, 16]);
3359	/// ```
3360	fn par_extend<I>(&mut self, par_iter: I)
3361	where
3362	I: IntoParallelIterator<Item = T>;
3363	}
3364
3365	/// `ParallelDrainFull` creates a parallel iterator that moves all items
3366	/// from a collection while retaining the original capacity.
3367	///
3368	/// Types which are indexable typically implement [`ParallelDrainRange`]
3369	/// instead, where you can drain fully with `par_drain(..)`.
3370	pub trait ParallelDrainFull {
3371	/// The draining parallel iterator type that will be created.
3372	type Iter: ParallelIterator<Item = Self::Item>;
3373
3374	/// The type of item that the parallel iterator will produce.
3375	/// This is usually the same as `IntoParallelIterator::Item`.
3376	type Item: Send;
3377
3378	/// Returns a draining parallel iterator over an entire collection.
3379	///
3380	/// When the iterator is dropped, all items are removed, even if the
3381	/// iterator was not fully consumed. If the iterator is leaked, for example
3382	/// using `std::mem::forget`, it is unspecified how many items are removed.
3383	///
3384	/// # Examples
3385	///
3386	/// ```
3387	/// use rayon::prelude::*;
3388	/// use std::collections::{BinaryHeap, HashSet};
3389	///
3390	/// let squares: HashSet<i32> = (0..10).map(\|x\| x * x).collect();
3391	///
3392	/// let mut heap: BinaryHeap<_> = squares.iter().copied().collect();
3393	/// assert_eq!(
3394	/// // heaps are drained in arbitrary order
3395	/// heap.par_drain()
3396	/// .inspect(\|x\| assert!(squares.contains(x)))
3397	/// .count(),
3398	/// squares.len(),
3399	/// );
3400	/// assert!(heap.is_empty());
3401	/// assert!(heap.capacity() >= squares.len());
3402	/// ```
3403	fn par_drain(self) -> Self::Iter;
3404	}
3405
3406	/// `ParallelDrainRange` creates a parallel iterator that moves a range of items
3407	/// from a collection while retaining the original capacity.
3408	///
3409	/// Types which are not indexable may implement [`ParallelDrainFull`] instead.
3410	pub trait ParallelDrainRange<Idx = usize> {
3411	/// The draining parallel iterator type that will be created.
3412	type Iter: ParallelIterator<Item = Self::Item>;
3413
3414	/// The type of item that the parallel iterator will produce.
3415	/// This is usually the same as `IntoParallelIterator::Item`.
3416	type Item: Send;
3417
3418	/// Returns a draining parallel iterator over a range of the collection.
3419	///
3420	/// When the iterator is dropped, all items in the range are removed, even
3421	/// if the iterator was not fully consumed. If the iterator is leaked, for
3422	/// example using `std::mem::forget`, it is unspecified how many items are
3423	/// removed.
3424	///
3425	/// # Examples
3426	///
3427	/// ```
3428	/// use rayon::prelude::*;
3429	///
3430	/// let squares: Vec<i32> = (0..10).map(\|x\| x * x).collect();
3431	///
3432	/// println!("RangeFull");
3433	/// let mut vec = squares.clone();
3434	/// assert!(vec.par_drain(..)
3435	/// .eq(squares.par_iter().copied()));
3436	/// assert!(vec.is_empty());
3437	/// assert!(vec.capacity() >= squares.len());
3438	///
3439	/// println!("RangeFrom");
3440	/// let mut vec = squares.clone();
3441	/// assert!(vec.par_drain(5..)
3442	/// .eq(squares[5..].par_iter().copied()));
3443	/// assert_eq!(&vec[..], &squares[..5]);
3444	/// assert!(vec.capacity() >= squares.len());
3445	///
3446	/// println!("RangeTo");
3447	/// let mut vec = squares.clone();
3448	/// assert!(vec.par_drain(..5)
3449	/// .eq(squares[..5].par_iter().copied()));
3450	/// assert_eq!(&vec[..], &squares[5..]);
3451	/// assert!(vec.capacity() >= squares.len());
3452	///
3453	/// println!("RangeToInclusive");
3454	/// let mut vec = squares.clone();
3455	/// assert!(vec.par_drain(..=5)
3456	/// .eq(squares[..=5].par_iter().copied()));
3457	/// assert_eq!(&vec[..], &squares[6..]);
3458	/// assert!(vec.capacity() >= squares.len());
3459	///
3460	/// println!("Range");
3461	/// let mut vec = squares.clone();
3462	/// assert!(vec.par_drain(3..7)
3463	/// .eq(squares[3..7].par_iter().copied()));
3464	/// assert_eq!(&vec[..3], &squares[..3]);
3465	/// assert_eq!(&vec[3..], &squares[7..]);
3466	/// assert!(vec.capacity() >= squares.len());
3467	///
3468	/// println!("RangeInclusive");
3469	/// let mut vec = squares.clone();
3470	/// assert!(vec.par_drain(3..=7)
3471	/// .eq(squares[3..=7].par_iter().copied()));
3472	/// assert_eq!(&vec[..3], &squares[..3]);
3473	/// assert_eq!(&vec[3..], &squares[8..]);
3474	/// assert!(vec.capacity() >= squares.len());
3475	/// ```
3476	fn par_drain<R: RangeBounds<Idx>>(self, range: R) -> Self::Iter;
3477	}
3478
3479	/// Clone of `std::ops::Try`, until that is someday stabilized.
3480	///
3481	/// Implementing this trait is not permitted outside of `rayon`.
3482	trait Try {
3483	type Output;
3484	type Residual;
3485
3486	fn from_output(output: Self::Output) -> Self;
3487
3488	fn from_residual(residual: Self::Residual) -> Self;
3489
3490	fn branch(self) -> ControlFlow<Self::Residual, Self::Output>;
3491	}
3492
3493	impl<B, C> Try for ControlFlow<B, C> {
3494	type Output = C;
3495	type Residual = ControlFlow<B, Infallible>;
3496
3497	fn from_output(output: Self::Output) -> Self {
3498	Self::Continue(output)
3499	}
3500
3501	fn from_residual(ControlFlow::Break(b): Self::Residual) -> Self {
3502	Self::Break(b)
3503	}
3504
3505	fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
3506	self.map_break(ControlFlow::Break)
3507	}
3508	}
3509
3510	impl<T> Try for Option<T> {
3511	type Output = T;
3512	type Residual = Option<Infallible>;
3513
3514	fn from_output(output: Self::Output) -> Self {
3515	Some(output)
3516	}
3517
3518	fn from_residual(None: Self::Residual) -> Self {
3519	None
3520	}
3521
3522	fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
3523	match self {
3524	Some(c) => ControlFlow::Continue(c),
3525	None => ControlFlow::Break(None),
3526	}
3527	}
3528	}
3529
3530	impl<T, E> Try for Result<T, E> {
3531	type Output = T;
3532	type Residual = Result<Infallible, E>;
3533
3534	fn from_output(output: Self::Output) -> Self {
3535	Ok(output)
3536	}
3537
3538	fn from_residual(Err(e): Self::Residual) -> Self {
3539	Err(e)
3540	}
3541
3542	fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
3543	match self {
3544	Ok(c) => ControlFlow::Continue(c),
3545	Err(e) => ControlFlow::Break(Err(e)),
3546	}
3547	}
3548	}
3549
3550	impl<T, E> Try for Poll<Result<T, E>> {
3551	type Output = Poll<T>;
3552	type Residual = Result<Infallible, E>;
3553
3554	fn from_output(output: Self::Output) -> Self {
3555	output.map(Ok)
3556	}
3557
3558	fn from_residual(Err(e): Self::Residual) -> Self {
3559	Poll::Ready(Err(e))
3560	}
3561
3562	fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
3563	match self {
3564	Poll::Pending => ControlFlow::Continue(Poll::Pending),
3565	Poll::Ready(Ok(c)) => ControlFlow::Continue(Poll::Ready(c)),
3566	Poll::Ready(Err(e)) => ControlFlow::Break(Err(e)),
3567	}
3568	}
3569	}
3570
3571	impl<T, E> Try for Poll<Option<Result<T, E>>> {
3572	type Output = Poll<Option<T>>;
3573	type Residual = Result<Infallible, E>;
3574
3575	fn from_output(output: Self::Output) -> Self {
3576	match output {
3577	Poll::Ready(o) => Poll::Ready(o.map(Ok)),
3578	Poll::Pending => Poll::Pending,
3579	}
3580	}
3581
3582	fn from_residual(Err(e): Self::Residual) -> Self {
3583	Poll::Ready(Some(Err(e)))
3584	}
3585
3586	fn branch(self) -> ControlFlow<Self::Residual, Self::Output> {
3587	match self {
3588	Poll::Pending => ControlFlow::Continue(Poll::Pending),
3589	Poll::Ready(None) => ControlFlow::Continue(Poll::Ready(None)),
3590	Poll::Ready(Some(Ok(c))) => ControlFlow::Continue(Poll::Ready(Some(c))),
3591	Poll::Ready(Some(Err(e))) => ControlFlow::Break(Err(e)),
3592	}
3593	}
3594	}