diff --git a/libraries/stdlib/js-ir/build.gradle b/libraries/stdlib/js-ir/build.gradle index b5819322f0a..88a0a0b2c09 100644 --- a/libraries/stdlib/js-ir/build.gradle +++ b/libraries/stdlib/js-ir/build.gradle @@ -21,7 +21,6 @@ task prepareNativeBuiltinsSources(type: Sync) { include "Array.kt" include "Boolean.kt" include "CharSequence.kt" - include "Collections.kt" include "Comparable.kt" include "Coroutines.kt" include "Iterator.kt" diff --git a/libraries/stdlib/js-ir/builtins/Collections.kt b/libraries/stdlib/js-ir/builtins/Collections.kt new file mode 100644 index 00000000000..1e8adc446fc --- /dev/null +++ b/libraries/stdlib/js-ir/builtins/Collections.kt @@ -0,0 +1,430 @@ +@file:Suppress( + "NON_ABSTRACT_FUNCTION_WITH_NO_BODY", + "MUST_BE_INITIALIZED_OR_BE_ABSTRACT", + "EXTERNAL_TYPE_EXTENDS_NON_EXTERNAL_TYPE", + "PRIMARY_CONSTRUCTOR_DELEGATION_CALL_EXPECTED", + "WRONG_MODIFIER_TARGET" +) +/* + * 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 + +/** + * 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? + + // 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? + + // 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 + } +}