documentcloud/underscore — pull request #563 by kevinoid (2012-04-19 17:21:43+00:00)
Title: Tighten specification for _.sortedIndex

It would be useful if _.sortedIndex specified that it returns the lowest index, rather than any index, at which the value should be inserted into the list in order to maintain the list's sorted order. This is how the current implementation behaves, but it requires users to either read the source to determine this behavior (and rely on the implementation not changing this behavior) or handle the case that this behavior may change.

The primary use case that I envision, and the one which prompted me to make this suggestion, is maintaining a sorted list of unique elements. If _.sortedIndex is not guaranteed to return the lowest index at which value may be inserted, the insert process must check both the value at the index it returns and the value at the next smaller index (if one exists) for a duplicate element (for the case that _.sortedIndex would insert the value after its duplicate).

This pull also adds a test for this behavior.

Note: It would also be important to change the documentation on the website, but I did not see that available on github, so it is not included in this (or a related) pull.

Thanks!