Document number:   P1650R0
Date:   2019-05-25
Audience:   Library Evolution Working Group
Reply-to:  
Tomasz KamiƄski <tomaszkam at gmail dot com>

Output std::chrono::days with 'd' suffix

1. Introduction

This paper proposes to use dedicated 'd' suffix when outputing std::chrono::days (e.g. '10d'), instead of relying on generic version (e.g. '10[86400]s').

Before After
std::cout << (sys_days{2018y/January/18} - sys_days{2018y/January/8});
// Prints: 10[86400]s
std::cout << (sys_days{2018y/January/18} - sys_days{2018y/January/8});
// Prints: 10d

Changes proposed in this paper need to be considered in the C++20 timeline, as they would constitute breaking change after the publication of standard in the current form.

2. Revision history

2.1. Revision 0

Initial revision.

3. Motivation and Scope

Streaming an std::chorono::duration specialization to the standard stream, output a number followed by this unit suffix. Currently the standard defines a set of the predefined suffixes ('h', 'min', 's', 'ns') and generic suffixes in form of '[N]s' for an integral number of seconds, and '[N/M]s' for fractional ratios of seconds.

The predefined set of units includes seconds ('s') and its derivative units ('Ks', 'ns', 'ms'), and additional time units that are allowed to be used with International System of Units: minutes ('min') and hours ('h'). This paper proposes to extend this set to cover days unit ('d').

This paper is not proposing a suffix for std::chrono::years or std::chrono::months, as these concepts do not represent standardized and static time intervals.

3.1. Surprising output

Standard overloads of the stream operations for the duration are intended to be used for the quick debugging logging purposes. However, with the current configuration the user that checks the result of the difference of the dates (in serialized representation), like:

std::cout << (floor<days>(system_clock::now()) - sys_days(1970y/January/01d);

Will be presented with '18035[86400]s' output, which is mildly surprising in first contact (the generic from is not used for other commonly occurring units minutes, seconds and milliseconds). With the change proposed in this paper, `18035d` will be produced instead.

3.2. Standardized and widely used

Days and the 'd' suffix is one of the time units (in addition to minutes and hours) that is not part international system of units, that is accepted but the International Committee for Weights and Measures to be used with SI, due is importance and common usage.

3.3. Drawbacks

For completeness the author would like to note that the change, has two minor drawbacks:

The 'd' suffix for 'std::chrono::days' (duration) is inconsistent with the d User Defined Literal, that produces 'std::chrono::day' (day of month). This paper does not propose any change is this regard, as the 'std::chrono::day' class is used more frequently (e.g. to produce date literals like 2018y/March/20d).

Secondly, proposed literal 'd' for days, may be confused with existing 'ds' (deciseconds) suffix. However, the changes of such problem occurring in practice are limited by infrequent usage of the second unit.

4. Proposed Wording

The proposed wording changes refer to N4810 (C++ Working Draft, 2019-03-15).

Add following additional item to the list in [time.duration.io] p2:

The units suffix depends on the type Period::type as follows:
  • [ ... ]
  • Otherwise, if Period::type is ratio<3600>, the suffix is "h".
  • Otherwise, if Period::type is ratio<86400>, the suffix is "d".
  • Otherwise, if Period::type::den == 1, the suffix is "[num]s".
  • Otherwise, the suffix is "[num/den]s".

Update the value of the __cpp_lib_chrono in table "Standard library feature-test macros" of [support.limits.general] to reflect the date of approval of this proposal. [ Note: The intention is to use the same feature test macro as P1466: Miscellaneous minor fixes for chrono. ]

5. Implementability

This change was already implemented in Howard's Hinnant Date library.

6. Acknowledgements

Howard Hinnant, and participants of C++ User Group Krakow meeting provided invaluable feedback on this change.

Special thanks and recognition goes to Sabre (http://www.sabre.com) for supporting the production of this proposal and author's participation in standardization committee.

7. References

  1. The NIST Reference on Constatns, Units and Uncertainty: Units outside of the SI, (https://physics.nist.gov/cuu/Units/outside.html)
  2. Howard E. Hinnant, Date library, (https://github.com/HowardHinnant/date)
  3. Howard E. Hinnant, Miscellaneous minor fixes for chrono, (P1466, https://wg21.link/P1466)
  4. Richard Smith, "Working Draft, Standard for Programming Language C++" (N4810, https://wg21.link/n4810)