Document why unwraps won't fail

[shssoichiro]

Closes #42

[KodrAus]

Thanks @shssoichiro! This looks good to me.

[KodrAus]

Thanks @shssoichiro! This looks good to me.

[brson]

r? @BurntSushi

[BurntSushi]

Hmm. I don't think this is right. While we do actually guarantee that self.ops.max_open is greater than 0, that doesn't seem to have anything to do with this unwrap. In particular, this unwrap is just making sure that we don't overflow the oldest_opened state, which is a usize. It's not technically a bug in walkdir if this trips, but it's more like an error case that really can't happen in practice. In particular, it would require descending into a directory that has a depth greater than the maximum size of a usize on the current platform.

Arguably, one might want to turn this into a real error, but it doesn't seem worth it to me. I think we should just add a comment that basically says what I said above and call it a day. What do you think?

[shssoichiro]

If walkdir guarantees that self.ops.max_open is never 0, then I can update this comment to indicate that. However, I wrote it this way because, given the arithmetic in the if clause, the checked_add will never fail if self.ops.max_open is greater than 0. Granted, it's still unrealistic that that bound would ever be reached. So perhaps, yes, I can update the comment to just indicate that.

[shssoichiro]

Upon further thought, is there a reason this was written as a checked_add rather than just using + 1?

[BurntSushi]

Upon further thought, is there a reason this was written as a checked_add rather than just using + 1?

Because + 1 will silently overflow, which would be a silent bug.

But, you make a good point about the subtraction. Perhaps the right thing here is to change the if to self.stack_list.len().checked_sub(self.oldest_opened).unwrap() == self.ops.max_open and keep the checked_add. The comment can simply state that self.oldest_opened is guaranteed to never be greater than self.stack_list.len(), which implies that the subtraction won't underflow and that adding 1 will never overflow.

[shssoichiro]

That sounds good, I went ahead and pushed these changes up.

[BurntSushi]

@shssoichiro Fantastic. Thanks so much!