Deprecate IndexingIterable and IndexingIterator and provide Iterator.withIndex() instead of the latter.

libraries/stdlib/src/kotlin/collections/IndexingIterator.kt

@@ -12,6 +12,7 @@ public data class IndexedValue<out T>(public val index: Int, public val value: T
  * A wrapper over another [Iterable] (or any other object that can produce an [Iterator]) that returns
  * an indexing iterator.
  */
+@Deprecated("This implementation class will become internal soon. Use Iterable<IndexedValue<T>> instead.", ReplaceWith("Iterable<IndexedValue<T>>"))
 public class IndexingIterable<out T>(private val iteratorFactory: () -> Iterator<T>) : Iterable<IndexedValue<T>> {
     override fun iterator(): Iterator<IndexedValue<T>> = IndexingIterator(iteratorFactory())
 }
@@ -19,7 +20,10 @@ public class IndexingIterable<out T>(private val iteratorFactory: () -> Iterator
 /**
  * Iterator transforming original `iterator` into iterator of [IndexedValue], counting index from zero.
  */
-public class IndexingIterator<out T>(private val iterator: Iterator<T>) : Iterator<IndexedValue<T>> {
+@Deprecated("This implementation class will become internal soon. Use Iterator<IndexedValue<T>> instead.", ReplaceWith("Iterator<IndexedValue<T>>"))
+public class IndexingIterator<out T>
+@Deprecated("This implementation class will become internal soon. Use iterator.withIndex() instead.", ReplaceWith("iterator.withIndex()"))
+constructor(private val iterator: Iterator<T>) : Iterator<IndexedValue<T>> {
     private var index = 0
     final override fun hasNext(): Boolean = iterator.hasNext()
     final override fun next(): IndexedValue<T> = IndexedValue(index++, iterator.next())

libraries/stdlib/src/kotlin/collections/Iterators.kt

@@ -19,6 +19,12 @@ public operator fun <T> Enumeration<T>.iterator(): Iterator<T> = object : Iterat
  */
 public operator fun <T> Iterator<T>.iterator(): Iterator<T> = this
 
+/**
+ * Returns an [Iterator] wrapping each value produced by this [Iterator] with the [IndexedValue],
+ * containing value and it's index.
+ */
+public fun <T> Iterator<T>.withIndex(): Iterator<IndexedValue<T>> = IndexingIterator(this)
+
 /**
  * Performs the given [operation] on each element of this [Iterator].
  */