Collection

Reduce the memory impact of existing and new collections that are small.

Latest Update	Stable Release	Release Candidate	Beta Release	Alpha Release
December 11, 2024	1.4.5	-	1.5.0-beta01	-

Declaring dependencies

To add a dependency on Collection, you must add the Google Maven repository to your project. Read Google's Maven repository for more information.

Add the dependencies for the artifacts you need in the build.gradle file for your app or module:

Groovy

dependencies {
    def collection_version = "1.4.5"
    implementation "androidx.collection:collection:$collection_version"
}

Kotlin

dependencies {
    val collection_version = "1.4.5"
    implementation("androidx.collection:collection:$collection_version")
}

For more information about dependencies, see Add Build Dependencies.

Feedback

Your feedback helps make Jetpack better. Let us know if you discover new issues or have ideas for improving this library. Please take a look at the existing issues in this library before you create a new one. You can add your vote to an existing issue by clicking the star button.

Create a new issue

See the Issue Tracker documentation for more information.

Version 1.5

Version 1.5.0-beta01

December 11, 2024

androidx.collection:collection-*:1.5.0-beta01 is released. Version 1.5.0-beta01 contains these commits.

API Changes

Adds support for watchosDeviceArm64 KMP target and target kotlin 1.9 (Icf15d, b/364652024)

Version 1.5.0-alpha06

November 13, 2024

androidx.collection:collection-*:1.5.0-alpha06 is released. Version 1.5.0-alpha06 contains these commits.

Bug Fixes

Fixed a crash that could occur in SieveCache and OrderedScatterSet when adding numerous items causing repeated key collisions. (Iaaf3d, b/375607736)
Add wasm target to collection library. (I66fe3, b/352722444)

Version 1.5.0-alpha05

October 30, 2024

androidx.collection:collection-*:1.5.0-alpha05 is released. Version 1.5.0-alpha05 contains these commits.

Version 1.5.0-alpha04

October 16, 2024

androidx.collection:collection-*:1.5.0-alpha04 is released. Version 1.5.0-alpha04 contains these commits.

Version 1.5.0-alpha03

October 2, 2024

androidx.collection:collection-*:1.5.0-alpha03 is released. Version 1.5.0-alpha03 contains these commits.

API Changes

Kotlin version update to 1.9 (I1a14c)

External Contribution

Forward contains to containsKey. Thanks Jake Wharton! (I9362b)
Add container builders for scalar-specialized collections. Thanks Jake Wharton! (I13179)

Version 1.5.0-alpha02

September 18, 2024

androidx.collection:collection-*:1.5.0-alpha02 is released. Version 1.5.0-alpha02 contains these commits.

API Changes

Adds support for watchosDeviceArm64 platform target. (I1cc04, b/364652024)

Version 1.5.0-alpha01

September 4, 2024

androidx.collection:collection-*:1.5.0-alpha01 is released. Version 1.5.0-alpha01 contains these commits.

API Changes

OrderedScatterSet is a new ordered, allocation-free collection (Ic4178)
SieveCache is a new allocation-free replacement for LruCache that offers better hit ratio characteristics. (I50a17)
Exposed the packedValue internal representation for IntIntPair and FloatFloatPair. (Ifeb75, b/331853566)
Adding access to the content array in list collections. (I899d5, b/333903173)
Add DoubleList, a List-like data structure optimized for Double values. (Ia10d1, b/315127635)

Bug Fixes

Collections library is moving to target Kotlin 1.9 (I0782f)
Optimize many of the collections to be more efficient. (Ic0566)

Version 1.4

Version 1.4.5

October 30, 2024

androidx.collection:collection-*:1.4.5 is released. Version 1.4.5 contains these commits.

Version 1.4.4

September 18, 2024

androidx.collection:collection-*:1.4.4 is released. Version 1.4.4 contains these commits.

Bug Fixes

Workaround ArrayIndexOutOfBounds when sorting an empty collection. (I65245)

Version 1.4.3

August 7, 2024

androidx.collection:collection-*:1.4.3 is released. Version 1.4.3 contains these commits.

Bug Fixes

