kotlin-stdlib/kotlin.collections/ArrayList/ensureCapacity

ensureCapacity

expect fun ensureCapacity(minCapacity: Int)(source)

Ensures that the capacity of this list is at least equal to the specified minCapacity.

If the current capacity is less than the minCapacity, a new backing storage is allocated with greater capacity. Otherwise, this method takes no action and simply returns.

This operation can be used to minimize the number of incremental reallocations when the eventual size of the list is known in advance, improving performance when adding many elements.

On the JS target, this method has no effect due to the internal JS implementation.

Since Kotlin

1.0

Parameters

minCapacity

the desired minimum capacity.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Suppose we have an existing list with unknown current capacity
val list = arrayListOf(1, 2, 3, 4, 5)

// When we know in advance that we'll add many elements,
// we can pre-allocate capacity to avoid multiple reallocations
val elementsToAdd = 1000
list.ensureCapacity(list.size + elementsToAdd)

// Now adding elements won't trigger internal array resizing
// until we exceed the ensured capacity
for (i in 1..elementsToAdd) {
    list.add(i)
}

assertEquals(1005, list.size)
assertEquals(1, list.first())
assertEquals(1000, list.last()) 
   //sampleEnd
}
actual fun ensureCapacity(minCapacity: Int)(source)

Does nothing in this ArrayList implementation.

Since Kotlin

1.1
actual fun ensureCapacity(minCapacity: Int)(source)

Ensures that the capacity of this list is at least equal to the specified minCapacity.

If the current capacity is less than the minCapacity, a new backing storage is allocated with greater capacity. Otherwise, this method takes no action and simply returns.

This operation can be used to minimize the number of incremental reallocations when the eventual size of the list is known in advance, improving performance when adding many elements.

Since Kotlin

1.3

Parameters

minCapacity

the desired minimum capacity.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Suppose we have an existing list with unknown current capacity
val list = arrayListOf(1, 2, 3, 4, 5)

// When we know in advance that we'll add many elements,
// we can pre-allocate capacity to avoid multiple reallocations
val elementsToAdd = 1000
list.ensureCapacity(list.size + elementsToAdd)

// Now adding elements won't trigger internal array resizing
// until we exceed the ensured capacity
for (i in 1..elementsToAdd) {
    list.add(i)
}

assertEquals(1005, list.size)
assertEquals(1, list.first())
assertEquals(1000, list.last()) 
   //sampleEnd
}
actual fun ensureCapacity(minCapacity: Int)(source)

Ensures that the capacity of this list is at least equal to the specified minCapacity.

If the current capacity is less than the minCapacity, a new backing storage is allocated with greater capacity. Otherwise, this method takes no action and simply returns.

This operation can be used to minimize the number of incremental reallocations when the eventual size of the list is known in advance, improving performance when adding many elements.

Since Kotlin

1.8

Parameters

minCapacity

the desired minimum capacity.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Suppose we have an existing list with unknown current capacity
val list = arrayListOf(1, 2, 3, 4, 5)

// When we know in advance that we'll add many elements,
// we can pre-allocate capacity to avoid multiple reallocations
val elementsToAdd = 1000
list.ensureCapacity(list.size + elementsToAdd)

// Now adding elements won't trigger internal array resizing
// until we exceed the ensured capacity
for (i in 1..elementsToAdd) {
    list.add(i)
}

assertEquals(1005, list.size)
assertEquals(1, list.first())
assertEquals(1000, list.last()) 
   //sampleEnd
}
actual fun ensureCapacity(minCapacity: Int)(source)

Ensures that the capacity of this list is at least equal to the specified minCapacity.

If the current capacity is less than the minCapacity, a new backing storage is allocated with greater capacity. Otherwise, this method takes no action and simply returns.

This operation can be used to minimize the number of incremental reallocations when the eventual size of the list is known in advance, improving performance when adding many elements.

Since Kotlin

1.8

Parameters

minCapacity

the desired minimum capacity.

Samples

import kotlin.math.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Suppose we have an existing list with unknown current capacity
val list = arrayListOf(1, 2, 3, 4, 5)

// When we know in advance that we'll add many elements,
// we can pre-allocate capacity to avoid multiple reallocations
val elementsToAdd = 1000
list.ensureCapacity(list.size + elementsToAdd)

// Now adding elements won't trigger internal array resizing
// until we exceed the ensured capacity
for (i in 1..elementsToAdd) {
    list.add(i)
}

assertEquals(1005, list.size)
assertEquals(1, list.first())
assertEquals(1000, list.last()) 
   //sampleEnd
}