Merge "Docs: fixed typo and made minor edits" into pi-dev

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

 * <code>SparseArray</code> maps integers to Objects and, unlike a normal array of Objects,

 * its indices can contain gaps. <code>SparseArray</code> is intended to be more memory-efficient

 * than a

 * <a href="/reference/java/util/HashMap"><code>HashMap</code></a>, because it avoids

 * auto-boxing keys 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

 * that may contain large numbers of items. It is generally slower than a

 * <code>HashMap</code> 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 not significant, less than 50%.</p>

 * the performance difference is less than 50%.

 *

 * <p>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.</p>

 * 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.

 *

 * <p>It is possible to iterate over the items in this container using

 * {@link #keyAt(int)} and {@link #valueAt(int)}. Iterating over the keys using

 * <code>keyAt(int)</code> 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 <code>valueAt(int)</code>.</p>

 * <code>keyAt(int)</code> with ascending values of the index returns the

 * keys in ascending order. In the case of <code>valueAt(int)</code>, the

 * values corresponding to the keys are returned in ascending order.

 */

public class SparseArray<E> implements Cloneable {

    private static final Object DELETED = new Object();

    /**

     * 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.

     * <p>Beware that this is a linear search, unlike lookups by key,

     * and that multiple keys can map to the same value and this will

    /**

     * 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.

     * <p>Beware that this is a linear search, unlike lookups by key,

     * and that multiple keys can map to the same value and this will