Fixed a corruption that could happen in ScatterMap, ScatterSet, and their primitive variants. (I38a4a, b/352560465)
Performance optimizations. In particular:
- Replace calls to check() and required() with variants that don't inline exception throws. This reduces the final binary size and more importantly relieves i-cache pressure a little bit.
- Improved removeDeletedMarkers() in the "scatter" family of collections. The new version clears deleted markers 8 markers at a time and skips more expensive writes in the process. (Ic0566)

Version 1.4.2

July 24, 2024

androidx.collection:collection-*:1.4.2 is released. Version 1.4.2 contains these commits.

New Features

Includes additional Kotlin Multiplatform targets: watchos, tvos, linuxArm64. (b/352543988)

Version 1.4.1

July 10, 2024

androidx.collection:collection-*:1.4.1 is released. Version 1.4.1 contains these commits.

Bug Fixes

Remove deleted tombstones from Map/Set when resizing. (7a996c5, b/345960092)

Version 1.4.0

January 24, 2024

androidx.collection:collection-*:1.4.0 is released. Version 1.4.0 contains these commits.

Important changes since 1.3.0

New high-efficiency collections for storing primitives without boxing have been added:

MutableScatterMap & ScatterMap - Classes with MutableMap & Map-like API
MutableScatterSet & ScatterSet - Classes with MutableSet & Set-like API
MutableObjectList & ObjectList - Classes with MutableList & List-like API

For example, a map with an integer key and a reference type value is an IntObjectMap<T>. A map with a long key and a float value is a LongFloatMap. There is no version with the name ObjectObjectMap because that is covered by ScatterMap/MutableScatterMap.

Version 1.4.0-rc01

January 10, 2024

androidx.collection:collection-*:1.4.0-rc01 is released with no changes. Version 1.4.0-rc01 contains these commits.

Version 1.4.0-beta02

November 29, 2023

androidx.collection:collection-*:1.4.0-beta02 is released. Version 1.4.0-beta02 contains these commits.

New Features

Improved performance of FloatFloatPair. (If5537)

Bug Fixes

ScatterMap.asMap() iterator now return new instances (I28932, b/310365754)

Version 1.4.0-beta01

November 15, 2023

androidx.collection:collection-*:1.4.0-beta01 is released. Version 1.4.0-beta01 contains these commits.

Bug Fixes

Fix for ListIterator incorrectly setting values in ObjectList that could result in a crash due to IndexOutOfBoundsException. (I3bd8a, b/307049391)

Version 1.4.0-alpha02

October 18, 2023

androidx.collection:collection-*:1.4.0-alpha02 is released. Version 1.4.0-alpha02 contains these commits.

API Changes

Added overload for put that returns the previous value when it is replaced to all primitive collections, such as FloatFloatMap.
Convert removeIf methods on primitive collections, such as MutableFloatFloatMap to inline. This ensures that the lambda for removeIf is not allocated.

Version 1.4.0-alpha01

October 4, 2023

androidx.collection:collection-*:1.4.0-alpha01 is released. Version 1.4.0-alpha01 contains these commits.

New Features

New high-efficiency collections have been added that have low allocation overhead and high performance:

MutableScatterMap & ScatterMap - Classes with MutableMap & Map-like API
MutableScatterSet & ScatterSet - Classes with MutableSet & Set-like API
MutableObjectList & ObjectList - Classes with MutableList & List-like API

New high-efficiency collections for storing primitives without boxing have been added:

Mutable[Int|Float|Long]List - Classes with MutableList<Int|Float|Long>-like API. The read-only [Int|Float|Long]List also exists. For example, integers can be held in an IntList.
Mutable[Int|Float|Long]Set - Classes with MutableSet<Int|Float|Long>-like API. The read-only [Int|Float|Long]Set also exists. For example, integers can be held in an IntSet.
Mutable[Int|Float|Long|Object][Int|Float|Long|Object]Map - Classes with Mutable<Int|Float|Long,T, Int|Float|Long|T>-like API. The read-only [Int|Float|Long|Object][Int|Float|Long|Object]Map also exists. For example, a map with an integer key and a reference type value is an IntObjectMap<T>. A map with a long key and a float value is a LongFloatMap. There is no version with the name ObjectObjectMap because that is covered by ScatterMap/MutableScatterMap.

