As per Rust API guidelines:

Crate names should not use -rs or -rust as a suffix or prefix. Every crate is Rust! It serves no purpose to remind users of this constantly.

niceware is not taken yet, so just renaming and re-publishing should be fine. Perhaps consider yanking the old crates (see cargo yank).

The function argument is now clearly named num_random_bytes but that didn't stop me from making a mistake in the example.

Before I go ahead and fix it, I wonder if any of these approaches is better:

• Changing it to number of words. If someone makes a mistake it at least leads to too good security instead of worse security. (Note that too many words is still bad. Also note it has nice property that it never panics due to odd count.)
• have both fn generate_passphrase_with_entropy_bytes() and fn generate_passphrase_with_word_count() to disambiguate and perhaps make the code cleaner
• enum Entropy { Words(u16), Bytes(u16), } and then take that enum instead.
• struct WordCount(u16); and struct ByteCount(u16); with sealed trait Entropy. This is probably overengineered with the advantage that ByteCount could enforce even number in constructor.

Found your crate on reddit and thought that I could make a PR as the best kind of review. :)

This makes various improvements to the code to make it more idiomatic and performant. I split them to somewhat smaller pieces that can be described more easily - see individual commit messages. One of them is quite big as it made significant changes, hope it's clear though. LMK if you don't understand something.

I've refactored both of the current error types into a new Error type and removed all sources of panics. This is to make the functions better match the constraints of the type system (e.g., bytes_to_pass_phrase can take any &[u8], but some of them are invalid). Also, I've changed num_words to be a usize; representing it as a u16 is mostly an implementation detail, since the real size check is done against MAX_PASSPHRASE_WORDS.

This changes generate_passphrase from taking number of bytes to taking number of words which is more natural and avoids panic. It also "fixes" documentation saying that calling the function with parameter 8 generates 128 bits of entropy. (That now becomes true statement.)

Closes #5

We don't need ownership of Vec buffers in bytes_to_passphrase and passphrase_to_bytes.

The arg to generate_passphrase can be named clearer to show it takes a random number of bytes.

Don't expose ring's error type. Wrap it with the new RNGError to enable us to swap RNG crates in the future.

This adds BytesToPassPhraseIter which implements Iterator and related traits. This should make it possible to perform the conversion without allocations.

Part of #6

Instead of taking/returning slice/Vec<...> the functions could take impl Iterator<Item=[u8; 2]>/return impl Iterator<Item=...> so that callers that don't need Vec do not need to allocate at all. (E.g. this is the case if the user wants to just write out the passphrase.) Requiring Item=[u8; 2] also side steps the evenness check completely.

I think with these adjustments it should be possible to make whole crate allocation-free. The current methods can be kept for backwards compatibility or as helpers for people who don't want to mess with iterators

Inspecting specific word that is unknown may be useful to some callers but adding a method to retrieve it basically commits to always storing it within error type. I think it's very reasonable to expect that it will always be there but opened an issue just in case. The suggested method is:

/// The word that is not known
fn word(&self) -> &str {
    &self.word
}

An alternative would be to continue scanning the words even after error and return a slice of all unknown words.