[collect] Add method to get i-th element of Collections

This change adds a new method `Collections2.getElement(Collection, int)`, which
returns the i-th element of the collection.

Unlike existing methods via Java `Stream` or `Iterable`, the method in this
change supports fast access for `ImmutableCollection`s backed by an internal
array in `O(1)` instead of `O(n)` with the existing approach.

Users can use this method to, e.g., retrieve a random element from
`ImmutableSet` (e.g., to select a random node to connect to from a pool of
nodes in a distributed system).

Author: Yannic

android/guava/src/com/google/common/collect/Collections2.java

@@ -693,4 +693,32 @@ private static boolean isPermutation(List<?> first, List<?> second) {
     }
     return map;
   }
+
+  /**
+   * Returns the element in the provided {@link Collection} at position {@code index}.
+   *
+   * @param collection The {@link Collection} to get the element from
+   * @param index The index of the element to get.
+   * @return The element.
+   *
+   * @throws IndexOutOfBoundsException if {@code index} is not within range of {@code 0} (inclusive)
+   *                                   and {@code collection.size()} (exclusive).
+   */
+  public static <T extends @Nullable Object> T getElement(Collection<T> collection, int index) {
+    int size = collection.size();
+    if (size < index) {
+      throw new IndexOutOfBoundsException();
+    }
+
+    // Fast path: `collection` is an `ImmutableCollection` and backed by an array of elements.
+    if (collection instanceof ImmutableCollection) {
+      ImmutableCollection<T> immutableCollection = (ImmutableCollection<T>) collection;
+      Object[] internalArray = immutableCollection.internalArray();
+      if (internalArray != null) {
+        return (T) internalArray[immutableCollection.internalArrayStart() + index];
+      }
+    }
+
+    return Iterables.getFirst(Iterables.skip(collection, index), null);
+  }
 }

guava-tests/test/com/google/common/collect/Collections2Test.java

@@ -21,6 +21,7 @@
 import static com.google.common.collect.Lists.newArrayList;
 import static com.google.common.truth.Truth.assertThat;
 import static java.util.Collections.nCopies;
+import static org.junit.Assert.assertThrows;
 
 import com.google.common.annotations.GwtCompatible;
 import com.google.common.annotations.GwtIncompatible;
@@ -498,4 +499,58 @@ public void testToStringImplWithNullEntries() throws Exception {
 
     assertEquals(list.toString(), Collections2.toStringImpl(list));
   }
+
+  public void testGetElementOutOfRangeWithSet() {
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet(), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet(), 0));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet(), 1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet("a"), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet("a"), 1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet("a"), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Sets.newHashSet("a", "b"), 2));
+  }
+
+  public void testGetElementOutOfRangeWithList() {
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList(), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList(), 0));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList(), 1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList("a"), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList("a"), 1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList("a"), -1));
+    assertThrows(IndexOutOfBoundsException.class, () -> Collections2.getElement(Lists.newArrayList("a", "b"), 2));
+  }
+
+  public void testGetElementFromSet() {
+    assertThat(Collections2.getElement(Sets.newHashSet("a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(Sets.newHashSet("b"), 0)).isEqualTo("b");
+    assertThat(Collections2.getElement(Sets.newHashSet("a", "b"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(Sets.newHashSet("a", "b"), 1)).isEqualTo("b");
+    assertThat(Collections2.getElement(Sets.newHashSet("b", "a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(Sets.newHashSet("b", "a"), 1)).isEqualTo("b");
+  }
+
+  public void testGetElementFromList() {
+    assertThat(Collections2.getElement(Lists.newArrayList("a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(Lists.newArrayList("a", "b"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(Lists.newArrayList("a", "b"), 1)).isEqualTo("b");
+    assertThat(Collections2.getElement(Lists.newArrayList("b", "a"), 0)).isEqualTo("b");
+    assertThat(Collections2.getElement(Lists.newArrayList("b", "a"), 1)).isEqualTo("a");
+  }
+
+  public void testGetElementFromImmutableSet() {
+    assertThat(Collections2.getElement(ImmutableSet.of("a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(ImmutableSet.of("b"), 0)).isEqualTo("b");
+    assertThat(Collections2.getElement(ImmutableSet.of("a", "b"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(ImmutableSet.of("a", "b"), 1)).isEqualTo("b");
+    assertThat(Collections2.getElement(ImmutableSet.of("b", "a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(ImmutableSet.of("b", "a"), 1)).isEqualTo("b");
+  }
+
+  public void testGetElementFromImmutableList() {
+    assertThat(Collections2.getElement(ImmutableList.of("a"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(ImmutableList.of("a", "b"), 0)).isEqualTo("a");
+    assertThat(Collections2.getElement(ImmutableList.of("a", "b"), 1)).isEqualTo("b");
+    assertThat(Collections2.getElement(ImmutableList.of("b", "a"), 0)).isEqualTo("b");
+    assertThat(Collections2.getElement(ImmutableList.of("b", "a"), 1)).isEqualTo("a");
+  }
 }

guava/src/com/google/common/collect/Collections2.java

@@ -699,4 +699,32 @@ private static boolean isPermutation(List<?> first, List<?> second) {
     Multiset<?> secondMultiset = HashMultiset.create(second);
     return firstMultiset.equals(secondMultiset);
   }
+
+  /**
+   * Returns the element in the provided {@link Collection} at position {@code index}.
+   *
+   * @param collection The {@link Collection} to get the element from
+   * @param index The index of the element to get.
+   * @return The element.
+   *
+   * @throws IndexOutOfBoundsException if {@code index} is not within range of {@code 0} (inclusive)
+   *                                   and {@code collection.size()} (exclusive).
+   */
+  public static <T extends @Nullable Object> T getElement(Collection<T> collection, int index) {
+    int size = collection.size();
+    if (size < index) {
+      throw new IndexOutOfBoundsException();
+    }
+
+    // Fast path: `collection` is an `ImmutableCollection` and backed by an array of elements.
+    if (collection instanceof ImmutableCollection) {
+      ImmutableCollection<T> immutableCollection = (ImmutableCollection<T>) collection;
+      Object[] internalArray = immutableCollection.internalArray();
+      if (internalArray != null) {
+        return (T) internalArray[immutableCollection.internalArrayStart() + index];
+      }
+    }
+
+    return Iterables.getFirst(Iterables.skip(collection, index), null);
+  }
 }