Skip to content

Commit 7e35007

Browse files
kvr000kvr000
committed
binarySearch on sorted arrays and sorted lists
1 parent ec4f545 commit 7e35007

File tree

4 files changed

+410
-0
lines changed

4 files changed

+410
-0
lines changed

‎src/main/java/org/apache/commons/lang3/ArrayUtils.java

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1432,6 +1432,115 @@ public static <T> T arraycopy(final T source, final int sourcePos, final T dest,
14321432
return dest;
14331433
}
14341434

1435+
/**
1436+
* Searches element in array sorted by key.
1437+
*
1438+
* @param array
1439+
* array sorted by key field
1440+
* @param key
1441+
* key to search for
1442+
* @param keyExtractor
1443+
* function to extract key from element
1444+
* @param comparator
1445+
* comparator for keys
1446+
*
1447+
* @return
1448+
* index of the search key, if it is contained in the array within specified range; otherwise,
1449+
* (-first_greater - 1). The first_greater is the index of lowest greater element in the list - if all elements
1450+
* are lower, the first_greater is defined as toIndex.
1451+
*
1452+
* @param <T>
1453+
* type of array element
1454+
* @param <K>
1455+
* type of key
1456+
*/
1457+
public static <K, T> int binarySearch(
1458+
T[] array,
1459+
K key,
1460+
Function<T, K> keyExtractor, Comparator<? super K> comparator
1461+
) {
1462+
return binarySearch0(array, 0, array.length, key, keyExtractor, comparator);
1463+
}
1464+
1465+
/**
1466+
* Searches element in array sorted by key, within range fromIndex - toIndex (inclusive - exclusive).
1467+
*
1468+
* @param array
1469+
* array sorted by key field
1470+
* @param fromIndex
1471+
* start index
1472+
* @param toIndex
1473+
* end index (exclusive)
1474+
* @param key
1475+
* key to search for
1476+
* @param keyExtractor
1477+
* function to extract key from element
1478+
* @param comparator
1479+
* comparator for keys
1480+
*
1481+
* @return
1482+
* index of the search key, if it is contained in the array within specified range; otherwise,
1483+
* (-first_greater - 1). The first_greater is the index of lowest greater element in the list - if all elements
1484+
* are lower, the first_greater is defined as toIndex.
1485+
*
1486+
* @throws ArrayIndexOutOfBoundsException
1487+
* when fromIndex or toIndex is out of array range
1488+
* @throws IllegalArgumentException
1489+
* when fromIndex is greater than toIndex
1490+
*
1491+
* @param <T>
1492+
* type of array element
1493+
* @param <K>
1494+
* type of key
1495+
*/
1496+
public static <T, K> int binarySearch(
1497+
T[] array,
1498+
int fromIndex, int toIndex,
1499+
K key,
1500+
Function<T, K> keyExtractor, Comparator<? super K> comparator
1501+
) {
1502+
if (fromIndex > toIndex) {
1503+
throw new IllegalArgumentException(
1504+
"fromIndex(" + fromIndex + ") > toIndex(" + toIndex + ")");
1505+
}
1506+
if (fromIndex < 0) {
1507+
throw new ArrayIndexOutOfBoundsException(fromIndex);
1508+
}
1509+
if (toIndex > array.length) {
1510+
throw new ArrayIndexOutOfBoundsException(toIndex);
1511+
}
1512+
1513+
return binarySearch0(array, fromIndex, toIndex, key, keyExtractor, comparator);
1514+
}
1515+
1516+
// common implementation for binarySearch methods, with same semantics:
1517+
private static <T, K> int binarySearch0(
1518+
T[] array,
1519+
int fromIndex, int toIndex,
1520+
K key,
1521+
Function<T, K> keyExtractor, Comparator<? super K> comparator
1522+
) {
1523+
int l = fromIndex;
1524+
int h = toIndex - 1;
1525+
1526+
while (l <= h) {
1527+
final int m = (l + h) >>> 1; // unsigned shift to avoid overflow
1528+
final K value = keyExtractor.apply(array[m]);
1529+
final int c = comparator.compare(value, key);
1530+
if (c < 0) {
1531+
l = m + 1;
1532+
} else if (c > 0) {
1533+
h = m - 1;
1534+
} else {
1535+
// 0, found
1536+
return m;
1537+
}
1538+
}
1539+
1540+
// not found, the l points to the lowest higher match:
1541+
return -l - 1;
1542+
}
1543+
14351544
/**
14361545
* Clones an array or returns {@code null}.
14371546
* <p>

‎src/main/java/org/apache/commons/lang3/SortedListUtils.java

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package org.apache.commons.lang3;
18+
19+
import java.util.Comparator;
20+
import java.util.List;
21+
import java.util.function.Function;
22+
23+
24+
/**
25+
* Operations on sorted {@link List}.
26+
*/
27+
public class SortedListUtils {
28+
/**
29+
* Finds element in sorted list.
30+
*
31+
* @param list
32+
* list sorted by key field
33+
* @param key
34+
* key to search for
35+
* @param keyExtractor
36+
* function to extract key from element
37+
* @param comparator
38+
* comparator for keys
39+
*
40+
* @return
41+
* index of the search key, if it is contained in the list within specified range; otherwise,
42+
* (-first_greater - 1). The first_greater is the index of lowest greater element in the list - if all elements
43+
* are lower, the first_greater is defined as toIndex.
44+
*
45+
* @param <T>
46+
* type of list element
47+
* @param <K>
48+
* type of key
49+
*/
50+
public static <K, T> int binarySearch(
51+
List<T> list,
52+
K key,
53+
Function<T, K> keyExtractor, Comparator<? super K> comparator
54+
) {
55+
return binarySearch(list, 0, list.size(), key, keyExtractor, comparator);
56+
}
57+
58+
/**
59+
* Finds element in sorted list, within range fromIndex - toIndex (inclusive - exclusive).
60+
*
61+
* @param list
62+
* list sorted by key field
63+
* @param fromIndex
64+
* start index
65+
* @param toIndex
66+
* end index (exclusive)
67+
* @param key
68+
* key to search for
69+
* @param keyExtractor
70+
* function to extract key from element
71+
* @param comparator
72+
* comparator for keys
73+
*
74+
* @return
75+
* index of the search key, if it is contained in the list within specified range; otherwise,
76+
* (-first_greater - 1). The first_greater is the index of lowest greater element in the list - if all elements
77+
* are lower, the first_greater is defined as toIndex.
78+
*
79+
* @param <T>
80+
* type of array element
81+
* @param <K>
82+
* type of key
83+
*/
84+
public static <T, K> int binarySearch(
85+
List<T> list,
86+
int fromIndex, int toIndex,
87+
K key,
88+
Function<T, K> keyExtractor, Comparator<? super K> comparator
89+
) {
90+
int l = fromIndex;
91+
int h = toIndex - 1;
92+
93+
while (l <= h) {
94+
int m = (l + h) >>> 1; // unsigned shift to avoid overflow
95+
K value = keyExtractor.apply(list.get(m));
96+
int c = comparator.compare(value, key);
97+
if (c < 0) {
98+
l = m + 1;
99+
} else if (c > 0) {
100+
h = m - 1;
101+
} else {
102+
// 0, found
103+
return m;
104+
}
105+
}
106+
107+
// not found, the l points to the lowest higher match:
108+
return -l - 1;
109+
}
110+
}

