Update SparseArray docs to be more informative.

Change-Id: I5d8d17d46a69ccdcf6b29f93be3d44addd80ab61

1 files changed, 12 insertions, 2 deletions

diff --git a/core/java/android/util/SparseBooleanArray.java b/core/java/android/util/SparseBooleanArray.java
index 73e3629d467d..430755a94e41 100644
--- a/core/java/android/util/SparseBooleanArray.java
+++ b/core/java/android/util/SparseBooleanArray.java
@@ -21,8 +21,18 @@ import com.android.internal.util.ArrayUtils;
 /**
  * SparseBooleanArrays map integers to booleans.
  * Unlike a normal array of booleans
- * there can be gaps in the indices.  It is intended to be more efficient
- * than using a HashMap to map Integers to Booleans.
+ * there can be gaps in the indices.  It is intended to be more memory efficient
+ * than using a HashMap to map Integers to Booleans, both because it avoids
+ * auto-boxing keys and values and its data structure doesn't rely on an extra entry object
+ * for each mapping.
+ *
+ * <p>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
+ * 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%.</p>
  */
 public class SparseBooleanArray implements Cloneable {
     static final boolean[] EMPTY_BOOLEANS = new boolean[0];