Version 1.3.0

October 4, 2023

androidx.collection:collection-*:1.3.0 is released. Version 1.3.0 contains these commits.

Important changes since 1.2.0

You can now use Collections in Kotlin Multiplatform projects. Note that non-Android targets of Collections are still experimental, but we decided to merge versions to make it easier for developers to try them.
All of the source has been migrated to Kotlin. As part of this change, many APIs are now properly typed for nullity and a few package private members have become internal. A list of exact changes are available in the minor release notes for 1.3.x below.
Along with the Kotlin migration, collection-ktx has been merged with the main collection artifact. You can safely drop any dependencies on collection:collection-ktx in favor of collection:collection as collection-ktx is now empty.

Version 1.3.0-rc01

September 6, 2023

androidx.collection:collection-*:1.3.0-rc01 is released with no changes. Version 1.3.0-rc01 contains these commits.

Version 1.3.0-beta01

August 9, 2023

androidx.collection:collection-*:1.3.0-beta01 is released. Version 1.3.0-beta01 contains these commits.

Version 1.3.0-alpha04

March 24, 2023

androidx.collection:collection-*:1.3.0-alpha04 is released.

Bug Fixes

Removed dependency constraints from Maven artifacts to workaround a build problem in Kotlin Native Targets (b/274786186, KT-57531).

Version 1.3.0-alpha03

March 22, 2023

androidx.collection:collection-*:1.3.0-alpha03 is released. Version 1.3.0-alpha03 contains these commits.

New Features

You can now use Collections in KMM projects. Note that non-Android targets of Collections are still experimental but we decided to merge versions to make it easier for developers to try them.

API Changes

ArraySet now implements MutableCollections instead of AbstractMutableCollection to allow for a more memory efficient implementation of toArray (I1ac32)

Bug Fixes

ArraySet.toArray is now only available on JVM as it was always only included for compatibility with Java. Kotlin users should generally use the stdlib's .toTypedArray helpers instead, which provides the exact same functionality with added type safety. (I2c59b)

Version 1.3.0-alpha02

July 27, 2022

androidx.collection:collection:1.3.0-alpha02 and androidx.collection:collection-ktx:1.3.0-alpha02 are released. Version 1.3.0-alpha02 contains these commits.

API Changes

SparseArrayCompat is now available to non-jvm platforms from the common artifact (Ic9bd0, b/219589118, b/228347315)
CircularIntArray is now available to non-jvm platforms from the common artifact (I3d8ef, b/228344943)
LongSparseArray is now available to non-jvm platforms from the common artifact (I73149, b/228347315)

Version 1.3.0-alpha01

June 29, 2022

androidx.collection:collection:1.3.0-alpha01 and androidx.collection:collection-ktx:1.3.0-alpha01 are released. Version 1.3.0-alpha01 contains these commits.

New Features

collection-ktx extensions have been migrated into the main collections artifact, androidx.collection:collection. This change makes the pre-existing -ktx extensions accessible to Kotlin users without requiring the -ktx dependency, while still maintaining compatibility for existing users. Maintaining these extensions in a separate -ktx artifact is no longer beneficial since the main artifact has moved to Kotlin. (I6eef2)

API Changes

ArraySet now extends AbstractMutableCollection and no longer directly implements the Collection interface. (If6da0, b/230860589)
Converted ArraySet to Kotlin. Due to stricter typing, some Kotlin calls may no longer compile. (Id68c1, b/230860589)
- The following calls have the argument type T, not T?:
  - ArraySet<T>.contains(null)
  - ArraySet<T>.add(null)
  - ArraySet<T>.remove(null)
- The following calls have the return type T?, not T!:
  - ArraySet<T?>.valueAt(n)
  - ArraySet<T?>.removeAt(n)
  - ArraySet<T?>().iterator().next()
- The following calls are no longer possible from Kotlin:
  - set.toArray() - use set.toTypedArray()
  - set.toArray(array) - use set.forEachIndexed(array::set)
