Super Issue: Release `v1.1`

[tcharding]

Super issue for releasing encoding functionality currently only available in pre-1.0 versions.

• Prepare master to be v1.1  #206
• Make the crate conform to the API guidelines #208
• Decide if there is stuff we want to make private
• Do the release PR: Release tracking PR: hex v1.1.0 #210
• Add examples to hex iterator constructors #241
• Get a concept ACK from Kix.

[tcharding]

@Kixunil mentioning you since you are the original author of this crate. Do you want to have any input into this release? Especially the third item.

[jamillambert]

API test already done. Added missing test in #231

[tcharding]

Thanks man, confirmed.

[Kixunil]

The reason I didn't want to expose the iterators yet is that I hoped we would improve them to support both &str and &[u8] inputs without too much duplicate work or performance issues. I'm not sure how urgent this is but I would at least want to discuss it.

I think I was thinking along the lines of:

pub struct HexDigitsIter<'a, Source: ?Sized>(/*whatever is there today*/, PhantomData<Source>);

impl<'a, Source> HexDigitsIter {
    fn new(input: &'a Source) -> Self where &'a Source: AsRef<&'a [u8]> {
         Self { iter: input.as_ref().chunks_exact(2) }
    }
}

And then in error handling know that we can soundly use core::str::from_bytes_unchecked when Source == str. Though this micro-optimziation might not be worth it at least in the beginning I'd like to have the API such that it could support it if we want to do it.

[apoelstra]

Currently the only public constructor of HexDigitsIter is from_pairs. I would be fine making this private and adding an extra generic to the object (which users would likely never notice, since users basically never care about the exact type of iterators).

I would suggest using a const IS_UTF8: bool rather than Source: ?Sized, which will (a) be way easier to branch on than the type of an unsized generic, and (b) would let us define a clean unsafe API for users to force the value if they know that their byte-slice is ascii or whatever.

[apoelstra]

Actually, on further review, this seems ridiculous. We never need to know whether the "original string" (if one even exists) is valid UTF-8, except as you say, in the hypothetical case that we expand our OddLengthStringError to contain the entire string.

But we can only do that by adding a lifetime to the error (API breaking) or by cloning the string (which will eat any performance gained by this micro-optimization).

And this does have a user cost: it means that if the user tries to do something like if condition { /* thing that makes a iter with one generic */ } else { /* thing that makes an iter with the other generic */ } then their code won't compile. Which is likely to happen exactly in the case that they might have either a string or a bytestring.

So this sounds like it will make the API permanently uglier for the sake of a microoptimization which is probably impossible in Rust.

[Kixunil]

I would suggest using a const IS_UTF8: bool

Yeah, that would've been better. I think I was thinking of picking one of them as the default, which wasn't well supported in older Rust versions but I'm not sure which should it be, so this is probably non-issue.

hypothetical case that we expand our OddLengthStringError to contain the entire string.

Well, another one is getting char instead of u8 but sure, that is ridiculous.

or by cloning the string (which will eat any performance gained by this micro-optimization).

We could have String -> Iterator function which I think might be useful regardless in which case there is no copying but I guess just having entirely different type for that is better. And that one might support the optimization.

The condition part can be solved by calling as_bytes but I could see it being annoying.

So I think I'm OK with keeping it as-is. I mainly didn't want this to be unmentioned.

[apoelstra]

I guess just having entirely different type for that is better

Yeah, I think so.

So I think I'm OK with keeping it as-is. I mainly didn't want this to be unmentioned.

Cool. I'll let @tcharding take a look before closing this.

[tcharding]

I believe there is a good argument to say that we can defer all this iterator thinking.

We proved already in the v1.0.0 release that there is only a small portion of this crate that is typically required to be used in the public API of downstream crates. That means we can do a v2.0.0 anytime since we can be confident that we can semver all the v1.0.0 stuff. And then any of the v1.1 stuff can be changed. So if/when we want to do this iterator stuff we can.

[tcharding]

BTW good to see you @Kixunil.