Mdf performance and docs

[pitdicker]

The Mdf types reason for existence is to have a way to convert between ordinal dates and month-day dates efficiently. It is a core part of the performance of chrono, we use it internally all over the place. Before converting it to return Results in the 0.5 branch I need a benchmark to not materially regress its performance.

Turns out I already regressed it by ca. 25% (at least according to the new benchmark) since chrono 0.4.24 😱.
After the benchmark in the first commit, the next three commits recover this lost performance by reverting needless checks:

• Make functions in internals const #1043 introduced checks in Mdf::new that are also covered by the table lookup Mdf exists for.
• Refactor internals module part 4 #1432 tries to make NaiveDate::from_mdf share code with NaiveDate::from_ordinal_and_flags. It looks clean, but that introduces a bunch of unneeded checks. I added a dedicated method Mdf::ordinal_and_flags and made NaiveDate::from_mdf use that.
• Use NonZeroI32 inside NaiveDate #1207 introduced a useless check against zero with NonZeroI32::new.

Then there are two commits that improve the performance a little bit more.
And while working on it I wrote some doc comments for the methods on Mdf.

Benchmark results

Chrono 0.4.24

bench_date_from_ymd     time:   [4.3541 ns 4.3737 ns 4.3958 ns]

Before

bench_date_from_ymd     time:   [5.5149 ns 5.5508 ns 5.5919 ns]

After

bench_date_from_ymd     time:   [4.2512 ns 4.2572 ns 4.2637 ns]

---

I have the commits that extend this PR to convert an Mdf to return Results ready, but would like to base them on this PR to the main branch.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (4d4ff14) 91.85% compared to head (81a52a9) 91.86%.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1438   +/-   ##
=======================================
  Coverage   91.85%   91.86%           
=======================================
  Files          40       40           
  Lines       17469    17471    +2     
=======================================
+ Hits        16046    16049    +3     
+ Misses       1423     1422    -1     

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

[pitdicker]

I rebased the documentation commit to be earlier in the PR, that should make reviewing a bit easier.

And there was one commit I had left after the internals refactor that makes the constants used in YearFlags less magical and updates the documentation. It kind of seems to fit in with this PR (as the other half of this file).

[pitdicker]

Nice, thank you!