Ensure usage from correct logic will never panic: use Result where appropriate, otherwise document correct usage

[marshallpierce]

This will make it possible to guarantee panic-free codepaths.

Optionally, we might expose ways to record, read, that can panic but do not require the Result syntactic overhead.

[jonhoo]

Implementing AddAssign already sort-of gives us the latter, but having named methods for this as well would probably also be a good addition.

[marshallpierce]

On further consideration, I'm not sure that a blanket "use Result everywhere" policy is actually beneficial. The potential overflow in value_for, for instance, isn't necessarily useful to expose with a Result since you will only encounter an Err if your logic is wrong and you iterate too far. As an example, what about an iterator implementation that is correctly implemented? It will have Result-handling code that is never going to hit error cases unless it has incorrect logic that tries to iterate too far.

I think a more useful goal would be something like:

• Use Result where valid logic can still encounter an overflow, etc, error
• In places that will always succeed unless a programmer error is made, carefully document what the result will be (e.g. "if the input cannot be represented in a u64, the result will be garbage, but it will not panic"). This means using wrapping_shl and friends to make that behavior more explicit.

[jonhoo]

Yeah, you're right, that seems like a reasonable plan.

[marshallpierce]

Potential panic? https://github.com/jonhoo/hdrsample/pull/34/files#diff-b4aea3e418ccdb71239b96952d9cddb6R1559

[jonhoo]

Closing now that #55 has been merged. #38 is still a concern, but that's tracked, well, in #38.