Collection operations overview
The Kotlin standard library offers a broad variety of functions for performing operations on collections. This includes simple operations, such as getting or adding elements, as well as more complex ones including search, sorting, filtering, transformations, and so on.
Extension and member functions
Member functions define operations that are essential for a collection type. For example,
Collection contains the function
isEmpty() for checking its emptiness;
get() for index access to elements, and so on.
When you create your own implementations of collection interfaces, you must implement their member functions. To make the creation of new implementations easier, use the skeletal implementations of collection interfaces from the standard library:
AbstractMap, and their mutable counterparts.
Other collection operations are declared as extension functions. These are filtering, transformation, ordering, and other collection processing functions.
Common operations are available for both read-only and mutable collections. Common operations fall into these groups:
- Retrieving collection parts
- Retrieving single elements
- Aggregate operations
Operations described on these pages return their results without affecting the original collection. For example, a filtering operation produces a new collection that contains all the elements matching the filtering predicate. Results of such operations should be either stored in variables, or used in some other way, for example, passed in other functions.
For certain collection operations, there is an option to specify the destination object. Destination is a mutable collection to which the function appends its resulting items instead of returning them in a new object. For performing operations with destinations, there are separate functions with the
To postfix in their names, for example,
filterTo() instead of
associateTo() instead of
associate(). These functions take the destination collection as an additional parameter.
For convenience, these functions return the destination collection back, so you can create it right in the corresponding argument of the function call:
Functions with destination are available for filtering, association, grouping, flattening, and other operations. For the complete list of destination operations see the Kotlin collections reference.
For mutable collections, there are also write operations that change the collection state. Such operations include adding, removing, and updating elements. Write operations are listed in the Write operations and corresponding sections of List-specific operations and Map specific operations.
For certain operations, there are pairs of functions for performing the same operation: one applies the operation in-place and the other returns the result as a separate collection. For example,
sort() sorts a mutable collection in-place, so its state changes;
sorted() creates a new collection that contains the same elements in the sorted order.