@@ -969,6 +969,54 @@ const impl<T: [const] Destruct> Drop for Guard<'_, T> {
969969 }
970970}
971971
972+ /// Panic guard for incremental initialization of arrays from the back.
973+ ///
974+ /// Elements of the array are populated starting from the end towards the beginning.
975+ /// Disarm the guard with `mem:: forget` once the array has been fully initialized.
976+ ///
977+ /// # Safety
978+ ///
979+ /// All write accesses to this structure are unsafe and must maintain a correct
980+ /// count of `initialized` elements.
981+ struct GuardBack <' a, T > {
982+ /// The array to be initialized (will be filled from the end).
983+ pub array_mut: & ' a mut [ MaybeUninit <T >] ,
984+ /// The number of items that have been initialized so far.
985+ pub initialized: usize,
986+ }
987+
988+ impl<T > GuardBack <' _, T > {
989+ /// Adds an item to the array and updates the initialized item counter.
990+ ///
991+ /// # Safety
992+ ///
993+ /// No more than N elements must be initialized.
994+ #[ inline]
995+ pub ( crate ) unsafe fn push_unchecked ( & mut self , item : T ) {
996+ // SAFETY: If `initialized` was correct before and the caller does not
997+ // invoke this method more than N times, then writes will be in-bounds
998+ // and slots will not be initialized more than once.
999+ unsafe {
1000+ let offset = self . initialized . unchecked_add ( 1 ) ;
1001+ let index = self . array_mut . len ( ) . unchecked_sub ( offset) ;
1002+ self . array_mut . get_unchecked_mut ( index) . write ( item) ;
1003+ self . initialized = offset;
1004+ }
1005+ }
1006+ }
1007+
1008+ impl < T : Destruct > Drop for GuardBack < ' _ , T > {
1009+ #[ inline]
1010+ fn drop ( & mut self ) {
1011+ debug_assert ! ( self . initialized <= self . array_mut. len( ) ) ;
1012+ let len = self . array_mut . len ( ) ;
1013+ // SAFETY: this slice will contain only initialized objects.
1014+ unsafe {
1015+ self . array_mut . get_unchecked_mut ( len - self . initialized ..len) . assume_init_drop ( ) ;
1016+ }
1017+ }
1018+ }
1019+
9721020/// Pulls `N` items from `iter` and returns them as an array. If the iterator
9731021/// yields fewer than `N` items, `Err` is returned containing an iterator over
9741022/// the already yielded items.
@@ -1076,3 +1124,109 @@ const fn iter_next_chunk_erased<T>(
10761124 mem:: forget ( guard) ;
10771125 Ok ( ( ) )
10781126}
1127+
1128+ /// Pulls `N` items from the back of `iter` and returns them as an array.
1129+ /// If the iterator yields fewer than `N` items, `Err` is returned containing
1130+ /// an iterator over the already yielded items.
1131+ ///
1132+ /// Since the iterator is passed as a mutable reference and this function calls
1133+ /// `next_back` at most `N` times, the iterator can still be used afterwards to
1134+ /// retrieve the remaining items.
1135+ ///
1136+ /// If `iter.next_back()` panics, all items already yielded by the iterator are
1137+ /// dropped.
1138+ ///
1139+ /// Used for [`DoubleEndedIterator::next_chunk_back`].
1140+ #[ inline]
1141+ pub ( crate ) fn iter_next_chunk_back < T , const N : usize > (
1142+ iter : & mut impl DoubleEndedIterator < Item = T > ,
1143+ ) -> Result < [ T ; N ] , IntoIter < T , N > > {
1144+ iter. spec_next_chunk_back ( )
1145+ }
1146+
1147+ pub ( crate ) trait SpecNextChunkBack < T , const N : usize > :
1148+ DoubleEndedIterator < Item = T >
1149+ {
1150+ fn spec_next_chunk_back ( & mut self ) -> Result < [ T ; N ] , IntoIter < T , N > > ;
1151+ }
1152+
1153+ impl < I : DoubleEndedIterator < Item = T > , T , const N : usize > SpecNextChunkBack < T , N > for I {
1154+ #[ inline]
1155+ default fn spec_next_chunk_back ( & mut self ) -> Result < [ T ; N ] , IntoIter < T , N > > {
1156+ let mut array = [ const { MaybeUninit :: uninit ( ) } ; N ] ;
1157+ let r = iter_next_chunk_back_erased ( & mut array, self ) ;
1158+ match r {
1159+ Ok ( ( ) ) => {
1160+ // SAFETY: All elements of `array` were populated.
1161+ Ok ( unsafe { MaybeUninit :: array_assume_init ( array) } )
1162+ }
1163+ Err ( initialized) => {
1164+ // SAFETY: Only the last `initialized` elements were populated
1165+ Err ( unsafe { IntoIter :: new_unchecked ( array, N - initialized..N ) } )
1166+ }
1167+ }
1168+ }
1169+ }
1170+
1171+ impl < I : DoubleEndedIterator < Item = T > + TrustedLen , T , const N : usize > SpecNextChunkBack < T , N >
1172+ for I
1173+ {
1174+ fn spec_next_chunk_back ( & mut self ) -> Result < [ T ; N ] , IntoIter < T , N > > {
1175+ let len = ( * self ) . size_hint ( ) . 0 ;
1176+ let mut array = [ const { MaybeUninit :: uninit ( ) } ; N ] ;
1177+ if len < N {
1178+ // SAFETY: `TrustedLen`, an unsafe trait, requires that i can get len items out of it.
1179+ unsafe { write_back ( & mut array, self , len) } ;
1180+ // SAFETY: Only the last `len` elements were populated
1181+ Err ( unsafe { IntoIter :: new_unchecked ( array, N - len..N ) } )
1182+ } else {
1183+ // SAFETY: `TrustedLen`, an unsafe trait, requires that i can get N items out of it.
1184+ unsafe { write_back ( & mut array, self , N ) } ;
1185+ // SAFETY: All N items were populated
1186+ Ok ( unsafe { MaybeUninit :: array_assume_init ( array) } )
1187+ }
1188+ }
1189+ }
1190+
1191+ // SAFETY: `from` must have len items, and len items must be < N.
1192+ unsafe fn write_back < T , const N : usize > (
1193+ to : & mut [ MaybeUninit < T > ; N ] ,
1194+ from : & mut impl DoubleEndedIterator < Item = T > ,
1195+ len : usize ,
1196+ ) {
1197+ let mut guard = GuardBack { array_mut : to, initialized : 0 } ;
1198+ while guard. initialized < len {
1199+ // SAFETY: caller has guaranteed, from has len items.
1200+ let item = unsafe { from. next_back ( ) . unwrap_unchecked ( ) } ;
1201+ // SAFETY: guard.initialized < len < N
1202+ unsafe { guard. push_unchecked ( item) } ;
1203+ }
1204+ crate :: mem:: forget ( guard) ;
1205+ }
1206+
1207+ /// Version of [`iter_next_chunk_back`] using a passed-in slice
1208+ /// in order to avoid needing to monomorphize for every array length.
1209+ ///
1210+ /// Unfortunately this loop has two exit conditions, the buffer filling up
1211+ /// or the iterator running out of items, making it tend to optimize poorly.
1212+ #[ inline]
1213+ fn iter_next_chunk_back_erased < T > (
1214+ buffer : & mut [ MaybeUninit < T > ] ,
1215+ iter : & mut impl DoubleEndedIterator < Item = T > ,
1216+ ) -> Result < ( ) , usize > {
1217+ // if `Iterator::next_back` panics, this guard will drop already initialized items
1218+ let mut guard = GuardBack { array_mut : buffer, initialized : 0 } ;
1219+ while guard. initialized < guard. array_mut . len ( ) {
1220+ let Some ( item) = iter. next_back ( ) else {
1221+ let initialized = guard. initialized ;
1222+ mem:: forget ( guard) ;
1223+ return Err ( initialized) ;
1224+ } ;
1225+
1226+ // SAFETY: The loop condition ensures we have space to push the item
1227+ unsafe { guard. push_unchecked ( item) } ;
1228+ }
1229+
1230+ mem:: forget ( guard) ;
1231+ Ok ( ( ) )
1232+ }
0 commit comments