Improved parser & diagnostics

[QnnOkabayashi]

I'm submitting a feature

Description

This features adds drastically improved diagnostics for error handling for the uuid!() macro. Improvements include not panicking on multibyte characters, and providing more human-oriented feedback on why a string failed to parse. For example, instead of complaining about an invalid length if the last group has one too many characters, it will tell you that the last group has one too many characters.

This PR also improves the parser implementation. It works by separating the parsing from error handling, allowing the parser to be a const fn that is heavily optimized and returns Option<[u8; 16]>, where the error handler can come along later and figure out exactly what went wrong if the user cares. This is because most of the time, it's likely that the user doesn't particularly care what went wrong because they aren't expecting it to fail.

Finally, it introduces the Uuid::try_parse method, which is intended to replace Uuid::parse_str. They do the same thing, except Uuid::parse_str will automatically diagnose the error with slight overhead in the case that it fails, where Uuid::try_parse just returns the lightweight error type, InvalidUuid, that can be diagnosed at a later time using InvalidUuid::into_err.

Related Issue(s)

#559
#556

[kinggoesgaming]

Would love to see the benchmarks on this

[QnnOkabayashi]

Would love to see the benchmarks on this

I'm not sure how to benchmark, but the implementation is a slightly modified version of the const-str impl.

#556 (comment)

[KodrAus]

I think @kinggoesgaming would be interested in the difference with main, and it looks like things do improve there:

main

test parse_invalid_character ... bench:          44 ns/iter (+/- 1)
test parse_invalid_group_len ... bench:          60 ns/iter (+/- 1)
test parse_invalid_groups    ... bench:          71 ns/iter (+/- 1)
test parse_invalid_len       ... bench:          10 ns/iter (+/- 0)
test parse_nil               ... bench:          63 ns/iter (+/- 3)
test parse_nil_hyphenated    ... bench:          65 ns/iter (+/- 2)
test parse_random            ... bench:          56 ns/iter (+/- 3)
test parse_random_hyphenated ... bench:          65 ns/iter (+/- 2)
test parse_urn               ... bench:          67 ns/iter (+/- 2)

This PR

test parse_invalid_character ... bench:          47 ns/iter (+/- 0)
test parse_invalid_group_len ... bench:          55 ns/iter (+/- 0)
test parse_invalid_groups    ... bench:          62 ns/iter (+/- 0)
test parse_invalid_len       ... bench:          58 ns/iter (+/- 0)
test parse_nil               ... bench:          30 ns/iter (+/- 0)
test parse_nil_hyphenated    ... bench:          31 ns/iter (+/- 0)
test parse_random            ... bench:          30 ns/iter (+/- 0)
test parse_random_hyphenated ... bench:          31 ns/iter (+/- 0)
test parse_urn               ... bench:          32 ns/iter (+/- 0)

[KodrAus]

Thanks for working on this @QnnOkabayashi! This looks good to me 🚀

[kinggoesgaming]

I think @kinggoesgaming would be interested in the difference with main, and it looks like things do improve there:

main

test parse_invalid_character ... bench:          44 ns/iter (+/- 1)

test parse_invalid_group_len ... bench:          60 ns/iter (+/- 1)

test parse_invalid_groups    ... bench:          71 ns/iter (+/- 1)

test parse_invalid_len       ... bench:          10 ns/iter (+/- 0)

test parse_nil               ... bench:          63 ns/iter (+/- 3)

test parse_nil_hyphenated    ... bench:          65 ns/iter (+/- 2)

test parse_random            ... bench:          56 ns/iter (+/- 3)

test parse_random_hyphenated ... bench:          65 ns/iter (+/- 2)

test parse_urn               ... bench:          67 ns/iter (+/- 2)

This PR

test parse_invalid_character ... bench:          47 ns/iter (+/- 0)

test parse_invalid_group_len ... bench:          55 ns/iter (+/- 0)

test parse_invalid_groups    ... bench:          62 ns/iter (+/- 0)

test parse_invalid_len       ... bench:          58 ns/iter (+/- 0)

test parse_nil               ... bench:          30 ns/iter (+/- 0)

test parse_nil_hyphenated    ... bench:          31 ns/iter (+/- 0)

test parse_random            ... bench:          30 ns/iter (+/- 0)

test parse_random_hyphenated ... bench:          31 ns/iter (+/- 0)

test parse_urn               ... bench:          32 ns/iter (+/- 0)

Yup this is exactly what I was thinking about. The couple of regressions are IMHO acceptable