Add unboxing binarySearch to Lists util

Author: Col-E

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>software.coley</groupId>
     <artifactId>extra-collections</artifactId>
-    <version>1.6.0</version>
+    <version>1.7.0</version>
 
     <name>Extra Collections</name>
     <description>Extra useful collection types and utilities</description>

src/main/java/software/coley/collections/Lists.java

@@ -10,7 +10,7 @@
 import java.util.Comparator;
 import java.util.List;
 import java.util.SortedSet;
-import java.util.TreeSet;
+import java.util.function.Function;
 
 /**
  * Utility for handling {@link java.util.List} types.
@@ -201,8 +201,9 @@ public static <T> List<T> ofVar(T... values) {
 	 * @param <T>
 	 * 		Item type.
 	 *
-	 * @return Index of item in list.
-	 * If the item is not in the list, the negative value of the index where it would appear in sorted order.
+	 * @return Index of item in list, within the range.
+	 * If the item is not in the list, then {@code (-(insertion point) - 1)} where the insertion point is
+	 * the index at which the value would be inserted into the list.
 	 */
 	public static <T extends Comparable<T>> int binarySearch(@Nonnull List<T> items, @Nonnull T target) {
 		return binarySearch(items, target, 0, items.size() - 1);
@@ -221,24 +222,76 @@ public static <T extends Comparable<T>> int binarySearch(@Nonnull List<T> items,
 	 * 		Item type.
 	 *
 	 * @return Index of item in list, within the range.
-	 * If the item is not in the list, the negative value of the index where it would appear in sorted order.
+	 * If the item is not in the list, then {@code (-(insertion point) - 1)} where the insertion point is
+	 * the index at which the value would be inserted into the list.
 	 */
 	public static <T extends Comparable<T>> int binarySearch(@Nonnull List<T> items, @Nonnull T target, int first, int last) {
-		if (first > last)
-			// Typically yield '-1' but with this, we will have it such that if 'target' is not in the list
-			// then the return value will be the negative value of the index where it would be inserted into
-			// while maintaining sorted order.
-			return (first == 0 && last == -1) ? last : -last;
-		else {
-			int middle = (first + last) / 2;
+		while (first <= last) {
+			int middle = (first + last) >>> 1;
 			int compResult = target.compareTo(items.get(middle));
 			if (compResult == 0)
 				return middle;
-			else if (compResult < 0)
-				return binarySearch(items, target, first, middle - 1);
+			if (compResult < 0)
+				last = middle - 1;
+			else
+				first = middle + 1;
+		}
+		return (first == 0 && last == -1) ? last : -last;
+	}
+
+	/**
+	 * @param items
+	 * 		Item list to search in.
+	 * @param target
+	 * 		Item to search for.
+	 * @param unbox
+	 * 		Function to unbox B into T.
+	 * @param <B>
+	 * 		Box type.
+	 * @param <T>
+	 * 		Item type.
+	 *
+	 * @return Index of item in list, within the range.
+	 * If the item is not in the list, then {@code (-(insertion point) - 1)} where the insertion point is
+	 * the index at which the value would be inserted into the list.
+	 */
+	public static <B, T extends Comparable<T>> int binaryUnboxingSearch(@Nonnull List<B> items, @Nonnull T target, @Nonnull Function<B, T> unbox) {
+		return binaryUnboxingSearch(items, target, unbox, 0, items.size() - 1);
+	}
+
+	/**
+	 * @param items
+	 * 		Item list to search in.
+	 * @param target
+	 * 		Item to search for.
+	 * @param unbox
+	 * 		Function to unbox B into T.
+	 * @param first
+	 * 		Start range.
+	 * @param last
+	 * 		End range.
+	 * @param <B>
+	 * 		Box type.
+	 * @param <T>
+	 * 		Item type.
+	 *
+	 * @return Index of item in list, within the range.
+	 * If the item is not in the list, then {@code (-(insertion point) - 1)} where the insertion point is
+	 * the index at which the value would be inserted into the list.
+	 */
+	public static <B, T extends Comparable<T>> int binaryUnboxingSearch(@Nonnull List<B> items, @Nonnull T target,
+	                                                                    @Nonnull Function<B, T> unbox, int first, int last) {
+		while (first <= last) {
+			int middle = (first + last) >>> 1;
+			int compResult = target.compareTo(unbox.apply(items.get(middle)));
+			if (compResult == 0)
+				return middle;
+			if (compResult < 0)
+				last = middle - 1;
 			else
-				return binarySearch(items, target, middle + 1, last);
+				first = middle + 1;
 		}
+		return (first == 0 && last == -1) ? last : -last;
 	}
 
 	/**

src/test/java/software/coley/collections/ListsTest.java

@@ -1,10 +1,13 @@
 package software.coley.collections;
 
 import org.junit.jupiter.api.Test;
+import software.coley.collections.box.Box;
 
 import java.util.ArrayList;
+import java.util.Collections;
 import java.util.Comparator;
 import java.util.List;
+import java.util.function.Function;
 
 import static java.util.Arrays.asList;
 import static java.util.Collections.emptyList;
@@ -72,6 +75,10 @@ void of() {
 
 	@Test
 	void binarySearch() {
+		// Base case, empty list
+		assertEquals(-1, Lists.binarySearch(Collections.emptyList(), "a"));
+
+		// Alphabetical test case
 		List<String> strings = asList("a", "b", "c", /* d */ "e", "f");
 		assertEquals(0, Lists.binarySearch(strings, "a"));
 		assertEquals(2, Lists.binarySearch(strings, "c"));
@@ -89,6 +96,23 @@ void binarySearch() {
 		assertEquals(-3, Lists.binarySearch(strings, "a", 4, 5));
 	}
 
+	@Test
+	void binaryBoxedSearch() {
+		// Same test as the above but boxed
+		List<Box<String>> strings = asList(new Box<>("a"), new Box<>("b"), new Box<>("c"), /* new Box<>("d") */ new Box<>("e"), new Box<>("f"));
+		assertEquals(0, Lists.binaryUnboxingSearch(strings, "a", Box::get));
+		assertEquals(2, Lists. binaryUnboxingSearch(strings, "c", Box::get));
+		assertEquals(3, Lists. binaryUnboxingSearch(strings, "e", Box::get));
+		assertEquals(4, Lists. binaryUnboxingSearch(strings, "f", Box::get));
+		assertEquals(-1, Lists.binaryUnboxingSearch(strings, " ", Box::get));
+		assertEquals(-2, Lists.binaryUnboxingSearch(strings, "d", Box::get));
+		assertEquals(-4, Lists.binaryUnboxingSearch(strings, "g", Box::get));
+		assertEquals(0, Lists. binaryUnboxingSearch(strings, "a",  Box::get, 1, 5));
+		assertEquals(-1, Lists.binaryUnboxingSearch(strings, "a", Box::get, 2, 5));
+		assertEquals(-2, Lists.binaryUnboxingSearch(strings, "a", Box::get, 3, 5));
+		assertEquals(-3, Lists.binaryUnboxingSearch(strings, "a", Box::get, 4, 5));
+	}
+
 	@Test
 	void sortedInsertIndex() {
 		// Unlike the binary search call, this normalizes the index to positive range