DistinctBy documentation is misleading


#1

The DistinctBy documentation https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/distinct-by.html says ‘Returns a list containing only elements from the given array having distinct keys returned by the given [selector]’

It should say “returns the first element in the list for every computed value of the selector”:

>>> listOf("aa", "ab", "bc").distinctBy{ it[0] }
[aa, bc]

The current documentation says this example should only return “bc” because that’s the only entry with a distinct key.


#2

If you read the “having” as qualifying “a list “rather than “elements”, it acts as described. But “elements” is nearer, so I’d read it as you did, too. Rewriting would correct the docs: “Returns a list of elements drawn from the array. Each list element has a distinct key returned by the selector function.”

The docs may not wish to constrain the implementation to promising more than uniqueness by key; saying it must be the first such with that key may be a step too far.