diff --git a/Examples-and-Recipes.md b/Examples-and-Recipes.md index 990beed..e886d89 100644 --- a/Examples-and-Recipes.md +++ b/Examples-and-Recipes.md @@ -28,6 +28,7 @@ This page contains examples and recipes contributed by community members. Feel f - [How to convert to/from Windows' FILETIME](#FILETIME) - [Print out a compact calendar for the year](#calendar) - [Parsing unambiguous date time inside daylight transition](#parse_daylight_transition) +- [`microfortnights`?! Are you serious?](#microfortnights) *** @@ -1608,6 +1609,44 @@ Once we have a string of form 2), give this sample code a try (thank you [Aaron] cout << format("%F %T %Ez", zt) << ' ' << zt.get_time_zone()->name() << '\n'; } + +### `microfortnights`?! Are you serious? +(by [Howard Hinnant](https://github.com/HowardHinnant)) + +Well, kind of. The point of this article is to illustrate that no matter how crazy your units of time are, this library can handle it, and with style. + +If you're dealing with quarter-second durations, or frame-durations of 1/60 second, or whatever, `` can build the duration, and this library can format it. And all with very little effort. Let's say that you've got a time point consisting of a month, day, year, hour, minute, and microfortnight, just how hard is that to format out into human-readable format?! + +Turns out not hard at all. + + #include "date.h" + #include + + using fortnights = + std::chrono::duration, + date::weeks::period>>; + + using microfortnights = + std::chrono::duration>; + + int + main() + { + using namespace date; + using namespace std::chrono; + std::cout << format("%F %T\n", sys_days{nov/29/2016} + 15h + 13min + microfortnights{35}); + } + +The first thing to do is build your `chrono::duration` that represents a `microfortnight`. This is best done by first building a `fortnight`, and then multiplying that by `std::micro`. This will build some weird `chrono::duration` with a period we don't really have to know, but turns out to be not that far off from a second. + +To specify a `sys_time` in terms of this weird unit, you just do the usual addition. But instead of adding `seconds` you add `microfortnights`. Now it turns out that a microfortnight is _exactly_ 1.2096 seconds (who knew?). But you don't have to concern yourself with this detail as long as you've correctly defined `fortnights` as 2 `weeks` as above, and `microfortnights` as a `std::micro` times `fortnights` as above. + +Now you can just blindly add `microfortnights{35}` to your year/month/day hh::min timestamp as shown above, and ask `format` to format it with `"%F %T"`. This will output the correct time stamp with fractional decimal seconds to exactly represent `microfortnights`: + + 2016-11-29 15:13:42.3360 + +If this library can do this so easily with something as crazy as `microfortnights`, it can handle your crazy time problem. ***