From 5771302ca13c31cb85f17bc58da8f6f8227c9b85 Mon Sep 17 00:00:00 2001 From: Flavio Lerda Date: Sun, 8 Sep 2013 18:04:58 +0100 Subject: Document the order of values returned by keyAt(). The values returned by keyAt() are currently guaranteed to be in ascending order. This is helpful to users of the API to be able to make assumptions about the keys and values when iterating over one of the sparse array implementations. This commit adds documentation about this. Change-Id: I3d7eb78e115ce174f1167b83904b44bf5120b223 --- core/java/android/util/LongSparseArray.java | 17 +++++++++++++++++ core/java/android/util/LongSparseLongArray.java | 17 +++++++++++++++++ core/java/android/util/SparseArray.java | 17 +++++++++++++++++ core/java/android/util/SparseBooleanArray.java | 23 ++++++++++++++++++++--- core/java/android/util/SparseIntArray.java | 23 ++++++++++++++++++++--- core/java/android/util/SparseLongArray.java | 17 +++++++++++++++++ 6 files changed, 108 insertions(+), 6 deletions(-) (limited to 'core') diff --git a/core/java/android/util/LongSparseArray.java b/core/java/android/util/LongSparseArray.java index 63e8c25..d6e116f 100644 --- a/core/java/android/util/LongSparseArray.java +++ b/core/java/android/util/LongSparseArray.java @@ -39,6 +39,12 @@ import com.android.internal.util.ArrayUtils; * a single garbage collection step of all removed entries. This garbage collection will * need to be performed at any time the array needs to be grown or the the map size or * entry values are retrieved.

+ * + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

*/ public class LongSparseArray implements Cloneable { private static final Object DELETED = new Object(); @@ -238,6 +244,11 @@ public class LongSparseArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this * LongSparseArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public long keyAt(int index) { if (mGarbage) { @@ -251,6 +262,12 @@ public class LongSparseArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this * LongSparseArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ @SuppressWarnings("unchecked") public E valueAt(int index) { diff --git a/core/java/android/util/LongSparseLongArray.java b/core/java/android/util/LongSparseLongArray.java index 133e415..87d868b 100644 --- a/core/java/android/util/LongSparseLongArray.java +++ b/core/java/android/util/LongSparseLongArray.java @@ -35,6 +35,12 @@ import java.util.Arrays; * and deleting entries in the array. For containers holding up to hundreds of items, * the performance difference is not significant, less than 50%.

* + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

+ * * @hide */ public class LongSparseLongArray implements Cloneable { @@ -163,6 +169,11 @@ public class LongSparseLongArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this * SparseLongArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public long keyAt(int index) { return mKeys[index]; @@ -172,6 +183,12 @@ public class LongSparseLongArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this * SparseLongArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ public long valueAt(int index) { return mValues[index]; diff --git a/core/java/android/util/SparseArray.java b/core/java/android/util/SparseArray.java index 6e66090..6e168a8 100644 --- a/core/java/android/util/SparseArray.java +++ b/core/java/android/util/SparseArray.java @@ -39,6 +39,12 @@ import com.android.internal.util.ArrayUtils; * a single garbage collection step of all removed entries. This garbage collection will * need to be performed at any time the array needs to be grown or the the map size or * entry values are retrieved.

+ * + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

*/ public class SparseArray implements Cloneable { private static final Object DELETED = new Object(); @@ -251,6 +257,11 @@ public class SparseArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this * SparseArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public int keyAt(int index) { if (mGarbage) { @@ -264,6 +275,12 @@ public class SparseArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this * SparseArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ @SuppressWarnings("unchecked") public E valueAt(int index) { diff --git a/core/java/android/util/SparseBooleanArray.java b/core/java/android/util/SparseBooleanArray.java index da196d7..68487e3 100644 --- a/core/java/android/util/SparseBooleanArray.java +++ b/core/java/android/util/SparseBooleanArray.java @@ -33,6 +33,12 @@ import com.android.internal.util.ArrayUtils; * HashMap, since lookups require a binary search and adds and removes require inserting * and deleting entries in the array. For containers holding up to hundreds of items, * the performance difference is not significant, less than 50%.

+ * + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

*/ public class SparseBooleanArray implements Cloneable { /** @@ -159,16 +165,27 @@ public class SparseBooleanArray implements Cloneable { /** * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this - * SparseBooleanArray stores. + * SparseBooleanArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public int keyAt(int index) { return mKeys[index]; } - + /** * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this - * SparseBooleanArray stores. + * SparseBooleanArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ public boolean valueAt(int index) { return mValues[index]; diff --git a/core/java/android/util/SparseIntArray.java b/core/java/android/util/SparseIntArray.java index c2bacb0..0835cb0 100644 --- a/core/java/android/util/SparseIntArray.java +++ b/core/java/android/util/SparseIntArray.java @@ -32,6 +32,12 @@ import com.android.internal.util.ArrayUtils; * HashMap, since lookups require a binary search and adds and removes require inserting * and deleting entries in the array. For containers holding up to hundreds of items, * the performance difference is not significant, less than 50%.

+ * + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

*/ public class SparseIntArray implements Cloneable { private int[] mKeys; @@ -169,16 +175,27 @@ public class SparseIntArray implements Cloneable { /** * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this - * SparseIntArray stores. + * SparseIntArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public int keyAt(int index) { return mKeys[index]; } - + /** * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this - * SparseIntArray stores. + * SparseIntArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ public int valueAt(int index) { return mValues[index]; diff --git a/core/java/android/util/SparseLongArray.java b/core/java/android/util/SparseLongArray.java index 182fd35..62c1c0d 100644 --- a/core/java/android/util/SparseLongArray.java +++ b/core/java/android/util/SparseLongArray.java @@ -32,6 +32,12 @@ import com.android.internal.util.ArrayUtils; * HashMap, since lookups require a binary search and adds and removes require inserting * and deleting entries in the array. For containers holding up to hundreds of items, * the performance difference is not significant, less than 50%.

+ * + *

It is possible to iterate over the items in this container using + * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using + * keyAt(int) with ascending values of the index will return the + * keys in ascending order, or the values corresponding to the keys in ascending + * order in the case of valueAt(int).

*/ public class SparseLongArray implements Cloneable { private int[] mKeys; @@ -159,6 +165,11 @@ public class SparseLongArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the key from the indexth key-value mapping that this * SparseLongArray stores. + * + *

The keys corresponding to indices in ascending order are guaranteed to + * be in ascending order, e.g., keyAt(0) will return the + * smallest key and keyAt(size()-1) will return the largest + * key.

*/ public int keyAt(int index) { return mKeys[index]; @@ -168,6 +179,12 @@ public class SparseLongArray implements Cloneable { * Given an index in the range 0...size()-1, returns * the value from the indexth key-value mapping that this * SparseLongArray stores. + * + *

The values corresponding to indices in ascending order are guaranteed + * to be associated with keys in ascending order, e.g., + * valueAt(0) will return the value associated with the + * smallest key and valueAt(size()-1) will return the value + * associated with the largest key.

*/ public long valueAt(int index) { return mValues[index]; -- cgit v1.1