azalea/kotlin-fork
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Provide samples for list, collection and array related functions #KT-20357

Browse Source
This commit is contained in:
Alexey Belkov
2017-10-18 01:57:38 +03:00
committed by Ilya Gorbunov
parent 97332aaeea
commit 72354559e5
7 changed files with 331 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/src/kotlin/collections/Arrays.kt
+2
View File
@@ -24,6 +24,7 @@ package kotlin.collections
/**
* Returns a single list of all elements from all arrays in the given array.
* @sample samples.collections.Arrays.Transformations.flattenArray
*/
public fun <T> Array<out Array<out T>>.flatten(): List<T> {
val result = ArrayList<T>(sumBy { it.size })
@@ -37,6 +38,7 @@ public fun <T> Array<out Array<out T>>.flatten(): List<T> {
* Returns a pair of lists, where
* *first* list is built from the first values of each pair from this array,
* *second* list is built from the second values of each pair from this array.
* @sample samples.collections.Arrays.Transformations.unzipArray
*/
public fun <T, R> Array<out Pair<T, R>>.unzip(): Pair<List<T>, List<R>> {
val listT = ArrayList<T>(size)
libraries/stdlib/src/kotlin/collections/ArraysJVM.kt
+6 -1
View File
@@ -23,11 +23,15 @@ package kotlin.collections
import java.nio.charset.Charset
/** Returns the array if it's not `null`, or an empty array otherwise. */
/**
* Returns the array if it's not `null`, or an empty array otherwise.
* @sample samples.collections.Arrays.Usage.arrayOrEmpty
*/
public inline fun <reified T> Array<out T>?.orEmpty(): Array<out T> = this ?: emptyArray<T>()
/**
* Converts the contents of this byte array to a string using the specified [charset].
* @sample samples.text.Strings.stringToByteArray
*/
@kotlin.internal.InlineOnly
public inline fun ByteArray.toString(charset: Charset): String = String(this, charset)
@@ -37,6 +41,7 @@ public inline fun ByteArray.toString(charset: Charset): String = String(this, ch
*
* Allocates an array of runtime type `T` having its size equal to the size of this collection
* and populates the array with the elements of this collection.
* @sample samples.collections.Collections.Collections.collectionToTypedArray
*/
@Suppress("UNCHECKED_CAST")
public inline fun <reified T> Collection<T>.toTypedArray(): Array<T> {
libraries/stdlib/src/kotlin/collections/Collections.kt
+59 -12
View File
@@ -73,50 +73,79 @@ private class ArrayAsCollection<T>(val values: Array<out T>, val isVarargs: Bool
public fun toArray(): Array<out Any?> = values.copyToArrayOfAny(isVarargs)
}
/** Returns an empty read-only list. The returned list is serializable (JVM). */
/**
* Returns an empty read-only list. The returned list is serializable (JVM).
* @sample samples.collections.Collections.Lists.emptyReadOnlyList
*/
public fun <T> emptyList(): List<T> = EmptyList
/** Returns a new read-only list of given elements. The returned list is serializable (JVM). */
/**
* Returns a new read-only list of given elements. The returned list is serializable (JVM).
* @sample samples.collections.Collections.Lists.readOnlyList
*/
public fun <T> listOf(vararg elements: T): List<T> = if (elements.size > 0) elements.asList() else emptyList()
/** Returns an empty read-only list. The returned list is serializable (JVM). */
/**
* Returns an empty read-only list. The returned list is serializable (JVM).
* @sample samples.collections.Collections.Lists.emptyReadOnlyList
*/
@kotlin.internal.InlineOnly
public inline fun <T> listOf(): List<T> = emptyList()
/**
* Returns an immutable list containing only the specified object [element].
* The returned list is serializable.
* @sample samples.collections.Collections.Lists.singletonReadOnlyList
*/
@JvmVersion
public fun <T> listOf(element: T): List<T> = java.util.Collections.singletonList(element)
/** Returns an empty new [MutableList]. */
/**
* Returns an empty new [MutableList].
* @sample samples.collections.Collections.Lists.emptyMutableList
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
public inline fun <T> mutableListOf(): MutableList<T> = ArrayList()
/** Returns an empty new [ArrayList]. */
/**
* Returns an empty new [ArrayList].
* @sample samples.collections.Collections.Lists.emptyArrayList
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
public inline fun <T> arrayListOf(): ArrayList<T> = ArrayList()
/** Returns a new [MutableList] with the given elements. */
/**
* Returns a new [MutableList] with the given elements.
* @sample samples.collections.Collections.Lists.mutableList
*/
public fun <T> mutableListOf(vararg elements: T): MutableList<T>
= if (elements.size == 0) ArrayList() else ArrayList(ArrayAsCollection(elements, isVarargs = true))
/** Returns a new [ArrayList] with the given elements. */
/**
* Returns a new [ArrayList] with the given elements.
* @sample samples.collections.Collections.Lists.arrayList
*/
public fun <T> arrayListOf(vararg elements: T): ArrayList<T>
= if (elements.size == 0) ArrayList() else ArrayList(ArrayAsCollection(elements, isVarargs = true))
/** Returns a new read-only list either of single given element, if it is not null, or empty list it the element is null. The returned list is serializable (JVM). */
/**
* Returns a new read-only list either of single given element, if it is not null, or empty list if the element is null. The returned list is serializable (JVM).
* @sample samples.collections.Collections.Lists.singletonListOfNotNull
*/
public fun <T : Any> listOfNotNull(element: T?): List<T> = if (element != null) listOf(element) else emptyList()
/** Returns a new read-only list only of those given elements, that are not null. The returned list is serializable (JVM). */
/**
* Returns a new read-only list only of those given elements, that are not null. The returned list is serializable (JVM).
* @sample samples.collections.Collections.Lists.listOfNotNull
*/
public fun <T : Any> listOfNotNull(vararg elements: T?): List<T> = elements.filterNotNull()
/**
* Creates a new read-only list with the specified [size], where each element is calculated by calling the specified
* [init] function. The [init] function returns a list element given its index.
* @sample samples.collections.Collections.Lists.readOnlyListFromInitializer
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -125,6 +154,7 @@ public inline fun <T> List(size: Int, init: (index: Int) -> T): List<T> = Mutabl
/**
* Creates a new mutable list with the specified [size], where each element is calculated by calling the specified
* [init] function. The [init] function returns a list element given its index.
* @sample samples.collections.Collections.Lists.mutableListFromInitializer
*/
@SinceKotlin("1.1")
@kotlin.internal.InlineOnly
@@ -136,6 +166,7 @@ public inline fun <T> MutableList(size: Int, init: (index: Int) -> T): MutableLi
/**
* Returns an [IntRange] of the valid indices for this collection.
* @sample samples.collections.Collections.Collections.indicesOfCollection
*/
public val Collection<*>.indices: IntRange
get() = 0..size - 1
@@ -148,21 +179,31 @@ public val Collection<*>.indices: IntRange
public val <T> List<T>.lastIndex: Int
get() = this.size - 1
/** Returns `true` if the collection is not empty. */
/**
* Returns `true` if the collection is not empty.
* @sample samples.collections.Collections.Collections.collectionIsNotEmpty
*/
@kotlin.internal.InlineOnly
public inline fun <T> Collection<T>.isNotEmpty(): Boolean = !isEmpty()
/** Returns this Collection if it's not `null` and the empty list otherwise. */
/**
* Returns this Collection if it's not `null` and the empty list otherwise.
* @sample samples.collections.Collections.Collections.collectionOrEmpty
*/
@kotlin.internal.InlineOnly
public inline fun <T> Collection<T>?.orEmpty(): Collection<T> = this ?: emptyList()
/** Returns this List if it's not `null` and the empty list otherwise. */
/**
* Returns this List if it's not `null` and the empty list otherwise.
* @sample samples.collections.Collections.Lists.listOrEmpty
*/
@kotlin.internal.InlineOnly
public inline fun <T> List<T>?.orEmpty(): List<T> = this ?: emptyList()
/**
* Returns a list containing the elements returned by this enumeration
* in the order they are returned by the enumeration.
* @sample samples.collections.Collections.Lists.enumerationToList
*/
@JvmVersion
@kotlin.internal.InlineOnly
@@ -172,6 +213,7 @@ public inline fun <T> java.util.Enumeration<T>.toList(): List<T> = java.util.Col
* Checks if all elements in the specified collection are contained in this collection.
*
* Allows to overcome type-safety restriction of `containsAll` that requires to pass a collection of type `Collection<E>`.
* @sample samples.collections.Collections.Collections.collectionContainsAll
*/
@Suppress("EXTENSION_SHADOWED_BY_MEMBER") // false warning, extension takes precedence in some cases
@kotlin.internal.InlineOnly
@@ -215,6 +257,8 @@ private fun <T> Array<out T>.copyToArrayOfAny(isVarargs: Boolean): Array<Any?> =
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
* @sample samples.collections.Collections.Lists.binarySearchOnComparable
* @sample samples.collections.Collections.Lists.binarySearchWithBoundaries
*/
public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int = 0, toIndex: Int = size): Int {
rangeCheck(size, fromIndex, toIndex)
@@ -250,6 +294,7 @@ public fun <T: Comparable<T>> List<T?>.binarySearch(element: T?, fromIndex: Int
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted according to the specified [comparator].
* @sample samples.collections.Collections.Lists.binarySearchWithComparator
*/
public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fromIndex: Int = 0, toIndex: Int = size): Int {
rangeCheck(size, fromIndex, toIndex)
@@ -286,6 +331,7 @@ public fun <T> List<T>.binarySearch(element: T, comparator: Comparator<in T>, fr
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
* @sample samples.collections.Collections.Lists.binarySearchByKey
*/
public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromIndex: Int = 0, toIndex: Int = size, crossinline selector: (T) -> K?): Int =
binarySearch(fromIndex, toIndex) { compareValues(selector(it), key) }
@@ -308,6 +354,7 @@ public inline fun <T, K : Comparable<K>> List<T>.binarySearchBy(key: K?, fromInd
* otherwise, the inverted insertion point `(-insertion point - 1)`.
* The insertion point is defined as the index at which the element should be inserted,
* so that the list (or the specified subrange of list) still remains sorted.
* @sample samples.collections.Collections.Lists.binarySearchWithComparisonFunction
*/
public fun <T> List<T>.binarySearch(fromIndex: Int = 0, toIndex: Int = size, comparison: (T) -> Int): Int {
rangeCheck(size, fromIndex, toIndex)
libraries/stdlib/src/kotlin/text/StringsJVM.kt
+1
View File
@@ -367,6 +367,7 @@ public inline fun String.toUpperCase(locale: java.util.Locale): String = (this a
/**
* Encodes the contents of this string using the specified character set and returns the resulting byte array.
* @sample samples.text.Strings.stringToByteArray
*/
@kotlin.internal.InlineOnly
public inline fun String.toByteArray(charset: Charset = Charsets.UTF_8): ByteArray = (this as java.lang.String).getBytes(charset)