Introduce Array API

README.rst

@@ -118,6 +118,7 @@ You use it in the exact same way as before, except you pass in a byte string.
     >>> hamming_distance_bytes(b"\xde\xad\xbe\xef", b"\x00\x00\x00\x00")
     24
 
+
 We also provide a method for a quick boolean check of whether two hexadecimal strings
 are within a given Hamming distance.
 
@@ -129,10 +130,55 @@ are within a given Hamming distance.
     >>> check_hexstrings_within_dist("ffff", "0000", 2)
     False
 
-Similarly, ``hexhamming`` supports byte arrays via ``check_bytes_arrays_within_dist``, which has
-a similar API as ``check_hexstrings_within_dist``, except it expects a byte array. Additionally,
-it will check if any element of a byte array is within a specified Hamming Distance of another
-byte array.
+Similarly, ``hexhamming`` supports a quick byte array check via ``check_bytes_within_dist``, which has
+a similar API as ``check_hexstrings_within_dist``, except it expects a bytes array.
+
+The API described above is targeted at comparing two individual records and calculating their hamming distance quickly.
+For many applications the goal is to compare a given record to an array of other records and to find out if there
+are elements in the array that are within a given hamming distance of the search record. To support these application
+cases ``hexhamming`` has a set of array APIs. Given that these operations are often speed critical and require preparing data
+anyway, they are only available for bytes strings, not for hex strings.
+
+They all have the same signature, they take two bytes arrays and the ``max_dist`` to consider. The difference is, that the first
+bytes string should be a concatenation of a number of records to compare to, i.e. the length needs to be a multiple of the length
+of the second bytes string.
+
+There are three functions that return different results, depending on what is needed by the application.
+
+``check_bytes_arrays_first_within_dist`` returns the index of the first element that has a hamming distance less than ``max_dist``.
+
+::
+
+    >>> from hexhamming import check_bytes_arrays_first_within_dist
+    >>> check_bytes_arrays_first_within_dist(b"\xaa\xaa\xbb\xbb\xcc\xcc\xdd\xdd\xee\xee\xff\xff", b"\xff\xff", 4)
+    1
+
+
+``check_bytes_arrays_best_within_dist`` returns a tuple with the distance and the index of the element that has the lowest hamming
+distance less than ``max_dist``, or ``(-1,-1)`` if none do.
+
+::
+
+    >>> from hexhamming import check_bytes_arrays_best_within_dist
+    >>> check_bytes_arrays_best_within_dist(b"\xaa\xaa\xbb\xbb\xcc\xcc\xdd\xdd\xee\xee\xff\xff", b"\xff\xff", 4)
+    (0, 5)
+
+    >>> check_bytes_arrays_best_within_dist(b"\xaa\xaa\xbb\xbb\xcc\xcc\xdd\xdd\xee\xee\xff\xff", b"\xef\xfe", 4)
+    (2, 4)
+
+
+``check_bytes_arrays_all_within_dist`` returns a list of tuples with the distance and the index of the element that have a hamming
+distance less than ``max_dist``, or ``[]`` if none do.
+
+::
+
+    >>> from hexhamming import check_bytes_arrays_all_within_dist
+    >>> check_bytes_arrays_all_within_dist(b"\xaa\xaa\xbb\xbb\xcc\xcc\xdd\xdd\xee\xee\xff\xff", b"\xff\xff", 4)
+    [(4, 1), (4, 3), (4, 4), (0, 5)]
+
+
+Tip: When you're assembling the long array of records to compare against, don't concatenate the different ``bytes`` together. As they're
+immutable that is a very slow operation. Use a ``bytearray`` instead, and cast it to ``bytes`` at the end. See https://www.guyrutenberg.com/2020/04/04/fast-bytes-concatenation-in-python/ for more info and tests.
 
 Benchmark
 ---------

setup.py

@@ -33,7 +33,7 @@
             name="hexhamming",
             sources=["src/python_hexhamming.cc"],
             extra_compile_args=extra_compile_args,
-            language="c++11",
+            language="c++",
         )
     ],
 )