jvmMain.kotlin.Collections.kt Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of kotlin-stdlib Show documentation
Show all versions of kotlin-stdlib Show documentation
Kotlin Standard Library for JVM
/*
* Copyright 2010-2024 JetBrains s.r.o. and Kotlin Programming Language contributors.
* Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
*/
package kotlin.collections
import kotlin.internal.PlatformDependent
/**
* Classes that inherit from this interface can be represented as a sequence of elements that can
* be iterated over.
* @param T the type of element being iterated over. The iterator is covariant in its element type.
*/
public actual interface Iterable {
/**
* Returns an iterator over the elements of this object.
*/
public actual operator fun iterator(): Iterator
}
/**
* Classes that inherit from this interface can be represented as a sequence of elements that can
* be iterated over and that supports removing elements during iteration.
* @param T the type of element being iterated over. The mutable iterator is invariant in its element type.
*/
public actual interface MutableIterable : Iterable {
/**
* Returns an iterator over the elements of this sequence that supports removing elements during iteration.
*/
actual override fun iterator(): MutableIterator
}
/**
* A generic collection of elements. Methods in this interface support only read-only access to the collection;
* read/write access is supported through the [MutableCollection] interface.
* @param E the type of elements contained in the collection. The collection is covariant in its element type.
*/
public actual interface Collection : Iterable {
// Query Operations
/**
* Returns the size of the collection.
*/
public actual val size: Int
/**
* Returns `true` if the collection is empty (contains no elements), `false` otherwise.
*/
public actual fun isEmpty(): Boolean
/**
* Checks if the specified element is contained in this collection.
*/
public actual operator fun contains(element: @UnsafeVariance E): Boolean
actual override fun iterator(): Iterator
// Bulk Operations
/**
* Checks if all elements in the specified collection are contained in this collection.
*/
public actual fun containsAll(elements: Collection<@UnsafeVariance E>): Boolean
}
/**
* A generic collection of elements that supports adding and removing elements.
*
* @param E the type of elements contained in the collection. The mutable collection is invariant in its element type.
*/
public actual interface MutableCollection : Collection, MutableIterable {
// Query Operations
actual override fun iterator(): MutableIterator
// Modification Operations
/**
* Adds the specified element to the collection.
*
* @return `true` if the element has been added, `false` if the collection does not support duplicates
* and the element is already contained in the collection.
*/
public actual fun add(element: E): Boolean
/**
* Removes a single instance of the specified element from this
* collection, if it is present.
*
* @return `true` if the element has been successfully removed; `false` if it was not present in the collection.
*/
public actual fun remove(element: E): Boolean
// Bulk Modification Operations
/**
* Adds all of the elements of the specified collection to this collection.
*
* @return `true` if any of the specified elements was added to the collection, `false` if the collection was not modified.
*/
public actual fun addAll(elements: Collection): Boolean
/**
* Removes all of this collection's elements that are also contained in the specified collection.
*
* @return `true` if any of the specified elements was removed from the collection, `false` if the collection was not modified.
*/
public actual fun removeAll(elements: Collection): Boolean
/**
* Retains only the elements in this collection that are contained in the specified collection.
*
* @return `true` if any element was removed from the collection, `false` if the collection was not modified.
*/
public actual fun retainAll(elements: Collection): Boolean
/**
* Removes all elements from this collection.
*/
public actual fun clear(): Unit
}
/**
* A generic ordered collection of elements. Methods in this interface support only read-only access to the list;
* read/write access is supported through the [MutableList] interface.
* @param E the type of elements contained in the list. The list is covariant in its element type.
*/
public actual interface List : Collection {
// Query Operations
actual override val size: Int
actual override fun isEmpty(): Boolean
actual override fun contains(element: @UnsafeVariance E): Boolean
actual override fun iterator(): Iterator
// Bulk Operations
actual override fun containsAll(elements: Collection<@UnsafeVariance E>): Boolean
// Positional Access Operations
/**
* Returns the element at the specified index in the list.
*/
public actual operator fun get(index: Int): E
// Search Operations
/**
* Returns the index of the first occurrence of the specified element in the list, or -1 if the specified
* element is not contained in the list.
*/
public actual fun indexOf(element: @UnsafeVariance E): Int
/**
* Returns the index of the last occurrence of the specified element in the list, or -1 if the specified
* element is not contained in the list.
*/
public actual fun lastIndexOf(element: @UnsafeVariance E): Int
// List Iterators
/**
* Returns a list iterator over the elements in this list (in proper sequence).
*/
public actual fun listIterator(): ListIterator
/**
* Returns a list iterator over the elements in this list (in proper sequence), starting at the specified [index].
*/
public actual fun listIterator(index: Int): ListIterator
// View
/**
* Returns a view of the portion of this list between the specified [fromIndex] (inclusive) and [toIndex] (exclusive).
* The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa.
*
* Structural changes in the base list make the behavior of the view undefined.
*/
public actual fun subList(fromIndex: Int, toIndex: Int): List
}
/**
* A generic ordered collection of elements that supports adding and removing elements.
* @param E the type of elements contained in the list. The mutable list is invariant in its element type.
*/
public actual interface MutableList : List, MutableCollection {
// Modification Operations
/**
* Adds the specified element to the end of this list.
*
* @return `true` because the list is always modified as the result of this operation.
*/
actual override fun add(element: E): Boolean
actual override fun remove(element: E): Boolean
// Bulk Modification Operations
/**
* Adds all of the elements of the specified collection to the end of this list.
*
* The elements are appended in the order they appear in the [elements] collection.
*
* @return `true` if the list was changed as the result of the operation.
*/
override fun addAll(elements: Collection): Boolean
/**
* Inserts all of the elements of the specified collection [elements] into this list at the specified [index].
*
* @return `true` if the list was changed as the result of the operation.
*/
public actual fun addAll(index: Int, elements: Collection): Boolean
actual override fun removeAll(elements: Collection): Boolean
actual override fun retainAll(elements: Collection): Boolean
actual override fun clear(): Unit
// Positional Access Operations
/**
* Replaces the element at the specified position in this list with the specified element.
*
* @return the element previously at the specified position.
*/
public actual operator fun set(index: Int, element: E): E
/**
* Inserts an element into the list at the specified [index].
*/
public actual fun add(index: Int, element: E): Unit
/**
* Removes an element at the specified [index] from the list.
*
* @return the element that has been removed.
*/
public actual fun removeAt(index: Int): E
// List Iterators
actual override fun listIterator(): MutableListIterator
actual override fun listIterator(index: Int): MutableListIterator
// View
actual override fun subList(fromIndex: Int, toIndex: Int): MutableList
}
/**
* A generic unordered collection of elements that does not support duplicate elements.
* Methods in this interface support only read-only access to the set;
* read/write access is supported through the [MutableSet] interface.
* @param E the type of elements contained in the set. The set is covariant in its element type.
*/
public actual interface Set : Collection {
// Query Operations
actual override val size: Int
actual override fun isEmpty(): Boolean
actual override fun contains(element: @UnsafeVariance E): Boolean
actual override fun iterator(): Iterator
// Bulk Operations
actual override fun containsAll(elements: Collection<@UnsafeVariance E>): Boolean
}
/**
* A generic unordered collection of elements that does not support duplicate elements, and supports
* adding and removing elements.
* @param E the type of elements contained in the set. The mutable set is invariant in its element type.
*/
public actual interface MutableSet : Set, MutableCollection {
// Query Operations
actual override fun iterator(): MutableIterator
// Modification Operations
/**
* Adds the specified element to the set.
*
* @return `true` if the element has been added, `false` if the element is already contained in the set.
*/
actual override fun add(element: E): Boolean
actual override fun remove(element: E): Boolean
// Bulk Modification Operations
actual override fun addAll(elements: Collection): Boolean
actual override fun removeAll(elements: Collection): Boolean
actual override fun retainAll(elements: Collection): Boolean
actual override fun clear(): Unit
}
/**
* A collection that holds pairs of objects (keys and values) and supports efficiently retrieving
* the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
* Methods in this interface support only read-only access to the map; read-write access is supported through
* the [MutableMap] interface.
* @param K the type of map keys. The map is invariant in its key type, as it
* can accept key as a parameter (of [containsKey] for example) and return it in [keys] set.
* @param V the type of map values. The map is covariant in its value type.
*/
public actual interface Map {
// Query Operations
/**
* Returns the number of key/value pairs in the map.
*/
public actual val size: Int
/**
* Returns `true` if the map is empty (contains no elements), `false` otherwise.
*/
public actual fun isEmpty(): Boolean
/**
* Returns `true` if the map contains the specified [key].
*/
public actual fun containsKey(key: K): Boolean
/**
* Returns `true` if the map maps one or more keys to the specified [value].
*/
public actual fun containsValue(value: @UnsafeVariance V): Boolean
/**
* Returns the value corresponding to the given [key], or `null` if such a key is not present in the map.
*/
public actual operator fun get(key: K): V?
/**
* Returns the value corresponding to the given [key], or [defaultValue] if such a key is not present in the map.
*
* @since JDK 1.8
*/
@SinceKotlin("1.1")
@PlatformDependent
public actual fun getOrDefault(key: K, defaultValue: @UnsafeVariance V): V {
// See default implementation in JDK sources
throw NotImplementedError()
}
// Views
/**
* Returns a read-only [Set] of all keys in this map.
*/
public actual val keys: Set
/**
* Returns a read-only [Collection] of all values in this map. Note that this collection may contain duplicate values.
*/
public actual val values: Collection
/**
* Returns a read-only [Set] of all key/value pairs in this map.
*/
public actual val entries: Set>
/**
* Represents a key/value pair held by a [Map].
*
* Map entries are not supposed to be stored separately or used long after they are obtained.
* The behavior of an entry is undefined if the backing map has been modified after the entry was obtained.
*/
public actual interface Entry {
/**
* Returns the key of this key/value pair.
*/
public actual val key: K
/**
* Returns the value of this key/value pair.
*/
public actual val value: V
}
}
/**
* A modifiable collection that holds pairs of objects (keys and values) and supports efficiently retrieving
* the value corresponding to each key. Map keys are unique; the map holds only one value for each key.
* @param K the type of map keys. The map is invariant in its key type.
* @param V the type of map values. The mutable map is invariant in its value type.
*/
public actual interface MutableMap : Map {
// Modification Operations
/**
* Associates the specified [value] with the specified [key] in the map.
*
* @return the previous value associated with the key, or `null` if the key was not present in the map.
*/
public actual fun put(key: K, value: V): V?
/**
* Removes the specified key and its corresponding value from this map.
*
* @return the previous value associated with the key, or `null` if the key was not present in the map.
*/
public actual fun remove(key: K): V?
/**
* Removes the entry for the specified key only if it is mapped to the specified value.
*
* @return true if entry was removed
*/
@SinceKotlin("1.1")
@PlatformDependent
public actual fun remove(key: K, value: V): Boolean {
// See default implementation in JDK sources
return true
}
// Bulk Modification Operations
/**
* Updates this map with key/value pairs from the specified map [from].
*/
public actual fun putAll(from: Map): Unit
/**
* Removes all elements from this map.
*/
public actual fun clear(): Unit
// Views
/**
* Returns a [MutableSet] of all keys in this map.
*/
actual override val keys: MutableSet
/**
* Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
*/
actual override val values: MutableCollection
/**
* Returns a [MutableSet] of all key/value pairs in this map.
*/
actual override val entries: MutableSet>
/**
* Represents a key/value pair held by a [MutableMap].
*
* Map entries are not supposed to be stored separately or used long after they are obtained.
* The behavior of an entry is undefined if the backing map has been modified after the entry was obtained.
*/
public actual interface MutableEntry : Map.Entry {
/**
* Changes the value associated with the key of this entry.
*
* @return the previous value corresponding to the key.
*/
public actual fun setValue(newValue: V): V
}
}