Proposal Details

Currently the documentation of slices.BinarySearch says:

// BinarySearch searches for target in a sorted slice and returns the position
// where target is found, or the position where target would appear in the
// sort order; it also returns a bool saying whether the target is really found
// in the slice. The slice must be sorted in increasing order.
func BinarySearch[S ~[]E, E cmp.Ordered](x S, target E) (int, bool) {

To me, it is not clear what is returned if the target exists multiple times in x. It seems (looking at the implementation) it always returns the index of first appearance, which would be logical, and a good feature, but I cannot 100% infer this from the documentation.

Issued this as a issue as for now I have to assume that it can return any index of an element with target value, as I don't know if the current behaviour is incidental or guaranteed.