diff --git a/core/java/android/util/SparseArray.java b/core/java/android/util/SparseArray.java index b3400ef538b89..af18caa0e1220 100644 --- a/core/java/android/util/SparseArray.java +++ b/core/java/android/util/SparseArray.java @@ -22,32 +22,34 @@ import com.android.internal.util.GrowingArrayUtils; import libcore.util.EmptyArray; /** - * SparseArrays map integers to Objects. Unlike a normal array of Objects, - * there can be gaps in the indices. It is intended to be more memory efficient - * than using a HashMap to map Integers to Objects, both because it avoids + * SparseArray maps integers to Objects and, unlike a normal array of Objects, + * its indices can contain gaps. SparseArray is intended to be more memory-efficient + * than a + * HashMap, because it avoids * auto-boxing keys and its data structure doesn't rely on an extra entry object * for each mapping. * *

Note that this container keeps its mappings in an array data structure, - * using a binary search to find keys. The implementation is not intended to be appropriate for + * using a binary search to find keys. The implementation is not intended to be appropriate for * data structures - * that may contain large numbers of items. It is generally slower than a traditional - * 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%.

+ * that may contain large numbers of items. It is generally slower than a + * HashMap because 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 less than 50%. * *

To help with performance, the container includes an optimization when removing * keys: instead of compacting its array immediately, it leaves the removed entry marked - * as deleted. The entry can then be re-used for the same key, or compacted later in - * 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.

+ * as deleted. The entry can then be re-used for the same key or compacted later in + * a single garbage collection of all removed entries. This garbage collection + * must be performed whenever the array needs to be grown, or when 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).

+ * keyAt(int) with ascending values of the index returns the + * keys in ascending order. In the case of valueAt(int), the + * values corresponding to the keys are returned in ascending order. */ public class SparseArray implements Cloneable { private static final Object DELETED = new Object(); @@ -333,7 +335,7 @@ public class SparseArray implements Cloneable { /** * Returns an index for which {@link #valueAt} would return the - * specified key, or a negative number if no keys map to the + * specified value, or a negative number if no keys map to the * specified value. *

Beware that this is a linear search, unlike lookups by key, * and that multiple keys can map to the same value and this will @@ -357,7 +359,7 @@ public class SparseArray implements Cloneable { /** * Returns an index for which {@link #valueAt} would return the - * specified key, or a negative number if no keys map to the + * specified value, or a negative number if no keys map to the * specified value. *

Beware that this is a linear search, unlike lookups by key, * and that multiple keys can map to the same value and this will