Explain how Length.run_step works

[Zalathar]

This PR (hopefully) makes it easier to understand how Length.run_step works.

First it replaces j and i + 1 with more meaningful variable names, based on my interpretation of what's happening.

Then it adds an overall description of the shrinking process, step-by-step comments, and a diagram to put each variable and slice into context.

---

This is a stand-alone change that doesn't fix or change any behaviour, so there's no particular hurry to get it merged.

I recommend looking the variable-renaming commit on its own, because the combined diff makes it a bit harder to see that the new version is equivalent.

[DRMacIver]

I definitely like making this clearer! I've got two small comments:

• The name skipped isn't actually very obvious to me. It's certainly not one I would have chosen. Can you elaborate a little on why you chose that one?
• I think the explanation misses a crucial detail: Many of these elements past the current index could be ones that we can now delete, because running this pass once doesn't necessarily reach a fixed point. For example imagine a case where you started from [0, 1, 2] and the the interesting sequences were that, [0, 2], and [0]. When the first pass deletes the 1 the 2 is now deletable despite being to the right of the current index

[Zalathar]

The idea is that we are repeatedly trying to delete find_integer items from the end of a list.

But before doing so, we first “skip over” all of the rightmost items that we have previously failed to delete during this pass, delete items from the end of whatever remains, and then append all of the “skipped” items after the deleted items before considering the new candidate list.

Reusing your example, we would eventually skip over the stubborn [2] and try to delete items from the end of [0, 1]. After deleting the 1 and appending the skipped 2, our next candidate sequence is [0, 2], which we submit for consideration.

Eventually we find that 0 is also stubborn, so our skipped region contains 0 and 2. That’s now the entire sequence, so the pass ends.

[Zalathar]

(I’m not 100% on the name, because it doesn’t quite capture that we tried to delete each stubborn element before giving up and deciding to skip it for the remainder of the pass.)

[Zalathar]

Another way of looking at it is that in the original code, i is a cursor that moves backwards through the sequence, and j is an offset from the end of the sequence that helps keep the cursor in the right place after elements are deleted.

In the renamed code, j becomes skipped, which is the length of the subsequence to the right of the cursor. And i+1 becomes remaining, which is the length of the subsequence to the left of the cursor (plus the cursor itself).

These two lengths sum to the total length of the current sequence. When we take the slice start[:remaining - k], it should contain all of the elements eligible for deletion, minus the k elements actually being deleted. And start[remaining:] should contain all the elements that weren't eligible for deletion, i.e. the skipped elements that we've previously failed to delete.

(Ideally that latter slice would be start[-skipped:], but that doesn't work when skipped == 0, which I learned the hard way.)

[Zalathar]

Whoops, this reference to j no longer makes sense now that I've renamed the variables.

[Zalathar]

I tightened up some of the text, and moved the diagram into a “footnote” at the bottom of the file, so there's less of a wall-of-text effect when reading through the implementation from top to bottom.

I also changed remaining to candidates, indicating that it covers the elements that are still eligible candidates for deletion.

[Zac-HD]

Fantastic explanation - LGTM.