Create FS-1135-map-binary-search.md

[reinux]

Rendered RFC

[dsyme]

@KevinRansom @vzarytovskii @abelbraaksma Comments on this please?

[T-Gro]

@reinux :

I am still thinking of a better self-explainable API, I don't think a tuple of 3 with same types is best. Even though the ordering (previous,match,next) is likely the most natural one here.

Just to show another proposal, I have tried to DU-model the outcomes, but I do not think it is any better to your proposal here. The number of possible combinations is an inherent part of binary search if we want this to be a primitive supporting all sorts of scenarios.

type Node<'TKey,'TValue> = (struct ('TKey * 'TValue))

[<Struct>]
type MapPosition<'a,'b> =  
    | Between of below:Node<'a,'b> * above:Node<'a,'b>
    | AtMinimum of above:Node<'a,'b>
    | AtMaximum of below:Node<'a,'b>
    | MapWasEMpty

[<Struct>]
type BinarySearchResult<'a,'b> =
    | ExactMatch of hit:Node<'a,'b> * position:MapPosition<'a,'b> 
    | NotFound of  position:MapPosition<'a,'b> 

[Martin521]

I like the functionality and the API.
I am not sure about the name. "Binary search" is a well defined algorithm for arrays with a single return value.
Just Map.search? Map.tryFindWithNeighbors?

[reinux]

I like the functionality and the API. I am not sure about the name. "Binary search" is a well defined algorithm for arrays with a single return value. Just Map.search? Map.tryFindWithNeighbors?

The more I think about it, the more I'm liking Map.search. Even if I could validly argue that it's a special case of binary search (and I'm starting to have doubts), you probably wouldn't be the only one raising an eyebrow.

search is a nice, short name, and the return type, whatever we end up landing on, will do a fine job describing what it does anyway.

As for the return type, I think the only option we haven't explored yet is a single-case union with named parameters:

type MapSearchResult<'k, 'v> =
  MapSearchResult of left: ('k, 'v) option * exact: ('k, 'v) option * right: ('k, 'v) option

This would effectively be the same as the tuple version, except that we'd be trading conciseness with some IDE assistance.

I'm likewise unsure whether this is the best approach either.