From f16747db093f6d6371d617efc8d90698d2d5b389 Mon Sep 17 00:00:00 2001
From: Dianne Hackborn <hackbod@google.com>
Date: Wed, 10 Jun 2015 17:49:43 -0700
Subject: [PATCH] Add ArraySet to the SDK.

Also fix some documentation.

Change-Id: I46025c3b5450e7cd671135b99ff3b298e223651d
---
 api/current.txt                      | 27 ++++++++++++++++++++++++-
 api/system-current.txt               | 27 ++++++++++++++++++++++++-
 core/java/android/util/ArrayMap.java | 11 ++++++----
 core/java/android/util/ArraySet.java | 30 ++++++++++++++++++++++++++--
 4 files changed, 87 insertions(+), 8 deletions(-)

diff --git a/api/current.txt b/api/current.txt
index cfb9398ac2315..65ce26855de25 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -33909,7 +33909,7 @@ package android.util {
   public final class ArrayMap implements java.util.Map {
     ctor public ArrayMap();
     ctor public ArrayMap(int);
-    ctor public ArrayMap(android.util.ArrayMap);
+    ctor public ArrayMap(android.util.ArrayMap<K, V>);
     method public void clear();
     method public boolean containsAll(java.util.Collection<?>);
     method public boolean containsKey(java.lang.Object);
@@ -33934,6 +33934,31 @@ package android.util {
     method public java.util.Collection<V> values();
   }
 
+  public final class ArraySet implements java.util.Collection java.util.Set {
+    ctor public ArraySet();
+    ctor public ArraySet(int);
+    ctor public ArraySet(android.util.ArraySet<E>);
+    method public boolean add(E);
+    method public void addAll(android.util.ArraySet<? extends E>);
+    method public boolean addAll(java.util.Collection<? extends E>);
+    method public void clear();
+    method public boolean contains(java.lang.Object);
+    method public boolean containsAll(java.util.Collection<?>);
+    method public void ensureCapacity(int);
+    method public int indexOf(java.lang.Object);
+    method public boolean isEmpty();
+    method public java.util.Iterator<E> iterator();
+    method public boolean remove(java.lang.Object);
+    method public boolean removeAll(android.util.ArraySet<? extends E>);
+    method public boolean removeAll(java.util.Collection<?>);
+    method public E removeAt(int);
+    method public boolean retainAll(java.util.Collection<?>);
+    method public int size();
+    method public java.lang.Object[] toArray();
+    method public T[] toArray(T[]);
+    method public E valueAt(int);
+  }
+
   public class AtomicFile {
     ctor public AtomicFile(java.io.File);
     method public void delete();
diff --git a/api/system-current.txt b/api/system-current.txt
index 6035ef29b48af..9cb0dc224303c 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -36186,7 +36186,7 @@ package android.util {
   public final class ArrayMap implements java.util.Map {
     ctor public ArrayMap();
     ctor public ArrayMap(int);
-    ctor public ArrayMap(android.util.ArrayMap);
+    ctor public ArrayMap(android.util.ArrayMap<K, V>);
     method public void clear();
     method public boolean containsAll(java.util.Collection<?>);
     method public boolean containsKey(java.lang.Object);
@@ -36211,6 +36211,31 @@ package android.util {
     method public java.util.Collection<V> values();
   }
 
+  public final class ArraySet implements java.util.Collection java.util.Set {
+    ctor public ArraySet();
+    ctor public ArraySet(int);
+    ctor public ArraySet(android.util.ArraySet<E>);
+    method public boolean add(E);
+    method public void addAll(android.util.ArraySet<? extends E>);
+    method public boolean addAll(java.util.Collection<? extends E>);
+    method public void clear();
+    method public boolean contains(java.lang.Object);
+    method public boolean containsAll(java.util.Collection<?>);
+    method public void ensureCapacity(int);
+    method public int indexOf(java.lang.Object);
+    method public boolean isEmpty();
+    method public java.util.Iterator<E> iterator();
+    method public boolean remove(java.lang.Object);
+    method public boolean removeAll(android.util.ArraySet<? extends E>);
+    method public boolean removeAll(java.util.Collection<?>);
+    method public E removeAt(int);
+    method public boolean retainAll(java.util.Collection<?>);
+    method public int size();
+    method public java.lang.Object[] toArray();
+    method public T[] toArray(T[]);
+    method public E valueAt(int);
+  }
+
   public class AtomicFile {
     ctor public AtomicFile(java.io.File);
     method public void delete();
diff --git a/core/java/android/util/ArrayMap.java b/core/java/android/util/ArrayMap.java
index 6ed388515599a..4ee9807da8508 100644
--- a/core/java/android/util/ArrayMap.java
+++ b/core/java/android/util/ArrayMap.java
@@ -266,7 +266,7 @@ public final class ArrayMap<K, V> implements Map<K, V> {
     /**
      * Create a new ArrayMap with the mappings from the given ArrayMap.
      */
-    public ArrayMap(ArrayMap map) {
+    public ArrayMap(ArrayMap<K, V> map) {
         this();
         if (map != null) {
             putAll(map);
@@ -843,7 +843,8 @@ public final class ArrayMap<K, V> implements Map<K, V> {
      * in the array map.
      *
      * <p><b>Note:</b> this is a very inefficient way to access the array contents, it
-     * requires generating a number of temporary objects.</p>
+     * requires generating a number of temporary objects and allocates additional state
+     * information associated with the container that will remain for the life of the container.</p>
      *
      * <p><b>Note:</b></p> the semantics of this
      * Set are subtly different than that of a {@link java.util.HashMap}: most important,
@@ -861,7 +862,8 @@ public final class ArrayMap<K, V> implements Map<K, V> {
      * in the array map.
      *
      * <p><b>Note:</b> this is a fairly inefficient way to access the array contents, it
-     * requires generating a number of temporary objects.</p>
+     * requires generating a number of temporary objects and allocates additional state
+     * information associated with the container that will remain for the life of the container.</p>
      */
     @Override
     public Set<K> keySet() {
@@ -873,7 +875,8 @@ public final class ArrayMap<K, V> implements Map<K, V> {
      * in the array map.
      *
      * <p><b>Note:</b> this is a fairly inefficient way to access the array contents, it
-     * requires generating a number of temporary objects.</p>
+     * requires generating a number of temporary objects and allocates additional state
+     * information associated with the container that will remain for the life of the container.</p>
      */
     @Override
     public Collection<V> values() {
diff --git a/core/java/android/util/ArraySet.java b/core/java/android/util/ArraySet.java
index 7da3941914f60..b7a3c42e8f24c 100644
--- a/core/java/android/util/ArraySet.java
+++ b/core/java/android/util/ArraySet.java
@@ -42,8 +42,6 @@ import java.util.Set;
  * you have no control over this shrinking -- if you set a capacity and then remove an
  * item, it may reduce the capacity to better match the current size.  In the future an
  * explicit call to set the capacity should turn off this aggressive shrinking behavior.</p>
- *
- * @hide
  */
 public final class ArraySet<E> implements Collection<E>, Set<E> {
     private static final boolean DEBUG = false;
@@ -660,11 +658,24 @@ public final class ArraySet<E> implements Collection<E>, Set<E> {
         return mCollections;
     }
 
+    /**
+     * Return an {@link java.util.Iterator} over all values in the set.
+     *
+     * <p><b>Note:</b> this is a fairly inefficient way to access the array contents, it
+     * requires generating a number of temporary objects and allocates additional state
+     * information associated with the container that will remain for the life of the container.</p>
+     */
     @Override
     public Iterator<E> iterator() {
         return getCollection().getKeySet().iterator();
     }
 
+    /**
+     * Determine if the array set contains all of the values in the given collection.
+     * @param collection The collection whose contents are to be checked against.
+     * @return Returns true if this array set contains a value for every entry
+     * in <var>collection</var>, else returns false.
+     */
     @Override
     public boolean containsAll(Collection<?> collection) {
         Iterator<?> it = collection.iterator();
@@ -676,6 +687,10 @@ public final class ArraySet<E> implements Collection<E>, Set<E> {
         return true;
     }
 
+    /**
+     * Perform an {@link #add(Object)} of all values in <var>collection</var>
+     * @param collection The collection whose contents are to be retrieved.
+     */
     @Override
     public boolean addAll(Collection<? extends E> collection) {
         ensureCapacity(mSize + collection.size());
@@ -686,6 +701,11 @@ public final class ArraySet<E> implements Collection<E>, Set<E> {
         return added;
     }
 
+    /**
+     * Remove all values in the array set that exist in the given collection.
+     * @param collection The collection whose contents are to be used to remove values.
+     * @return Returns true if any values were removed from the array set, else false.
+     */
     @Override
     public boolean removeAll(Collection<?> collection) {
         boolean removed = false;
@@ -695,6 +715,12 @@ public final class ArraySet<E> implements Collection<E>, Set<E> {
         return removed;
     }
 
+    /**
+     * Remove all values in the array set that do <b>not</b> exist in the given collection.
+     * @param collection The collection whose contents are to be used to determine which
+     * values to keep.
+     * @return Returns true if any values were removed from the array set, else false.
+     */
     @Override
     public boolean retainAll(Collection<?> collection) {
         boolean removed = false;