Collection
Latest Update | Stable Release | Release Candidate | Beta Release | Alpha Release |
---|---|---|---|---|
October 2, 2024 | 1.4.4 | - | - | 1.5.0-alpha03 |
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.4" implementation "androidx.collection:collection:$collection_version" }
Kotlin
dependencies { val collection_version = "1.4.4" 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.
See the Issue Tracker documentation for more information.
Version 1.5
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
tocontainsKey
. 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 forLruCache
that offers better hit ratio characteristics. (I50a17)- Exposed the
packedValue
internal representation forIntIntPair
andFloatFloatPair
. (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.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()
andrequired()
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)
- Replace calls to
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 withMutableMap
& Map-like APIMutableScatterSet
&ScatterSet
- Classes withMutableSet
& Set-like APIMutableObjectList
&ObjectList
- Classes withMutableList
& 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 inObjectList
that could result in a crash due toIndexOutOfBoundsException
. (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 asFloatFloatMap
. - Convert
removeIf
methods on primitive collections, such asMutableFloatFloatMap
to inline. This ensures that the lambda forremoveIf
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 withMutableMap
& Map-like APIMutableScatterSet
&ScatterSet
- Classes withMutableSet
& Set-like APIMutableObjectList
&ObjectList
- Classes withMutableList
& List-like API
New high-efficiency collections for storing primitives without boxing have been added:
Mutable[Int|Float|Long]List
- Classes withMutableList<Int|Float|Long>
-like API. The read-only[Int|Float|Long]List
also exists. For example, integers can be held in anIntList
.Mutable[Int|Float|Long]Set
- Classes withMutableSet<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 withMutable<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 anIntObjectMap<T>
. A map with a long key and a float value is aLongFloatMap
. There is no version with the nameObjectObjectMap
because that is covered byScatterMap/MutableScatterMap
.
Version 1.3.0
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 oncollection:collection-ktx
in favor ofcollection:collection
ascollection-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 implementsMutableCollections
instead ofAbstractMutableCollection
to allow for a more memory efficient implementation oftoArray
(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 extendsAbstractMutableCollection
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
, notT?
:ArraySet<T>.contains(null)
ArraySet<T>.add(null)
ArraySet<T>.remove(null)
- The following calls have the return type
T?
, notT!
:ArraySet<T?>.valueAt(n)
ArraySet<T?>.removeAt(n)
ArraySet<T?>().iterator().next()
- The following calls are no longer possible from Kotlin:
set.toArray()
- useset.toTypedArray()
set.toArray(array)
- useset.forEachIndexed(array::set)
- The following calls have the argument type
- 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 ofSparseArrayCompat
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)
- The package private APIs,
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 returnsnull
for un-initialized calls out of bounds ofsize()
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
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 implementingentrySet().toArray()
,remove()
,removeAll()
, andretainAll()
, and removing implementation ofentrySet().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 implementingentrySet().toArray()
,remove()
,removeAll()
, andretainAll()
, and removing implementation ofentrySet().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
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
andisNotEmpty
functions in 'collection-ktx' artifact. (aosp/866529)
API changes
- Add
putIfAbsent
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772608) - Add
getOrDefault
toSimpleArrayMap
(aosp/772607) - Add two-argument
remove
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
. Deprecate corresponding KTX extensions for this functionality. (aosp/772482) - Add two-argument
replace
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772483) - Add three-argument
replace
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772484) - Deprecate redundant
delete
methods. Theremove
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 onSimpleArrayMap.class
instead ofArrayMap.class
. This ensures that if you are only usingSimpleArrayMap
,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
andisNotEmpty
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 onSimpleArrayMap.class
instead ofArrayMap.class
. This ensures that if you are only usingSimpleArrayMap
,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. Theremove
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
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772608) - Add
getOrDefault
toSimpleArrayMap
(aosp/772607) - Add two-argument
remove
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
. Deprecate corresponding KTX extensions for this functionality. (aosp/772482) - Add two-argument
replace
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772483) - Add three-argument
replace
toLongSparseArray
,SimpleArrayMap
, andSparseArrayCompat
(aosp/772484)