Chapter 4 `partial_sort` section could be a bit clearer

I totally understand and support the idea of keeping Alex's idiomatic way of speaking, but I wonder if a little clarification would help in the partial_sort section of chapter 4. It says:

std::partial_sort

For example, you give it 100 elements and you sort from 1st to the 10th to the last. But, for the last 90 elements there is no guarantee. Those of you who work on search, know you don't really need to sort everything, you just need to sort a little bit.

The video section corresponding to this is at https://youtu.be/VelLby6K2jQ?t=1305

Alex does mention that partial_sort takes 3 iterators, which is not reflected in the text.
On it's own, "you sort from 1st to the 10th to the last" is not very clear. I know it's exactly what he said, but of course the text lacks the context and the hand gestures from the video.
It is one of the speakers who says "for the last 90 elements there is no guarantee.". Alex corrects him and points out there is a guarantee that the last 90 elements will appear in some order
Alex also mentions that partial_sort can be used as a complete sort.

I don't know what your policy is for putting words in Alex's mouth, but I wonder if something like the following would be clearer?

std::partial_sort

partial_sort takes 3 iterators as parameters. For example, you give it 100 elements and you pass iterators to the 1st, 11th and last+1 elements. The smallest ten elements will be moved to the front in sorted order. But for the last 90 elements the only guarantee is that they will appear in some order. Those of you who work on search, know you don't really need to sort everything, you just need to sort a little bit. You can use partial_sort as a complete sort by setting the second argument the same as the third, but it won't be as efficient as sort.

I'm not convinced it's reasonable (and I know my suggested text is super clunky as it stands), which is why I've raised an issue instead of a PR. Perhaps a footnote would be better?

Here are a few thoughts:

In general I think it's OK to add to the exposition when things are not clear. Clarifications are good. If possible, I would try to order them to either lead with Alex's words, or lead with yours, then follow them up. For example:

What's the interface? It takes three iterators first, middle, and last. What does it do? It orders the elements so that first to middle contains the smallest elements from the entire range. Then it sorts those first elements.

The first three lines are his, mine are the implied response.

last is poorly named because it's one beyond the end, as you mentioned. However, this is a standard convention and all STL interfaces use the [first, last) idiom. So we should use last to refer to the iterator past the end of the range.

I have made a PR which I will ping you on.

justinmeiners / efficient-programming-with-components

Chapter 4 `partial_sort` section could be a bit clearer #16

For example, you give it 100 elements and you sort from 1st to the 10th to the last. But, for the last 90 elements there is no guarantee. Those of you who work on search, know you don't really need to sort everything, you just need to sort a little bit.