AK: Add a BinarySearch template implementation

binary_search takes a haystack, a size, a needle and a compare function.
The compare function should return negative if a < b, positive if a > b
and 0 if a == b. The "sane default" compare function is integral_compare
which implements this with subtraction a - b.
binary_search returns a pointer to a matching element, NOT necessarily
the FIRST matching element. It returns a nullptr if the element was not
found.

This patch includes tests for binary_search.

AK/BinarySearch.h

@@ -0,0 +1,32 @@
+#pragma once
+
+namespace AK {
+
+template<typename T>
+int integral_compare(const T& a, const T& b)
+{
+    return a - b;
+}
+
+template<typename T, typename Compare>
+T* binary_search(T* haystack, size_t haystack_size, const T& needle, Compare compare = integral_compare)
+{
+    int low = 0;
+    int high = haystack_size - 1;
+    while (low <= high) {
+        int middle = (low + high) / 2;
+        int comparison = compare(needle, haystack[middle]);
+        if (comparison < 0)
+            high = middle - 1;
+        else if (comparison > 0)
+            low = middle + 1;
+        else
+            return &haystack[middle];
+    }
+
+    return nullptr;
+}
+
+}
+
+using AK::binary_search;

AK/Tests/Makefile

@@ -1,4 +1,4 @@
-PROGRAMS = TestAtomic TestString TestQueue TestVector TestHashMap TestJSON TestWeakPtr TestNonnullRefPtr TestRefPtr TestFixedArray TestFileSystemPath TestURL TestStringView TestUtf8 TestCircularQueue
+PROGRAMS = TestBinarySearch TestAtomic TestString TestQueue TestVector TestHashMap TestJSON TestWeakPtr TestNonnullRefPtr TestRefPtr TestFixedArray TestFileSystemPath TestURL TestStringView TestUtf8 TestCircularQueue
 
 CXXFLAGS = -std=c++17 -Wall -Wextra -ggdb3 -O2 -I../ -I../../
 
@@ -25,6 +25,9 @@ endef
 all: $(PROGRAMS)
 	$(foreach x,$(PROGRAMS),$(call execute-command,./$(x)))
 
+TestBinarySearch: TestBinarySearch.o $(SHARED_TEST_OBJS)
+	$(PRE_CXX) $(CXX) $(CXXFLAGS) -o $@ TestBinarySearch.o $(SHARED_TEST_OBJS)
+
 TestAtomic: TestAtomic.o $(SHARED_TEST_OBJS)
 	$(PRE_CXX) $(CXX) $(CXXFLAGS) -o $@ TestAtomic.o $(SHARED_TEST_OBJS)
 

AK/Tests/TestBinarySearch.cpp

@@ -0,0 +1,82 @@
+#include <AK/TestSuite.h>
+
+#include <AK/BinarySearch.h>
+
+TEST_CASE(vector_ints)
+{
+    Vector<int> ints;
+    ints.append(1);
+    ints.append(2);
+    ints.append(3);
+
+    auto test1 = *binary_search(ints.data(), ints.size(), 1, AK::integral_compare<int>);
+    auto test2 = *binary_search(ints.data(), ints.size(), 2, AK::integral_compare<int>);
+    auto test3 = *binary_search(ints.data(), ints.size(), 3, AK::integral_compare<int>);
+    EXPECT_EQ(test1, 1);
+    EXPECT_EQ(test2, 2);
+    EXPECT_EQ(test3, 3);
+}
+
+TEST_CASE(array_doubles)
+{
+    double doubles[] = { 1.1, 9.9, 33.33 };
+
+    auto test1 = *binary_search(doubles, 3, 1.1, AK::integral_compare<double>);
+    auto test2 = *binary_search(doubles, 3, 9.9, AK::integral_compare<double>);
+    auto test3 = *binary_search(doubles, 3, 33.33, AK::integral_compare<double>);
+    EXPECT_EQ(test1, 1.1);
+    EXPECT_EQ(test2, 9.9);
+    EXPECT_EQ(test3, 33.33);
+}
+
+TEST_CASE(vector_strings)
+{
+    Vector<String> strings;
+    strings.append("bat");
+    strings.append("cat");
+    strings.append("dog");
+
+    auto string_compare = [](const String& a, const String& b) -> int {
+        return strcmp(a.characters(), b.characters());
+    };
+    auto test1 = *binary_search(strings.data(), strings.size(), String("bat"), string_compare);
+    auto test2 = *binary_search(strings.data(), strings.size(), String("cat"), string_compare);
+    auto test3 = *binary_search(strings.data(), strings.size(), String("dog"), string_compare);
+    EXPECT_EQ(test1, String("bat"));
+    EXPECT_EQ(test2, String("cat"));
+    EXPECT_EQ(test3, String("dog"));
+}
+
+TEST_CASE(single_element)
+{
+    Vector<int> ints;
+    ints.append(1);
+
+    auto test1 = *binary_search(ints.data(), ints.size(), 1, AK::integral_compare<int>);
+    EXPECT_EQ(test1, 1);
+}
+
+TEST_CASE(not_found)
+{
+    Vector<int> ints;
+    ints.append(1);
+    ints.append(2);
+    ints.append(3);
+
+    auto test1 = binary_search(ints.data(), ints.size(), -1, AK::integral_compare<int>);
+    auto test2 = binary_search(ints.data(), ints.size(), 0, AK::integral_compare<int>);
+    auto test3 = binary_search(ints.data(), ints.size(), 4, AK::integral_compare<int>);
+    EXPECT_EQ(test1, nullptr);
+    EXPECT_EQ(test2, nullptr);
+    EXPECT_EQ(test3, nullptr);
+}
+
+TEST_CASE(no_elements)
+{
+    Vector<int> ints;
+
+    auto test1 = binary_search(ints.data(), ints.size(), 1, AK::integral_compare<int>);
+    EXPECT_EQ(test1, nullptr);
+}
+
+TEST_MAIN(BinarySearch)