‎src/test/java/org/apache/commons/lang3/ArrayUtilsBinarySearchTest.java

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
/*
2+
* Licensed to the Apache Software Foundation (ASF) under one or more
3+
* contributor license agreements. See the NOTICE file distributed with
4+
* this work for additional information regarding copyright ownership.
5+
* The ASF licenses this file to You under the Apache License, Version 2.0
6+
* (the "License"); you may not use this file except in compliance with
7+
* the License. You may obtain a copy of the License at
8+
*
9+
* http://www.apache.org/licenses/LICENSE-2.0
10+
*
11+
* Unless required by applicable law or agreed to in writing, software
12+
* distributed under the License is distributed on an "AS IS" BASIS,
13+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14+
* See the License for the specific language governing permissions and
15+
* limitations under the License.
16+
*/
17+
package org.apache.commons.lang3;
18+
19+
import static org.junit.jupiter.api.Assertions.assertEquals;
20+
import static org.junit.jupiter.api.Assertions.assertThrowsExactly;
21+
22+
import java.util.stream.IntStream;
23+
24+
import org.junit.jupiter.api.Test;
25+
26+
/**
27+
* Unit tests {@link ArrayUtils} binarySearch functions.
28+
*/
29+
public class ArrayUtilsBinarySearchTest extends AbstractLangTest {
30+
31+
@Test
32+
public void binarySearch_whenLowHigherThanEnd_throw() {
33+
final Data[] list = createList(0, 1);
34+
assertThrowsExactly(IllegalArgumentException.class, () -> ArrayUtils.binarySearch(list, 1, 0, 0, Data::getValue, Integer::compare));
35+
}
36+
37+
@Test
38+
public void binarySearch_whenLowNegative_throw() {
39+
final Data[] list = createList(0, 1);
40+
assertThrowsExactly(ArrayIndexOutOfBoundsException.class, () -> ArrayUtils.binarySearch(list, -1, 0, 0, Data::getValue, Integer::compare));
41+
}
42+
43+
@Test
44+
public void binarySearch_whenEndBeyondLength_throw() {
45+
final Data[] list = createList(0, 1);
46+
assertThrowsExactly(ArrayIndexOutOfBoundsException.class, () -> ArrayUtils.binarySearch(list, 0, 3, 0, Data::getValue, Integer::compare));
47+
}
48+
49+
@Test
50+
public void binarySearch_whenEmpty_returnM1() {
51+
final Data[] list = createList();
52+
final int found = ArrayUtils.binarySearch(list, 0, Data::getValue, Integer::compare);
53+
assertEquals(-1, found);
54+
}
55+
56+
@Test
57+
public void binarySearch_whenExists_returnIndex() {
58+
final Data[] list = createList(0, 1, 2, 4, 7, 9, 12, 15, 17, 19, 25);
59+
final int found = ArrayUtils.binarySearch(list, 9, Data::getValue, Integer::compare);
60+
assertEquals(5, found);
61+
}
62+
63+
@Test
64+
public void binarySearch_whenNotExists_returnMinusInsertion() {
65+
final Data[] list = createList(0, 1, 2, 4, 7, 9, 12, 15, 17, 19, 25);
66+
final int found = ArrayUtils.binarySearch(list, 8, Data::getValue, Integer::compare);
67+
assertEquals(-6, found);
68+
}
69+
70+
@Test
71+
public void binarySearch_whenNotExistsBeginning_returnMinus1() {
72+
final Data[] list = createList(0, 1, 2, 4, 7, 9, 12, 15, 17, 19, 25);
73+
final int found = ArrayUtils.binarySearch(list, -3, Data::getValue, Integer::compare);
74+
assertEquals(-1, found);
75+
}
76+
77+
@Test
78+
public void binarySearch_whenNotExistsEnd_returnMinusLength() {
79+
final Data[] list = createList(0, 1, 2, 4, 7, 9, 12, 15, 17, 19, 25);
80+
final int found = ArrayUtils.binarySearch(list, 29, Data::getValue, Integer::compare);
81+
assertEquals(-(list.length + 1), found);
82+
}
83+
84+
@Test
85+
public void binarySearch_whenUnsorted_dontInfiniteLoop() {
86+
final Data[] list = createList(7, 1, 4, 9, 11, 8);
87+
final int found = ArrayUtils.binarySearch(list, 10, Data::getValue, Integer::compare);
88+
}
89+
90+
private Data[] createList(int... values) {
91+
return IntStream.of(values).mapToObj(Data::new)
92+
.toArray(Data[]::new);
93+
}
94+
95+
static class Data {
96+
97+
private final int value;
98+
99+
Data(int value) {
100+
this.value = value;
101+
}
102+
103+
public int getValue() {
104+
return value;
105+
}
106+
}
107+
}

0 commit comments

Comments
 (0)