Remove 'nearly_stateless' category, do not mention statefulness for terminal operations.

#KT-16994
2017-03-22 21:45:10 +03:00
parent 4018db680e
commit c98c2d9931
9 changed files with 84 additions and 86 deletions
@@ -93,8 +93,8 @@ and extension functions for sequences.

 The sequence operations can be classified into the following groups regarding their state requirements:

- - _stateless_ – operations like [kotlin.sequences.Sequence.map], [kotlin.sequences.Sequence.filter], which process each element independently;
- - _nearly stateless_ – operations which require a small constant amount of state to process an element, for example [kotlin.sequences.Sequence.take] or [kotlin.sequences.Sequence.drop];
+ - _stateless_ – operations which require no state and process each element independently like [kotlin.sequences.Sequence.map], [kotlin.sequences.Sequence.filter],
+   or require a small constant amount of state to process an element, for example [kotlin.sequences.Sequence.take] or [kotlin.sequences.Sequence.drop];
 - _stateful_ – operations which require a significant amount of state, usually proportional to the number of elements in a sequence.
 
 If the sequence operation returns another sequence, which is produced lazily, it's called _intermediate_, and otherwise the operation is _terminal_.
@@ -329,7 +329,7 @@ public inline fun <T> Sequence<T>.singleOrNull(predicate: (T) -> Boolean): T? {
 /**
 * Returns a sequence containing all elements except first [n] elements.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T> Sequence<T>.drop(n: Int): Sequence<T> {
    require(n >= 0) { "Requested element count $n is less than zero." }
@@ -363,7 +363,7 @@ public fun <T> Sequence<T>.filter(predicate: (T) -> Boolean): Sequence<T> {
 * @param [predicate] function that takes the index of an element and the element itself
 * and returns the result of predicate evaluation on the element.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T> Sequence<T>.filterIndexed(predicate: (index: Int, T) -> Boolean): Sequence<T> {
    // TODO: Rewrite with generalized MapFilterIndexingSequence
@@ -375,7 +375,7 @@ public fun <T> Sequence<T>.filterIndexed(predicate: (index: Int, T) -> Boolean):
 * @param [predicate] function that takes the index of an element and the element itself
 * and returns the result of predicate evaluation on the element.
 *
- * The operation is _terminal_ and _nearly stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterIndexedTo(destination: C, predicate: (index: Int, T) -> Boolean): C {
    forEachIndexed { index, element ->
@@ -397,7 +397,7 @@ public inline fun <reified R> Sequence<*>.filterIsInstance(): Sequence<@kotlin.i
 /**
 * Appends all elements that are instances of specified type parameter R to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <reified R, C : MutableCollection<in R>> Sequence<*>.filterIsInstanceTo(destination: C): C {
    for (element in this) if (element is R) destination.add(element)
@@ -426,7 +426,7 @@ public fun <T : Any> Sequence<T?>.filterNotNull(): Sequence<T> {
 /**
 * Appends all elements that are not `null` to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public fun <C : MutableCollection<in T>, T : Any> Sequence<T?>.filterNotNullTo(destination: C): C {
    for (element in this) if (element != null) destination.add(element)
@@ -436,7 +436,7 @@ public fun <C : MutableCollection<in T>, T : Any> Sequence<T?>.filterNotNullTo(d
 /**
 * Appends all elements not matching the given [predicate] to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterNotTo(destination: C, predicate: (T) -> Boolean): C {
    for (element in this) if (!predicate(element)) destination.add(element)
@@ -446,7 +446,7 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterNotTo(desti
 /**
 * Appends all elements matching the given [predicate] to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destination: C, predicate: (T) -> Boolean): C {
    for (element in this) if (predicate(element)) destination.add(element)
@@ -456,7 +456,7 @@ public inline fun <T, C : MutableCollection<in T>> Sequence<T>.filterTo(destinat
 /**
 * Returns a sequence containing first [n] elements.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T> Sequence<T>.take(n: Int): Sequence<T> {
    require(n >= 0) { "Requested element count $n is less than zero." }
@@ -705,7 +705,7 @@ public fun <T, R> Sequence<T>.flatMap(transform: (T) -> Sequence<R>): Sequence<R
 /**
 * Appends all elements yielded from results of [transform] function being invoked on each element of original sequence, to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.flatMapTo(destination: C, transform: (T) -> Sequence<R>): C {
    for (element in this) {
@@ -723,7 +723,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.flatMapTo(dest
 * 
 * @sample samples.collections.Collections.Transformations.groupBy
 *
- * The operation is _terminal_ and _stateful_.
+ * The operation is _terminal_.
 */
 public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List<T>> {
    return groupByTo(LinkedHashMap<K, MutableList<T>>(), keySelector)
@@ -738,7 +738,7 @@ public inline fun <T, K> Sequence<T>.groupBy(keySelector: (T) -> K): Map<K, List
 * 
 * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
 *
- * The operation is _terminal_ and _stateful_.
+ * The operation is _terminal_.
 */
 public inline fun <T, K, V> Sequence<T>.groupBy(keySelector: (T) -> K, valueTransform: (T) -> V): Map<K, List<V>> {
    return groupByTo(LinkedHashMap<K, MutableList<V>>(), keySelector, valueTransform)
@@ -752,7 +752,7 @@ public inline fun <T, K, V> Sequence<T>.groupBy(keySelector: (T) -> K, valueTran
 * 
 * @sample samples.collections.Collections.Transformations.groupBy
 *
- * The operation is _terminal_ and _stateful_.
+ * The operation is _terminal_.
 */
 public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Sequence<T>.groupByTo(destination: M, keySelector: (T) -> K): M {
    for (element in this) {
@@ -772,7 +772,7 @@ public inline fun <T, K, M : MutableMap<in K, MutableList<T>>> Sequence<T>.group
 * 
 * @sample samples.collections.Collections.Transformations.groupByKeysAndValues
 *
- * The operation is _terminal_ and _stateful_.
+ * The operation is _terminal_.
 */
 public inline fun <T, K, V, M : MutableMap<in K, MutableList<V>>> Sequence<T>.groupByTo(destination: M, keySelector: (T) -> K, valueTransform: (T) -> V): M {
    for (element in this) {
@@ -815,7 +815,7 @@ public fun <T, R> Sequence<T>.map(transform: (T) -> R): Sequence<R> {
 * @param [transform] function that takes the index of an element and the element itself
 * and returns the result of the transform applied to the element.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T, R> Sequence<T>.mapIndexed(transform: (index: Int, T) -> R): Sequence<R> {
    return TransformingIndexedSequence(this, transform)
@@ -827,7 +827,7 @@ public fun <T, R> Sequence<T>.mapIndexed(transform: (index: Int, T) -> R): Seque
 * @param [transform] function that takes the index of an element and the element itself
 * and returns the result of the transform applied to the element.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T, R : Any> Sequence<T>.mapIndexedNotNull(transform: (index: Int, T) -> R?): Sequence<R> {
    return TransformingIndexedSequence(this, transform).filterNotNull()
@@ -839,7 +839,7 @@ public fun <T, R : Any> Sequence<T>.mapIndexedNotNull(transform: (index: Int, T)
 * @param [transform] function that takes the index of an element and the element itself
 * and returns the result of the transform applied to the element.
 *
- * The operation is _terminal_ and _nearly stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, R : Any, C : MutableCollection<in R>> Sequence<T>.mapIndexedNotNullTo(destination: C, transform: (index: Int, T) -> R?): C {
    forEachIndexed { index, element -> transform(index, element)?.let { destination.add(it) } }
@@ -852,7 +852,7 @@ public inline fun <T, R : Any, C : MutableCollection<in R>> Sequence<T>.mapIndex
 * @param [transform] function that takes the index of an element and the element itself
 * and returns the result of the transform applied to the element.
 *
- * The operation is _terminal_ and _nearly stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.mapIndexedTo(destination: C, transform: (index: Int, T) -> R): C {
    var index = 0
@@ -875,7 +875,7 @@ public fun <T, R : Any> Sequence<T>.mapNotNull(transform: (T) -> R?): Sequence<R
 * Applies the given [transform] function to each element in the original sequence
 * and appends only the non-null results to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, R : Any, C : MutableCollection<in R>> Sequence<T>.mapNotNullTo(destination: C, transform: (T) -> R?): C {
    forEach { element -> transform(element)?.let { destination.add(it) } }
@@ -886,7 +886,7 @@ public inline fun <T, R : Any, C : MutableCollection<in R>> Sequence<T>.mapNotNu
 * Applies the given [transform] function to each element of the original sequence
 * and appends the results to the given [destination].
 *
- * The operation is _terminal_ and _stateless_.
+ * The operation is _terminal_.
 */
 public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.mapTo(destination: C, transform: (T) -> R): C {
    for (item in this)
@@ -897,7 +897,7 @@ public inline fun <T, R, C : MutableCollection<in R>> Sequence<T>.mapTo(destinat
 /**
 * Returns a sequence of [IndexedValue] for each element of the original sequence.
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public fun <T> Sequence<T>.withIndex(): Sequence<IndexedValue<T>> {
    return IndexingSequence(this)
@@ -1333,7 +1333,7 @@ public fun <T : Any> Sequence<T?>.requireNoNulls(): Sequence<T> {
 /**
 * Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element].
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
 public operator fun <T> Sequence<T>.minus(element: T): Sequence<T> {
    return object: Sequence<T> {
@@ -1405,7 +1405,7 @@ public operator fun <T> Sequence<T>.minus(elements: Sequence<T>): Sequence<T> {
 /**
 * Returns a sequence containing all elements of the original sequence without the first occurrence of the given [element].
 *
- * The operation is _intermediate_ and _nearly stateless_.
+ * The operation is _intermediate_ and _stateless_.
 */
@kotlin.internal.InlineOnly
 public inline fun <T> Sequence<T>.minusElement(element: T): Sequence<T> {