Combine overloaded constructor for SparseArrayCompat as an optional argument for Kotlin users. (If8407, b/227474719)
Remove operator syntax for SparseArrayCompat.get(key, defaultValue). Note this still allows operator syntax for .get(key), but better aligns the API surface of SparseArrayCompat with the other classes in this library. (I9a38d)
Migrate LongSparseArray extensions into the main artifact, androidx.collection:collection. This change makes the pre-existing -ktx extensions accessible to Kotlin users without requiring the -ktx dependency, while still maintaining compatibility for existing users. Maintaining these extensions in a separate -ktx artifact is no longer beneficial since the main artifact has moved to Kotlin. (I8659a)
Convert LongSparseArray to Kotlin. This change adds explicit nullity to its types, which is a binary compatible change, but may cause source incompatibilities. In particular: * .isEmpty is no longer accessible as a property, it must be accessed as a function call in Kotlin - .isEmpty() (Idfd0f)
Convert SimpleArrayMap to Kotlin. This change introduces a few incompatible changes, as a result of Java-Kotlin interop and the ability to correctly define nullity of types in the source.
- The package private APIs, .mSize, .mArray, .mHashes, .indexOf(), .indexOfNull(), and .indexOfValue(), were made private - this is technically a binary incompatible change, but reflects the intended visibility of these fields and is the closest we can achieve in Kotlin since it does not include a way to specify package-private visibility.
- The nullity of some types are now properly defined, the affected methods are: .getOrDefault, .keyAt, .valueAt, .setValueAt, .put, .putIfAbsent, .removeAt, .replace.
- For Kotlin users, .isEmpty() is now only available as a function instead of also through property access. (I271b7, b/182813986)
Convert CircularArray to Kotlin. Notable changes:
- Corrects the nullity of its generics to be non-null, which was previously impossible to declare, but was enforced in all of its public APIs.
- Due to Kotlin's Java interop, it was previously possible to access certain methods as both properties or functions. However, to reduce duplication while maintaining binary compatibility, it was necessary to remove these, which is a source-incompatible change. The affectedn calls are: .isEmpty, .getLast() and .getFirst(). (Ifffac)
Convert CircularIntArray to Kotlin. Due to Kotlin's Java interop, it was previously possible to access certain methods as both properties or functions. However, to reduce duplication while maintaining binary compatibility, it was necessary to remove these, which is a source-incompatible change. The affected calls are: .isEmpty, .getLast() and .getFirst(). (Ie36ce)
Convert LruCache to Kotlin (Ia2f19)
Convert SparseArrayCompat to Kotlin. (If6fe8)

A small behavior change is added to SparseArrayCompat.valueAt(), which no longer incorrectly returns null for un-initialized calls out of bounds of size() but within the provided initial capacity.

This change also introduces the correct nullity for some types which was previously missing.
- .get(): E? -> .get(): E
- .replace(Int, Int?): Int? -> .replace(Int, Int): Int?
- .replace(Int, Int?, Int?): Boolean -> .replace(Int, Int, Int): Boolean
- .put(Int, Int?) -> .put(Int, Int)
- .putIfAbsent(Int, Int?): Int? -> .putIfAbsent(Int, Int): Int?
- .setValueAt(index: Int, value: Int?) -> .setValueAt(index: Int, value: Int)
- .indexOfValue(value: Int?): Int -> .indexOfValue(value: Int): Int
- .containsValue(value: Int?): Boolean -> .containsValue(value: Int): Boolean
- .append(key: Int, value: Int?) -> .append(key: Int, value: Int)

Version 1.2.0

December 1, 2021

androidx.collection:collection:1.2.0 and androidx.collection:collection-ktx:1.2.0 are released. Version 1.2.0 contains these commits.

Important changes since 1.1.0

Add an array constructor to ArraySet. (Id7f19)
Make entrySet() API-compliant by implementing entrySet().toArray(), remove(), removeAll(), and retainAll(), and removing implementation of entrySet().addAll() (I5d505)

Version 1.2.0-rc01

November 17, 2021

androidx.collection:collection:1.2.0-rc01 and androidx.collection:collection-ktx:1.2.0-rc01 are released. Version 1.2.0-rc01 contains these commits.

API Changes

No changes from previous beta.

Version 1.2.0-beta01

October 13, 2021

