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

Improve documentation of collection constructors #KT-59192

Browse Source
This commit is contained in:
Abduqodiri Qurbonzoda
2023-06-08 15:25:01 +03:00
committed by Space Team
parent 2f7ae074f0
commit 0bef1533e2
13 changed files with 366 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files
libraries/stdlib/common/src/kotlin/collections/ArrayList.kt
+23
View File
@@ -6,8 +6,31 @@
package kotlin.collections
expect class ArrayList<E> : MutableList<E>, RandomAccess {
/**
* Creates a new empty [ArrayList].
*/
constructor()
/**
* Creates a new empty [ArrayList] with the specified initial capacity.
*
* Capacity is the maximum number of elements the list is able to store in current backing storage.
* When the list gets full and a new element can't be added, its capacity is expanded,
* which usually leads to creation of a bigger backing storage.
*
* @param initialCapacity the initial capacity of the created list.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
constructor(initialCapacity: Int)
/**
* Creates a new [ArrayList] filled with the elements of the specified collection.
*
* The iteration order of elements in the created list is the same as in the specified collection.
*/
constructor(elements: Collection<E>)
fun trimToSize()
libraries/stdlib/common/src/kotlin/collections/HashMap.kt
+35
View File
@@ -6,9 +6,44 @@
package kotlin.collections
expect class HashMap<K, V> : MutableMap<K, V> {
/**
* Creates a new empty [HashMap].
*/
constructor()
/**
* Creates a new empty [HashMap] with the specified initial capacity.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* When the map gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
constructor(initialCapacity: Int)
/**
* Creates a new empty [HashMap] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* Load factor is the measure of how full the map is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
constructor(initialCapacity: Int, loadFactor: Float)
/**
* Creates a new [HashMap] filled with the contents of the specified [original] map.
*/
constructor(original: Map<out K, V>)
// From Map
libraries/stdlib/common/src/kotlin/collections/HashSet.kt
+35
View File
@@ -6,9 +6,44 @@
package kotlin.collections
expect class HashSet<E> : MutableSet<E> {
/**
* Creates a new empty [HashSet].
*/
constructor()
/**
* Creates a new empty [HashSet] with the specified initial capacity.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* When the set gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
constructor(initialCapacity: Int)
/**
* Creates a new empty [HashSet] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* Load factor is the measure of how full the set is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
constructor(initialCapacity: Int, loadFactor: Float)
/**
* Creates a new [HashSet] filled with the elements of the specified collection.
*/
constructor(elements: Collection<E>)
// From Set
libraries/stdlib/common/src/kotlin/collections/LinkedHashMap.kt
+37
View File
@@ -6,9 +6,46 @@
package kotlin.collections
expect class LinkedHashMap<K, V> : MutableMap<K, V> {
/**
* Creates a new empty [LinkedHashMap].
*/
constructor()
/**
* Creates a new empty [LinkedHashMap] with the specified initial capacity.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* When the map gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
constructor(initialCapacity: Int)
/**
* Creates a new empty [LinkedHashMap] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* Load factor is the measure of how full the map is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
constructor(initialCapacity: Int, loadFactor: Float)
/**
* Creates a new [LinkedHashMap] filled with the contents of the specified [original] map.
*
* The iteration order of entries in the created map is the same as in the [original] map.
*/
constructor(original: Map<out K, V>)
// From Map
libraries/stdlib/common/src/kotlin/collections/LinkedHashSet.kt
+37
View File
@@ -6,9 +6,46 @@
package kotlin.collections
expect class LinkedHashSet<E> : MutableSet<E> {
/**
* Creates a new empty [LinkedHashSet].
*/
constructor()
/**
* Creates a new empty [LinkedHashSet] with the specified initial capacity.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* When the set gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
constructor(initialCapacity: Int)
/**
* Creates a new empty [LinkedHashSet] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* Load factor is the measure of how full the set is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
constructor(initialCapacity: Int, loadFactor: Float)
/**
* Creates a new [LinkedHashSet] filled with the elements of the specified collection.
*
* The iteration order of elements in the created set is the same as in the specified collection.
*/
constructor(elements: Collection<E>)
// From Set
libraries/stdlib/js/src/kotlin/collections/ArrayList.kt
+14 -4
View File
@@ -20,18 +20,28 @@ public actual open class ArrayList<E> internal constructor(private var array: Ar
private var isReadOnly: Boolean = false
/**
* Creates an empty [ArrayList].
* Creates a new empty [ArrayList].
*/
public actual constructor() : this(emptyArray()) {}
/**
* Creates an empty [ArrayList].
* @param initialCapacity initial capacity (ignored)
* Creates a new empty [ArrayList] with the specified initial capacity.
*
* Capacity is the maximum number of elements the list is able to store in current backing storage.
* When the list gets full and a new element can't be added, its capacity is expanded,
* which usually leads to creation of a bigger backing storage.
*
* @param initialCapacity the initial capacity of the created list.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
public actual constructor(initialCapacity: Int) : this(emptyArray()) {}
/**
* Creates an [ArrayList] filled from the [elements] collection.
* Creates a new [ArrayList] filled with the elements of the specified collection.
*
* The iteration order of elements in the created list is the same as in the specified collection.
*/
public actual constructor(elements: Collection<E>) : this(elements.toTypedArray<Any?>()) {}
libraries/stdlib/js/src/kotlin/collections/HashMap.kt
+25 -7
View File
@@ -57,29 +57,47 @@ public actual open class HashMap<K, V> : AbstractMutableMap<K, V>, MutableMap<K,
}
/**
* Constructs an empty [HashMap] instance.
* Creates a new empty [HashMap].
*/
actual constructor() : this(InternalHashCodeMap(EqualityComparator.HashCode))
/**
* Constructs an empty [HashMap] instance.
* Creates a new empty [HashMap] with the specified initial capacity and load factor.
*
* @param initialCapacity the initial capacity (ignored)
* @param loadFactor the load factor (ignored)
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* Load factor is the measure of how full the map is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @throws IllegalArgumentException if the initial capacity or load factor are negative
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) : this() {
// This implementation of HashMap has no need of load factors or capacities.
require(initialCapacity >= 0) { "Negative initial capacity: $initialCapacity" }
require(loadFactor >= 0) { "Non-positive load factor: $loadFactor" }
require(loadFactor > 0) { "Non-positive load factor: $loadFactor" }
}
/**
* Creates a new empty [HashMap] with the specified initial capacity.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* When the map gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(initialCapacity, 0.0f)
/**
* Constructs an instance of [HashMap] filled with the contents of the specified [original] map.
* Creates a new [HashMap] filled with the contents of the specified [original] map.
*/
actual constructor(original: Map<out K, V>) : this() {
this.putAll(original)
libraries/stdlib/js/src/kotlin/collections/HashSet.kt
+24 -6
View File
@@ -19,14 +19,14 @@ public actual open class HashSet<E> : AbstractMutableSet<E>, MutableSet<E> {
internal val map: HashMap<E, Any>
/**
* Constructs a new empty [HashSet].
* Creates a new empty [HashSet].
*/
actual constructor() {
map = HashMap<E, Any>()
}
/**
* Constructs a new [HashSet] filled with the elements of the specified collection.
* Creates a new [HashSet] filled with the elements of the specified collection.
*/
actual constructor(elements: Collection<E>) {
map = HashMap<E, Any>(elements.size)
@@ -34,17 +34,35 @@ public actual open class HashSet<E> : AbstractMutableSet<E>, MutableSet<E> {
}
/**
* Constructs a new empty [HashSet].
* Creates a new empty [HashSet] with the specified initial capacity and load factor.
*
* @param initialCapacity the initial capacity (ignored)
* @param loadFactor the load factor (ignored)
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* Load factor is the measure of how full the set is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @throws IllegalArgumentException if the initial capacity or load factor are negative
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) {
map = HashMap<E, Any>(initialCapacity, loadFactor)
}
/**
* Creates a new empty [HashSet] with the specified initial capacity.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* When the set gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(initialCapacity, 0.0f)
/**
libraries/stdlib/js/src/kotlin/collections/LinkedHashMap.kt
+26 -6
View File
@@ -170,7 +170,7 @@ public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
private var isReadOnly: Boolean = false
/**
* Constructs an empty [LinkedHashMap] instance.
* Creates a new empty [LinkedHashMap].
*/
actual constructor() : super() {
map = HashMap<K, ChainEntry<K, V>>()
@@ -182,21 +182,41 @@ public actual open class LinkedHashMap<K, V> : HashMap<K, V>, MutableMap<K, V> {
}
/**
* Constructs an empty [LinkedHashMap] instance.
* Creates a new empty [LinkedHashMap] with the specified initial capacity and load factor.
*
* @param initialCapacity the initial capacity (ignored)
* @param loadFactor the load factor (ignored)
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* Load factor is the measure of how full the map is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @throws IllegalArgumentException if the initial capacity or load factor are negative
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) : super(initialCapacity, loadFactor) {
map = HashMap<K, ChainEntry<K, V>>()
}
/**
* Creates a new empty [LinkedHashMap] with the specified initial capacity.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* When the map gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(initialCapacity, 0.0f)
/**
* Constructs an instance of [LinkedHashMap] filled with the contents of the specified [original] map.
* Creates a new [LinkedHashMap] filled with the contents of the specified [original] map.
*
* The iteration order of entries in the created map is the same as in the [original] map.
*/
actual constructor(original: Map<out K, V>) {
map = HashMap<K, ChainEntry<K, V>>()
libraries/stdlib/js/src/kotlin/collections/LinkedHashSet.kt
+26 -6
View File
@@ -24,27 +24,47 @@ public actual open class LinkedHashSet<E> : HashSet<E>, MutableSet<E> {
internal constructor(map: LinkedHashMap<E, Any>) : super(map)
/**
* Constructs a new empty [LinkedHashSet].
* Creates a new empty [LinkedHashSet].
*/
actual constructor() : super(LinkedHashMap<E, Any>())
/**
* Constructs a new [LinkedHashSet] filled with the elements of the specified collection.
* Creates a new [LinkedHashSet] filled with the elements of the specified collection.
*
* The iteration order of elements in the created set is the same as in the specified collection.
*/
actual constructor(elements: Collection<E>) : super(LinkedHashMap<E, Any>()) {
addAll(elements)
}
/**
* Constructs a new empty [LinkedHashSet].
* Creates a new empty [LinkedHashSet] with the specified initial capacity and load factor.
*
* @param initialCapacity the initial capacity (ignored)
* @param loadFactor the load factor (ignored)
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* Load factor is the measure of how full the set is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @throws IllegalArgumentException if the initial capacity or load factor are negative
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) : super(LinkedHashMap<E, Any>(initialCapacity, loadFactor))
/**
* Creates a new empty [LinkedHashSet] with the specified initial capacity.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* When the set gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(initialCapacity, 0.0f)
@PublishedApi
libraries/stdlib/native-wasm/src/kotlin/collections/ArrayList.kt
+20
View File
@@ -17,11 +17,31 @@ actual class ArrayList<E> private constructor(
private val Empty = ArrayList<Nothing>(0).also { it.isReadOnly = true }
}
/**
* Creates a new empty [ArrayList].
*/
actual constructor() : this(10)
/**
* Creates a new empty [ArrayList] with the specified initial capacity.
*
* Capacity is the maximum number of elements the list is able to store in current backing storage.
* When the list gets full and a new element can't be added, its capacity is expanded,
* which usually leads to creation of a bigger backing storage.
*
* @param initialCapacity the initial capacity of the created list.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(
arrayOfUninitializedElements(initialCapacity), 0, 0, false, null, null)
/**
* Creates a new [ArrayList] filled with the elements of the specified collection.
*
* The iteration order of elements in the created list is the same as in the specified collection.
*/
actual constructor(elements: Collection<E>) : this(elements.size) {
addAll(elements)
}
libraries/stdlib/native-wasm/src/kotlin/collections/HashMap.kt
+32 -1
View File
@@ -31,8 +31,23 @@ actual class HashMap<K, V> private constructor(
// ---------------------------- functions ----------------------------
/**
* Creates a new empty [HashMap].
*/
actual constructor() : this(INITIAL_CAPACITY)
/**
* Creates a new empty [HashMap] with the specified initial capacity.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* When the map gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(
arrayOfUninitializedElements(initialCapacity),
null,
@@ -41,11 +56,27 @@ actual class HashMap<K, V> private constructor(
INITIAL_MAX_PROBE_DISTANCE,
0)
/**
* Creates a new [HashMap] filled with the contents of the specified [original] map.
*/
actual constructor(original: Map<out K, V>) : this(original.size) {
putAll(original)
}
// This implementation doesn't use a loadFactor, this constructor is used for compatibility with common stdlib
/**
* Creates a new empty [HashMap] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of entries the map is able to store in current internal data structure.
* Load factor is the measure of how full the map is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created map.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) : this(initialCapacity)
@PublishedApi
libraries/stdlib/native-wasm/src/kotlin/collections/HashSet.kt
+32 -1
View File
@@ -12,15 +12,46 @@ actual class HashSet<E> internal constructor(
private val Empty = HashSet(HashMap.EmptyHolder.value<Nothing, Nothing>())
}
/**
* Creates a new empty [HashSet].
*/
actual constructor() : this(HashMap<E, Nothing>())
/**
* Creates a new empty [HashSet] with the specified initial capacity.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* When the set gets full by a certain default load factor, its capacity is expanded,
* which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative.
*/
actual constructor(initialCapacity: Int) : this(HashMap<E, Nothing>(initialCapacity))
/**
* Creates a new [HashSet] filled with the elements of the specified collection.
*/
actual constructor(elements: Collection<E>) : this(elements.size) {
addAll(elements)
}
// This implementation doesn't use a loadFactor
/**
* Creates a new empty [HashSet] with the specified initial capacity and load factor.
*
* Capacity is the maximum number of elements the set is able to store in current internal data structure.
* Load factor is the measure of how full the set is allowed to get in relation to
* its capacity before the capacity is expanded, which usually leads to rebuild of the internal data structure.
*
* @param initialCapacity the initial capacity of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
* @param loadFactor the load factor of the created set.
* Note that the argument is just a hint for the implementation and can be ignored.
*
* @throws IllegalArgumentException if [initialCapacity] is negative or [loadFactor] is non-positive.
*/
actual constructor(initialCapacity: Int, loadFactor: Float) : this(initialCapacity)
@PublishedApi