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-2015 JetBrains s.r.o.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
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 on its element type.
*/
public interface Iterable {
/**
* Returns an iterator over the elements of this object.
*/
public 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 on its element type.
*/
public interface MutableIterable : Iterable {
/**
* Returns an iterator over the elements of this sequence that supports removing elements during iteration.
*/
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 on its element type.
*/
public interface Collection : Iterable {
// Query Operations
/**
* Returns the size of the collection.
*/
public val size: Int
/**
* Returns `true` if the collection is empty (contains no elements), `false` otherwise.
*/
public fun isEmpty(): Boolean
/**
* Checks if the specified element is contained in this collection.
*/
public operator fun contains(element: @UnsafeVariance E): Boolean
override fun iterator(): Iterator
// Bulk Operations
/**
* Checks if all elements in the specified collection are contained in this collection.
*/
public 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 on its element type.
*/
public interface MutableCollection : Collection, MutableIterable {
// Query Operations
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 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 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 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 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 fun retainAll(elements: Collection): Boolean
/**
* Removes all elements from this collection.
*/
public 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 on its element type.
*/
public interface List : Collection {
// Query Operations
override val size: Int
override fun isEmpty(): Boolean
override fun contains(element: @UnsafeVariance E): Boolean
override fun iterator(): Iterator
// Bulk Operations
override fun containsAll(elements: Collection<@UnsafeVariance E>): Boolean
// Positional Access Operations
/**
* Returns the element at the specified index in the list.
*/
public 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 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 fun lastIndexOf(element: @UnsafeVariance E): Int
// List Iterators
/**
* Returns a list iterator over the elements in this list (in proper sequence).
*/
public fun listIterator(): ListIterator
/**
* Returns a list iterator over the elements in this list (in proper sequence), starting at the specified [index].
*/
public 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 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 on its element type.
*/
public 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.
*/
override fun add(element: E): Boolean
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 fun addAll(index: Int, elements: Collection): Boolean
override fun removeAll(elements: Collection): Boolean
override fun retainAll(elements: Collection): Boolean
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 operator fun set(index: Int, element: E): E
/**
* Inserts an element into the list at the specified [index].
*/
public 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 fun removeAt(index: Int): E
// List Iterators
override fun listIterator(): MutableListIterator
override fun listIterator(index: Int): MutableListIterator
// View
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 on its element type.
*/
public interface Set : Collection {
// Query Operations
override val size: Int
override fun isEmpty(): Boolean
override fun contains(element: @UnsafeVariance E): Boolean
override fun iterator(): Iterator
// Bulk Operations
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 on its element type.
*/
public interface MutableSet : Set, MutableCollection {
// Query Operations
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.
*/
override fun add(element: E): Boolean
override fun remove(element: E): Boolean
// Bulk Modification Operations
override fun addAll(elements: Collection): Boolean
override fun removeAll(elements: Collection): Boolean
override fun retainAll(elements: Collection): Boolean
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 on 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 on its value type.
*/
public interface Map {
// Query Operations
/**
* Returns the number of key/value pairs in the map.
*/
public val size: Int
/**
* Returns `true` if the map is empty (contains no elements), `false` otherwise.
*/
public fun isEmpty(): Boolean
/**
* Returns `true` if the map contains the specified [key].
*/
public fun containsKey(key: K): Boolean
/**
* Returns `true` if the map maps one or more keys to the specified [value].
*/
public 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 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 fun getOrDefault(key: K, defaultValue: @UnsafeVariance V): V {
// See default implementation in JDK sources
return null as V
}
// Views
/**
* Returns a read-only [Set] of all keys in this map.
*/
public val keys: Set
/**
* Returns a read-only [Collection] of all values in this map. Note that this collection may contain duplicate values.
*/
public val values: Collection
/**
* Returns a read-only [Set] of all key/value pairs in this map.
*/
public val entries: Set>
/**
* Represents a key/value pair held by a [Map].
*/
public interface Entry {
/**
* Returns the key of this key/value pair.
*/
public val key: K
/**
* Returns the value of this key/value pair.
*/
public 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 on its key type.
* @param V the type of map values. The mutable map is invariant on its value type.
*/
public 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 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 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 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 fun putAll(from: Map): Unit
/**
* Removes all elements from this map.
*/
public fun clear(): Unit
// Views
/**
* Returns a [MutableSet] of all keys in this map.
*/
override val keys: MutableSet
/**
* Returns a [MutableCollection] of all values in this map. Note that this collection may contain duplicate values.
*/
override val values: MutableCollection
/**
* Returns a [MutableSet] of all key/value pairs in this map.
*/
override val entries: MutableSet>
/**
* Represents a key/value pair held by a [MutableMap].
*/
public interface MutableEntry : Map.Entry {
/**
* Changes the value associated with the key of this entry.
*
* @return the previous value corresponding to the key.
*/
public fun setValue(newValue: V): V
}
}