androidx.collection:collection:1.2.0-beta01 and androidx.collection:collection-ktx:1.2.0-beta01 are released. Version 1.2.0-beta01 contains these commits.

Bug Fixes

Make entrySet() API-compliant by implementing entrySet().toArray(), remove(), removeAll(), and retainAll(), and removing implementation of entrySet().addAll() (I5d505)

Version 1.2.0-alpha01

December 16, 2020

androidx.collection:collection:1.2.0-alpha01 and androidx.collection:collection-ktx:1.2.0-alpha01 are released. Version 1.2.0-alpha01 contains these commits.

API Changes

Add an array constructor to ArraySet. (Id7f19)

Version 1.1.0

June 5, 2019

androidx.collection:collection:1.1.0 and androidx.collection:collection-ktx:1.1.0 are released. The commits included 1.1.0 can be found here.

Below is a summary of changes from 1.0.0 to 1.1.0:

New features

Use more efficient implementation for contains and isNotEmpty functions in 'collection-ktx' artifact. (aosp/866529)

API changes

Add putIfAbsent to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772608)
Add getOrDefault to SimpleArrayMap (aosp/772607)
Add two-argument remove to LongSparseArray, SimpleArrayMap, and SparseArrayCompat. Deprecate corresponding KTX extensions for this functionality. (aosp/772482)
Add two-argument replace to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772483)
Add three-argument replace to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772484)
Deprecate redundant delete methods. The remove method offers the same API and functionality and matches the API used by non-specialized Maps. (aosp/866053)

Bug fixes

Change SimpleArrayMap to synchronize its internal global cache of arrays on SimpleArrayMap.class instead of ArrayMap.class. This ensures that if you are only using SimpleArrayMap, ArrayMap can be removed by code shrinking tools. (aosp/934557)

Version 1.1.0-rc01

May 7, 2019

androidx.collection:collection:1.1.0-rc01 and androidx.collection:collection-ktx:1.1.0-rc01 are released. The commits included in this version can be found here.

New features

Use more efficient implementation for contains and isNotEmpty functions in 'collection-ktx' artifact. (aosp/866529)

Version 1.1.0-beta01

April 3, 2019

androidx.collection:collection:1.1.0-beta01 and androidx.collection:collection-ktx:1.1.0-beta01 are released. The commits included in this version can be found here.

API changes

The method mentioned in the alpha03 release notes as having its @RestrictTo value changed has been removed. It was unused by any AndroidX library (now or historically) and it did not offer any functionality that was missing from the public API.

Bug fixes

Change SimpleArrayMap to synchronize its internal global cache of arrays on SimpleArrayMap.class instead of ArrayMap.class. This ensures that if you are only using SimpleArrayMap, ArrayMap can be removed by code shrinking tools. (aosp/934557)

Version 1.1.0-alpha03

March 13, 2019

androidx.collection:collection:1.0.0-alpha03 and androidx.collection:collection-ktx:1.0.0-alpha03 are released. The full list of commits included in this version can be found here.

API changes

A method on ArraySet previously marked @RestrictTo(LIBRARY_GROUP) was changed to @RestrictTo(LIBRARY_GROUP_PREFIX). This is to support historical use by other AndroidX libraries which are now in different Maven group IDs. This method will either be made public or removed in 1.1.0-alpha04 because other AndroidX libraries should not get special APIs that other developers do not.

Version 1.1.0-alpha02

January 30, 2019

androidx.collection:collection 1.1.0-alpha02 and androidx.collection:collection-ktx 1.1.0-alpha02 are released.

API changes

Deprecate redundant delete methods. The remove methods offers the same API and functionality and matches the API used by non-specialized Maps. (aosp/866053)

Version 1.1.0-alpha01

December 3, 2018

API changes

Add putIfAbsent to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772608)
Add getOrDefault to SimpleArrayMap (aosp/772607)
Add two-argument remove to LongSparseArray, SimpleArrayMap, and SparseArrayCompat. Deprecate corresponding KTX extensions for this functionality. (aosp/772482)
Add two-argument replace to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772483)
Add three-argument replace to LongSparseArray, SimpleArrayMap, and SparseArrayCompat (aosp/772484)