Add StrftimeItems::{parse, parse_to_owned} and more documentation

[pitdicker]

Adds StrftimeItems::parse and StrftimeItems::parse_to_owned.

parse returns Vec<Item<'_>> and can return an error if the format string is invalid.

With the new formatting API the Vec hopefully gets more use, and then it may become difficult that is contains references to the format string. That is what the OwnedLiteral and OwnedSpace variants of Item are for, but we had no easy way to make those.
parse_to_owned returns Vec<Item<'static>>.

And I added some documentation and doctests.

[jtmoon79]

Nice.

[codecov]

Codecov Report

Attention: 19 lines in your changes are missing coverage. Please review.

Comparison is base (58f1f37) 93.41% compared to head (31db358) 91.87%.
Report is 56 commits behind head on main.

❗ Current head 31db358 differs from pull request most recent head ccde6a2. Consider uploading reports for the commit ccde6a2 to get more accurate results

Files	Patch %	Lines
src/naive/datetime/mod.rs	66.66%	6 Missing ⚠️
src/datetime/mod.rs	86.95%	3 Missing ⚠️
src/format/mod.rs	70.00%	3 Missing ⚠️
src/format/strftime.rs	97.67%	2 Missing ⚠️
src/month.rs	0.00%	2 Missing ⚠️
src/duration.rs	99.69%	1 Missing ⚠️
src/offset/utc.rs	0.00%	1 Missing ⚠️
src/weekday.rs	0.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1184      +/-   ##
==========================================
- Coverage   93.41%   91.87%   -1.55%     
==========================================
  Files          34       38       +4     
  Lines       16754    17614     +860     
==========================================
+ Hits        15651    16182     +531     
- Misses       1103     1432     +329     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[djc]

Instead of first collecting and then iterating again to find Error values, we can do both in one iteration by relying on the FromIter implementation for Result. Something like this:

self.into_iter().map(|item| match item == Item::Error {
    false => Ok(item),
    true => Err(BAD_FORMAT),
}).collect()

[pitdicker]

Cool, thank you!

[djc]

Here, too: why should this be added to the public API? What use case does it address that is currently underserved?

[pitdicker]

The Vec returned by StrftimeItems::parse borrows from the input string. While we have items that can take owned strings they were really not easy to use, or even discover.
Somewhat suggested in #852 (comment) (#1183).

[pitdicker]

This is a smallish PR that improves the documentation of StrftimeItems and adds two methods to make it easier to re-use its result: parse and parse_to_owned.

@djc you already reviewed a lot the past few days, but how to you feel about getting this one over the finish line? Also because you already gave it one round of review.

[djc]

"unrecognised" -> "unrecognized".

[djc]

Here, too.