`encode_engine_slice` should probably return a `&str` instead of `usize`

[upsuper]

I suggest that encode_engine_slice should have a signature like

pub fn encode_engine_slice<'a, E: Engine, T: AsRef<[u8]>>(
    input: T,
    output_buf: &'a mut [u8],
    engine: &E
) -> &'a mut str;

Apparently the encoded result is always a valid string, but the current API leaves a dilemma for some users:

• encode_engine: provides convenient str but allocates,
• use encode_engine_slice: doesn't allocate but doesn't provide str
  • which means you either need to run a meaningless check, or use an unsafe.

If encode_engine_slice can return a str, that dilemma would be resolved. The length can still be derived from .len() of the returned str.

There is also a precedent in the Rust std: char::encode_utf8 encodes into a buffer and returns a str.

This is a breaking change, though.

[marshallpierce]

Unfortunately this isn't really viable as far as I can tell.

• This library doesn't use unsafe, so doing str::from_utf8_unchecked for the user is out.
• Doing the check safely for all users is also not a great idea, as it's unneeded overhead for users that don't care.
• char::encode_utf8 isn't very helpful in this case. While we could conceivably create a mapping of base64 tokens to chars and then use that, it's variable length, which would destroy the performance of encoding.

[upsuper]

It seems that encode_engine already does a UTF-8 check on the output.

I wonder if I can build a crate around ASCII chars which exposes a safe API to construct ASCII strings, would you accept a PR making use of that to eliminate the checks?

[Nugine]

base64_simd::Base64::encode_as_str is exactly what you want. base64-simd also supports encoding/decoding with an uninitialized buffer, which is relatively difficult for a 100%-safe library.

[upsuper]

@Nugine That looks great. I'll give it a try. Thanks!