BisectSearch util

[runeflobakk]

Adds a util for performing bisection search (or binary searches) on ordered sets of arbitrary objects. The objects can be generated as needed based on an ordered index (where it "would" appear in an ordered set of the objects), and as such does not need to be existing instances in memory in order to be searched.

---

A use case for this is to iteratively find a generated valid binary file of a
certain size, e.g. PDFs, images, etc, anything that can be translated
from an integer to an object retaining the same notion of "order" as the
integer it is based on.

Generating PDFs with random content using PDFBox:

PDDocument createPdf(int pages) {
    // generate PDDocument with the given amount of pages, filled with random content
}

...

import no.digipost.io.DataSize;
import no.digipost.util.bisect.BisectSearch;
import no.digipost.util.bisect.Suggestion;
import static no.digipost.util.bisect.Evaluator.size;

public static void main(String[] args) {
    PDDocument pdf512kb = BisectSearch
            .from(numberOfPages -> Suggestion.of(createPdf(numberOfPages)))
            .inRange(30, 500)
            .searchFor(size(DataSize.kB(512), PDDocument::save))
}

Each attempted (suggested) PDDocument will also be properly closed, being an AutoCloseable, except from the resulting PDDocument which is returned from the search. By default, the search will perform at most 20 attempts before returning its last attempt (unless found before).

Similarly, this utility could be used to translate points (a.k.a. the integer from the range) to X and Y pixel amount, given a fixed aspect ratio, and generate images with random content, and search for one with a certain size.

[velfundert]