From c10b7292730acbe5c23f896a03dc27d74ab5e858 Mon Sep 17 00:00:00 2001 From: Howard Hinnant Date: Sat, 1 Apr 2017 22:25:28 -0400 Subject: [PATCH] Rewrite of the to_stream/format/from_stream/parse docs: * The bulk of the description is moved from tz.html to date.html. * The format and parse flags are now described in detail, instead of implicitly relying on the C and POSIX specs. This gives me room to specify a few corner cases that are either under-specified in the official specs, or to add extensions. * The from_stream / to_stream specifications are now located with each specific type that implements them. This allows more detailed documentation as to how each type interacts with the from_stream / to_stream system. * The format and parse functions are now more clearly separated from to_stream and from_stream, and are documented to be nothing more than syntax sugar on top of any type that choses to implement to_stream or from_stream. --- date.html | 1300 ++++++++++++++++++++++++++++++++++++++++++++++++++++- tz.html | 619 +++++++------------------ 2 files changed, 1438 insertions(+), 481 deletions(-) diff --git a/date.html b/date.html index b679dc7..f30c89c 100644 --- a/date.html +++ b/date.html @@ -26,7 +26,7 @@

Howard E. Hinnant
-2016-11-24
+2017-04-01

date

@@ -63,7 +63,7 @@ If you want detailed explanations of the algorithms, go there.

-It performs best with C++14, which has vastly improved constexpr rules. +It performs best with C++14, which has vastly improved constexpr rules. However, the library will auto-adopt to C++11, sacrificing several constexpr declarations. In C++11, this will effectively transfer some computations that should be done at compile-time to run-time. Porting to C++98/03 has not been attempted. @@ -1206,7 +1206,7 @@ That is, first find the first Thursday in January for year y, and t the number of days required to find the Monday before this day. This could have been done with days{3}. But I chose to code this as (thu-mon). Computationally and performance wise, these two choices are identical: they both subtract -the literal 3. I chose the latter because I believe it to be more readable. +the literal 3. I chose the latter because I believe it to be more readable. "3" is just a magic constant. But "(thu-mon)" is the number of days Thursday is past Monday.

@@ -1393,7 +1393,7 @@ limits()

I've included two extra units: picoseconds, and the units used by Visual Studio's system_clock::time_point. Units finer than picoseconds -do not work with this date library because the conversion factors needed to convert to +do not work with this date library because the conversion factors needed to convert to units such as days overflow the compile-time machinery. As a practical matter this is not important as the range of a 64 bit femtosecond is only about +/- 2.5 hours. On the other side, units coarser than hours, if represented by at @@ -1600,8 +1600,10 @@ operator<<(std::basic_ostream<CharT, Traits>& os, const local_ti    -Formatting and  -Parsing  +to_stream formatting  +format  +from_stream formatting  +parse  @@ -1664,7 +1666,7 @@ using years = std::chrono::duration 1/12 of a year. This definition accurately describes the length of the average month in the Gregorian calendar. months is the resultant type when subtracting two month field-based time points. months is -not implicitly convertible to days or weeks nor vice-versa. +not implicitly convertible to days or weeks nor vice-versa. months will not implicitly convert to years. 

@@ -1672,6 +1674,53 @@ using months = std::chrono::duration
     <int, std::ratio_divide<years::period, std::ratio<12>>>;
+

Formatting and parsing durations

+ +
+template <class CharT, class Traits, class Rep, class Period>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const std::chrono::duration<Rep, Period>& d);
+
+ +
+

+Effects: Inserts d, converted to the +common_type<duration, seconds> into os using the format +string fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%H, %I, %M, %p, %r, +%R, %S, %T, %X, %n, +%t or %%. +

+
+ +
+template <class Rep, class Period, class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            std::chrono::duration<Rep, Period>& d,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts d from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %H, %I, %M, %p, +%r, %R, %S, %T, %X, +%n, %t, %z, %Z or %%. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

sys_time

@@ -1710,7 +1759,7 @@ using sys_days = sys_time<days>;

sys_seconds is a std::chrono::time_point using -std::chrono::system_clock and std::chrono::seconds. +std::chrono::system_clock and std::chrono::seconds. This makes sys_seconds interoperable with std::chrono::system_clock::time_point. It is simply a count of non-leap seconds since the epoch of @@ -1724,6 +1773,45 @@ using sys_seconds = sys_time<std::chrono::seconds>;

+
+template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const sys_time<Duration>& tp);
+
+ +
+

+Effects: Inserts tp, converted to the +common_type<Duration, seconds> into os using the format +string fmt as specified by the +to_stream formatting flags. If +%Z is in the formatting string "UTC" will be used. If +%z is in the formatting string "+0000" will be used. +

+
+ +
+template <class Duration, class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            sys_time<Duration>& tp, std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts tp from is using the format string +fmt as specified by the +from_stream formatting flags. +If %z is present, the parsed offset will be subtracted from the parsed time. +If abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

local_time

@@ -1778,6 +1866,51 @@ using local_seconds = local_time<std::chrono::seconds>;
+
+template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const local_time<Duration>& tp, const std::string* abbrev = nullptr,
+          const std::chrono::seconds* offset_sec = nullptr);
+
+ +
+

+Effects: Inserts tp, converted to the +common_type<Duration, seconds> into os using the format +string fmt as specified by the +to_stream formatting flags. If +%Z is in the formatting string *abbrev will be used. If +%z is in the formatting string *offset_sec will be used. +

+ +

+Throws: A std::runtime_error if %Z is in the formatting +string and abbrev == nullptr, or if %z is in the formatting string +and offset_sec == nullptr. +

+
+ +
+template <class Duration, class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            local_time<Duration>& tp, std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts tp from is using the format string +fmt as specified by the +from_stream formatting flags. +If abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

last_spec

@@ -1840,6 +1973,17 @@ template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const day& d); +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const day& d); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, day& d, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr); + inline namespace literals { constexpr day operator "" _d(unsigned long long d) noexcept; } @@ -2103,6 +2247,47 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const day& d);
+
+ +
+

+Effects: Inserts d into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%d, %e, %n, %t +or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, day& d,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts d from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %e, %e, %n, +%t, %z, %Z or %%. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

month

@@ -2146,6 +2331,17 @@ template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const month& m); +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const month& m); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month& m, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr); + inline namespace literals { constexpr month jan{1}; constexpr month feb{2}; @@ -2437,6 +2633,47 @@ output for the month field by asctime. Otherwise outputs

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const month& m);
+
+ +
+

+Effects: Inserts m into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%b, %B, %h, %m, %n, +%t or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month& m,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts m from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %b, %B, %h, %m, +%n, %t, %z, %Z or %%. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

year

@@ -2488,6 +2725,17 @@ template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const year& y); +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const year& y); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year& y, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr); + inline namespace literals { constexpr year operator "" _y(unsigned long long y) noexcept; } @@ -2803,6 +3051,47 @@ into os. If the year is less than four decimal digits, pads the yea

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const year& y);
+
+ +
+

+Effects: Inserts y into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%C, %y, %Y, %n, %t +or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year& y,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts y from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %C, %y, %Y, %n, +%t, %z, %Z or %%. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

weekday

@@ -2846,6 +3135,17 @@ template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const weekday& wd); +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const weekday& wd); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, weekday& wd, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr); + inline namespace literals { constexpr weekday sun{0}; constexpr weekday mon{1}; @@ -2861,7 +3161,7 @@ constexpr weekday sat{6};

weekday represents a day of the week in the Gregorian calendar. It should -only be representing values in the range 0 to 6, corresponding to Sunday thru Saturday. +only be representing values in the range 0 to 6, corresponding to Sunday thru Saturday. However it may hold values outside this range. It can be constructed with any unsigned value, which will be subsequently truncated to fit into weekday's internal storage. weekday is equality comparable. @@ -3159,6 +3459,47 @@ output for the weekday field by asctime. Otherwise outputs

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const weekday& wd);
+
+ +
+

+Effects: Inserts wd into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%a, %A, %u, %w, %n, +%t or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, weekday& wd,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts wd from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %a, %A, %u, %w, %n, +%t, %z, %Z or %%. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

weekday_indexed

@@ -3325,7 +3666,7 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

Overview

-weekday_last represents the last weekday of a month. +weekday_last represents the last weekday of a month. It is most easily constructed by indexing a weekday with last.

@@ -3449,6 +3790,17 @@ constexpr bool operator>=(const month_day& x, const month_day& y) noe template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const month_day& md); + +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const month_day& md); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month_day& md, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr);

Overview

@@ -3591,6 +3943,48 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const month_day& md);
+
+ +
+

+Effects: Inserts md into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%b, %B, %d, %e, %h, +%m, %n, %t or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month_day& md,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts md from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %b, %B, %d, %e, +%h, %m, %n, %t, %z, +%Z or %%. If abbrev is not equal to +nullptr, the information parsed by %Z (if present) will be +placed in *abbrev. If offset is not equal to +nullptr, the information parsed by %z (if present) will be +placed in *offset. +

+
+

month_day_last

@@ -4049,6 +4443,17 @@ constexpr year_month operator-(const year_month& ym, const years& dy) no template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const year_month& ym); + +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const year_month& ym); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year_month& ym, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr);

Overview

@@ -4316,6 +4721,48 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const year_month& ym);
+
+ +
+

+Effects: Inserts ym into os using the format string +fmt as specified by the +to_stream formatting flags. The behavior +is undefined except for the following flags (or modified versions of these flags): +%b, %B, %C, %h, %m, +%y, %Y, %n, %t or %%. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year_month& ym,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts ym from is using the format string +fmt as specified by the +from_stream formatting flags. The +behavior is undefined except for the following flags (or modified versions of these +flags): %b, %B, %C, %h, +%m, %y, %Y, %n, %t, +%z, %Z or %%. If abbrev is not equal +to nullptr, the information parsed by %Z (if present) will be +placed in *abbrev. If offset is not equal to +nullptr, the information parsed by %z (if present) will be +placed in *offset. +

+
+

year_month_day

@@ -4368,6 +4815,17 @@ constexpr year_month_day operator-(const year_month_day& ymd, const years&am template<class CharT, class Traits> std::basic_ostream<class CharT, class Traits>& operator<<(std::basic_ostream<class CharT, class Traits>& os, const year_month_day& ymd); + +template<class CharT, class Traits> +void +to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt, + const year_month_day& ymd); + +template <class CharT, class Traits, class Alloc = std::allocator<CharT>> +void +from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year_month_day& ymd, + std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr, + std::chrono::minutes* offset = nullptr);

Overview

@@ -4378,7 +4836,7 @@ and day. year_month_day is a field-based time point w resolution of days. One can observe each field. year_month_day supports years and months oriented arithmetic, but not days oriented arithmetic. For the latter, there is a conversion to -sys_days which efficiently supports days oriented arithmetic. +sys_days which efficiently supports days oriented arithmetic. There is also a conversion from sys_days. year_month_day is equality and less-than comparable.

@@ -4736,6 +5194,45 @@ are prefixed with '0' if necessary..

+
+template<class CharT, class Traits>
+void
+to_stream(std::basic_ostream<class CharT, class Traits>& os, const CharT* fmt,
+          const year_month_day& ymd);
+
+ +
+

+Effects: Inserts ymd into os using the format string +fmt as specified by the +to_stream formatting flags. +

+

+Throws: A std::runtime_error if %z or %Z is +used in the fmt string. +

+
+ +
+template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year_month_day& ymd,
+            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
+ +
+

+Effects: Extracts ymd from is using the format string +fmt as specified by the +from_stream formatting flags. If +abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

+
+

year_month_day_last

@@ -5161,12 +5658,12 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

year_month_weekday represents a specific year, -month, and nth weekday of the month. +month, and nth weekday of the month. year_month_weekday is a field-based time point with a resolution of days. One can observe each field. year_month_weekday supports years and months oriented arithmetic, but not days oriented arithmetic. For the latter, there is a conversion to sys_days which -efficiently supports days oriented arithmetic. +efficiently supports days oriented arithmetic. year_month_weekday is equality comparable.

@@ -6817,7 +7314,7 @@ This specialization shall not exist unless Period < 1s. 

-constexpr 
+constexpr
 time_of_day<std::chrono::duration<Rep, Period>>::time_of_day() noexcept;
@@ -6836,7 +7333,7 @@ corresponding to 0 fractional seconds after 00:00:00. 
-constexpr explicit 
+constexpr explicit
 time_of_day<std::chrono::duration<Rep, Period>>::time_of_day(std::chrono::duration<Rep, Period> since_midnight) noexcept;
@@ -7037,5 +7534,778 @@ os << year_month_day(floor<days>(tp));

+

to_stream formatting

+ +

+Each flag begins with a %. Some flags can be modified by E or +O. During streaming each flag is replaced according to the table below. All +characters in the format string which are not represented in the table below are inserted +unchanged into the stream. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%aThe locale's abbreviated weekday name.
%AThe locale's full weekday name.
%bThe locale's abbreviated month name.
%BThe locale's full month name.
%cThe locale's date and time representation. The modified command %Ec +produces the locale's alternate date and time representation.
%CThe year divided by 100 using floored division. If the result is a single decimal +digit, it is prefixed with 0. The modified command %EC +produces the locale's alternative representation of the century.
%dThe day of month as a decimal number. If the result is a single decimal +digit, it is prefixed with 0. The modified command %Od +produces the locale's alternative representation.
%DEquivalent to %m/%d/%y.
%eThe day of month as a decimal number. If the result is a single decimal +digit, it is prefixed with a space. The modified command %Oe +produces the locale's alternative representation.
%FEquivalent to %Y-%m-%d.
%gThe last two decimal digits of the ISO week-based year. If the result is a single +digit it is prefixed by 0.
%GThe ISO week-based year as a decimal number. If the result is less than four +digits it is left-padded with 0 to four digits.
%hEquivalent to %b.
%HThe hour (24-hour clock) as a decimal number. If the result is a single +digit, it is prefixed with 0. The modified command %OH +produces the locale's alternative representation.
%IThe hour (12-hour clock) as a decimal number. If the result is a single +digit, it is prefixed with 0. The modified command %OI +produces the locale's alternative representation.
%jThe day of the year as a decimal number. Jan 1 is 001. If the result +is less than three digits, it is left-padded with 0 to three digits.
%mThe month as a decimal number. Jan is 01. If the result is a single +digit, it is prefixed with 0. The modified command %Om +produces the locale's alternative representation.
%MThe minute as a decimal number. If the result is a single +digit, it is prefixed with 0. The modified command %OM +produces the locale's alternative representation.
%nA newline character.
%pThe locale's equivalent of the AM/PM designations associated with a 12-hour +clock.
%rThe locale's 12-hour clock time.
%REquivalent to %H:%M.
%SSeconds as a decimal number. If the number of seconds is less than 10, the result is +prefixed with 0. If the precision of the input can not be exactly +represented with seconds, then the format is a decimal floating point number with a fixed +format and a precision matching that of the precision of the input (or to a microseconds +precision if the conversion to floating point decimal seconds can not be made within 18 +fractional digits). The character for the decimal point is localized according to the +locale. The modified command %OS produces the locale's alternative +representation.
%tA horizontal-tab character.
%TEquivalent to %H:%M:%S.
%uThe ISO weekday as a decimal number (1-7), where Monday is 1. The modified command +%Ou produces the locale's alternative representation.
%UThe week number of the year as a decimal number. The first Sunday of the year is the +first day of week 01. Days of the same year prior to that are in week +00. If the result is a single digit, it is prefixed with 0. +The modified command %OU produces the locale's alternative +representation.
%VThe ISO week-based week number as a decimal number. If the result is a single digit, +it is prefixed with 0. The modified command %OV produces the +locale's alternative representation.
%wThe weekday as a decimal number (0-6), where Sunday is 0. The modified command +%Ow produces the locale's alternative representation.
%WThe week number of the year as a decimal number. The first Monday of the year is the +first day of week 01. Days of the same year prior to that are in week +00. If the result is a single digit, it is prefixed with 0. The +modified command %OW produces the locale's alternative representation.
%xThe locale's date representation. The modified command %Ex +produces the locale's alternate date representation.
%XThe locale's time representation. The modified command %Ex +produces the locale's alternate time representation.
%yThe last two decimal digits of the year. If the result is a single digit it is +prefixed by 0.
%YThe year as a decimal number. If the result is less than four digits it is +left-padded with 0 to four digits.
%zThe offset from UTC in the ISO 8601 format. For example -0430 refers to +4 hours 30 minutes behind UTC. If the offset is zero, +0000 is used. +The modified commands %Ez and %Ez insert a : +between the hours and minutes: -04:30. A std::runtime_error is +thrown if the offset information is not available.
%ZThe time zone abbreviation. A std::runtime_error is thrown if the time +zone abbreviation is not available. UTC is used for +sys_time.
%%A % character.
+
+ +

format

+ +
+template <class CharT, class Streamable>
+std::basic_string<CharT>
+format(const std::locale& loc, const CharT* fmt, const Streamable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +to_stream(std::declval<std::basic_ostream<CharT>&>(), fmt, tp) +is valid. +

+

+Effects: Constructs a std::basic_ostringstream<CharT> os and +imbues it with loc. Calls to_stream(os, fmt, tp). +

+

+Returns: os.str(). +

+
+ +
+template <class CharT, class Streamable>
+std::basic_string<CharT>
+format(const CharT* fmt, const Streamable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +to_stream(std::declval<std::basic_ostream<CharT>&>(), fmt, tp) +is valid. +

+

+Effects: Constructs a std::basic_ostringstream<CharT> os. +Calls to_stream(os, fmt, tp). +

+

+Returns: os.str(). +

+
+ +
+template <class CharT, class Traits, class Streamable>
+std::basic_string<CharT>
+format(const std::locale& loc, const std::basic_string<CharT, Traits>& fmt, const Streamable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +to_stream(std::declval<std::basic_ostream<CharT>&>(), fmt.c_str(), tp) +is valid. +

+

+Effects: Constructs a std::basic_ostringstream<CharT> os and +imbues it with loc. Calls to_stream(os, fmt.c_str(), tp). +

+

+Returns: os.str(). +

+
+ +
+template <class CharT, class Traits, class Streamable>
+std::basic_string<CharT>
+format(const std::basic_string<CharT, Traits>& fmt, const Streamable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +to_stream(std::declval<std::basic_ostream<CharT>&>(), fmt.c_str(), tp) +is valid. +

+

+Effects: Constructs a std::basic_ostringstream<CharT> os. +Calls to_stream(os, fmt.c_str(), tp). +

+

+Returns: os.str(). +

+
+ +

from_stream formatting

+ +

+Each flag begins with a %. Some flags can be modified by E or +O. During parsing each flag interprets characters as parts of date and time +type according to the table below. Some flags can be modified by a width parameter which +governs how many characters are parsed from the stream in interpreting the flag. All +characters in the format string which are not represented in the table below are parsed +unchanged from the stream. The C++ specification says that the parsing of month and +weekday names is both locale sensitive and case insensitive. If you find this not +to be the case, file a bug with your std::lib vendor. +

+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
%aThe locale's full or abbreviated case-insensitive weekday name.
%AEquivalent to %a.
%bThe locale's full or abbreviated case-insensitive month name.
%BEquivalent to %b.
%cThe locale's date and time representation. The modified command %Ec +interprets the locale's alternate date and time representation.
%CThe century as a decimal number. The modified command %NC where +N is a positive decimal integer specifies the maximum number of characters to +read. If not specified, the default is 2. Leading zeroes are permitted but not required. +The modified commands %EC and %OC interpret the locale's +alternative representation of the century.
%dThe day of the month as a decimal number. The modified command %Nd where +N is a positive decimal integer specifies the maximum number of characters to +read. If not specified, the default is 2. Leading zeroes are permitted but not required. +The modified command %EC interprets the locale's alternative representation +of the day of the month.
%DEquivalent to %m/%d/%y.
%eEquivalent to %d and can be modified like %d.
%FEquivalent to %Y-%m-%d. If modified with a width, the width is applied +to only %Y.
%gThe last two decimal digits of the ISO week-based year. The modified command +%Ng where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 2. Leading zeroes are +permitted but not required.
%GThe ISO week-based year as a decimal number. The modified command %NG +where N is a positive decimal integer specifies the maximum number of +characters to read. If not specified, the default is 4. Leading zeroes are permitted +but not required.
%hEquivalent to %b.
%HThe hour (24-hour clock) as a decimal number. The modified command %NH +where N is a positive decimal integer specifies the maximum number of +characters to read. If not specified, the default is 2. Leading zeroes are permitted +but not required. The modified command %OH interprets the locale's +alternative representation.
%IThe hour (12-hour clock) as a decimal number. The modified command %NI +where N is a positive decimal integer specifies the maximum number of +characters to read. If not specified, the default is 2. Leading zeroes are permitted +but not required.
%jThe day of the year as a decimal number. Jan 1 is 1. The modified +command %Nj where N is a positive decimal integer specifies the +maximum number of characters to read. If not specified, the default is 3. Leading zeroes +are permitted but not required.
%mThe month as a decimal number. Jan is 1. The modified command +%Nm where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 2. Leading zeroes are +permitted but not required. The modified command %Om interprets the locale's +alternative representation.
%MThe minutes as a decimal number. The modified command +%NM where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 2. Leading zeroes are +permitted but not required. The modified command %OM interprets the locale's +alternative representation.
%nMatches one or more white space characters. Consecutive %n and +%t act as a single %n.
%pThe locale's equivalent of the AM/PM designations associated with a 12-hour clock. +The command %I must precede %p in the format string.
%rThe locale's 12-hour clock time.
%REquivalent to %H:%M.
%SThe seconds as a decimal number. The modified command %NS where +N is a positive decimal integer specifies the maximum number of characters to +read. If not specified, the default is 2 if the input time has a precision convertible to +seconds. Otherwise the default width is determined by the decimal precision of the input +and the field is interpreted as a long double in a fixed format. If encountered, the +locale determines the decimal point character. Leading zeroes are permitted but not +required. The modified command %OS interprets the locale's alternative +representation.
%tEquivalent to %n.
%TEquivalent to %H:%M:%S.
%uThe ISO weekday as a decimal number (1-7), where Monday is 1. The modified command +%Nu where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 1. Leading zeroes are +permitted but not required. The modified command %Ou interprets the locale's +alternative representation.
%UThe week number of the year as a decimal number. The first Sunday of the year is the +first day of week 01. Days of the same year prior to that are in week +00. The modified command %NU where N is a +positive decimal integer specifies the maximum number of characters to read. If not +specified, the default is 2. Leading zeroes are permitted but not required.
%VThe ISO week-based week number as a decimal number. The modified command +%NV where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 2. Leading zeroes are +permitted but not required.
%wThe weekday as a decimal number (0-6), where Sunday is 0. The modified command +%Nw where N is a positive decimal integer specifies the maximum +number of characters to read. If not specified, the default is 1. Leading zeroes are +permitted but not required. The modified command %Ou interprets the locale's +alternative representation.
%WThe week number of the year as a decimal number. The first Monday of the year is the +first day of week 01. Days of the same year prior to that are in week +00. The modified command %NW where N is a positive +decimal integer specifies the maximum number of characters to read. If not specified, the +default is 2. Leading zeroes are permitted but not required.
%xThe locale's date representation. The modified command %Ex +produces the locale's alternate date representation.
%XThe locale's time representation. The modified command %Ex +produces the locale's alternate time representation.
%yThe last two decimal digits of the year. The modified command %Ny where +N is a positive decimal integer specifies the maximum number of characters to +read. If not specified, the default is 2. Leading zeroes are permitted but not required. +The modified commands %Ey and %Oy interpret the locale's +alternative representation.
%YThe year as a decimal number. The modified command %NY where +N is a positive decimal integer specifies the maximum number of characters to +read. If not specified, the default is 4. Leading zeroes are permitted but not required. +The modified command %EY interprets the locale's alternative +representation.
%zThe offset from UTC in the ISO 8601 format. For example -0430 refers to +4 hours 30 minutes behind UTC. The modified commands %Ez and %Ez +parse a : between the hours and minutes and leading zeroes on the hour field +are optional: -4:30.
%ZThe time zone abbreviation. A single word is read as specified by the extraction +operator for std::basic_string.
%%A % character is extracted.
+
+ +

parse

+ +
+template <class Parsable, class CharT, class Traits, class Alloc>
+unspecified
+parse(const std::basic_string<CharT, Traits, Alloc>& format, Parsable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format.c_str(), tp) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format.c_str(), tp). +

+
+ +
+template <class Parsable, class CharT, class Traits, class Alloc>
+unspecified
+parse(const std::basic_string<CharT, Traits, Alloc>& format, Parsable& tp,
+      std::basic_string<CharT, Traits, Alloc>& abbrev);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format.c_str(), tp, &abbrev) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format.c_str(), tp, &abbrev). +

+
+ +
+template <class Parsable, class CharT, class Traits, class Alloc>
+unspecified
+parse(const std::basic_string<CharT, Traits, Alloc>& format, Parsable& tp,
+      std::chrono::minutes& offset);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format.c_str(), tp, nullptr, &offset) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format.c_str(), tp, nullptr, &offset). +

+
+ +
+template <class Parsable, class CharT, class Traits>
+unspecified
+parse(const std::basic_string<CharT, Traits>& format, Parsable& tp,
+      std::basic_string<CharT, Traits>& abbrev, std::chrono::minutes& offset);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format.c_str(), tp, &abbrev, &offset) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format.c_str(), tp, &abbrev, &offset). +

+
+ +
+// const CharT* formats
+
+template <class Parsable, class CharT>
+unspecified
+parse(const CharT* format, Parsable& tp);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format, tp) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format, tp). +

+
+ +
+template <class Parsable, class CharT, class Traits, class Alloc>
+unspecified
+parse(const CharT* format, Parsable& tp, std::basic_string<CharT, Traits, Alloc>& abbrev);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format, tp, &abbrev) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format, tp, &abbrev). +

+
+ +
+template <class Parsable, class CharT>
+unspecified
+parse(const CharT* format, Parsable& tp, std::chrono::minutes& offset);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format, tp, nullptr, &offset) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format, tp, nullptr, &offset). +

+
+ +
+template <class Parsable, class CharT, class Traits, class Alloc>
+unspecified
+parse(const CharT* format, Parsable& tp,
+      std::basic_string<CharT, Traits, Alloc>& abbrev, std::chrono::minutes& offset);
+
+ +
+

+Remarks: This function does not participate in overload resolution unless +from_stream(std::declval<std::basic_istream<CharT, Traits>&>(), format, tp, &abbrev, &offset) +is valid +

+

+Returns: A basic_istream<CharT, Traits> manipulator that on +extraction from a basic_istream<CharT, Traits> is calls +from_stream(is, format, tp, &abbrev, &offset). +

+
+ diff --git a/tz.html b/tz.html index e5b1a17..efe859b 100644 --- a/tz.html +++ b/tz.html @@ -26,7 +26,7 @@

Howard E. Hinnant
-2017-03-25
+2017-04-01

Time Zone Database Parser

@@ -57,10 +57,6 @@
  • time_zone
  • zoned_time
  • make_zoned
    • -
  • to_stream
    • -
  • format
    • -
  • from_stream
    • -
  • parse
  • utc_clock
  • tai_clock
  • gps_clock
    • @@ -529,7 +525,7 @@ zone, and no clock::now(). It is the void* of

  • -time_zone: This represents a specific geographical area, and all +time_zone: This represents a specific geographical area, and all time zone related information for this area over all time. This includes a name for the area, and for any specific point in time, the UTC offset, the abbreviation, and additional information. @@ -1513,7 +1509,7 @@ useful for debugging this library. time_point with precision Duration. If seconds is not implicitly convertible to Duration, the instantiation is ill-formed. [Note: There exist time_zones with UTC offsets that require a -precision of seconds. — end note:] +precision of seconds. — end note:] 

    @@ -1573,6 +1569,15 @@ operator==(const zoned_time<Duration1>& x, const zoned_time<Duratio
 template <class Duration1, class Duration2>
 bool
 operator!=(const zoned_time<Duration1>& x, const zoned_time<Duration2>& y);
+
+template <class CharT, class Traits, class Duration>
+std::basic_ostream<class CharT, class Traits>&
+operator<<(std::basic_ostream<class CharT, class Traits>& os, const zoned_time<Duration>& t)
+
+template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const zoned_time<Duration>& tp);

    @@ -1879,14 +1884,28 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

    -Effects: Streams t to os using the format "%F %T %Z" -and the value returned from t.get_local_time(). +Effects: Calls to_stream(os, "%F %T %Z", t).

    Returns: os.

    +
    +template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const zoned_time<Duration>& tp);
+
    + +
    +

    +Effects: Constructs a copy of the sys_info object by calling +tp.get_info() (stored in a local named info for example). +Then calls to_stream(os, fmt, tp.get_local_time(), &info.abbrev, &info.offset). +

    +
    +

    make_zoned

    @@ -2024,438 +2043,6 @@ make_zoned(const std::string& name, const sys_time<Duration>& st) -

    to_stream

    -
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const year& y);
-
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const month& m);
-
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const day& d);
-
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const weekday& wd);
-
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const year_month& ym);
-
    - -
    -template <class CharT, class Traits>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const month_day& md);
-
    - - -
    -template <class CharT, class Traits, , class Rep, class Period>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const std::chrono::duration<Rep, Period>& d);
-
    - -
    -template <class CharT, class Traits, , class Rep, class Period>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const year_month_day& ymd);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const local_time<Duration>& tp);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const sys_time<Duration>& tp);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const zoned_time<Duration>& tp);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const utc_time<Duration>& tp);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const tai_time<Duration>& tp);
-
    - -
    -template <class CharT, class Traits, class Duration>
-void
-to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
-          const gps_time<Duration>& tp);
-
    - -
    -

    -These are lower-level functions with respect to format. These functions -will format directly to a stream. If you use these you will not be able -to align your formatted time stamp within a width respecting the stream's -adjustfield. But in forgoing that utility you may realize some performance -gains over format as nothing in the implementation of to_stream -creates temporary strings or streams to format into. -

    -
    - -
    - -

    format

    -
    -
    -template <class CharT, class Streamable>
-std::basic_string<CharT>
-format(const std::locale& loc, const CharT* fmt, const Streamable& tp);
-
-template <class CharT, class Streamable>
-std::basic_string<CharT>
-format(const CharT* fmt, const Streamable& tp);
-
-template <class CharT, class Traits, class Streamable>
-std::basic_string<CharT>
-format(const std::locale& loc, const std::basic_string<CharT, Traits>& fmt, const Streamable& tp);
-
-template <class CharT, class Traits, class Streamable>
-std::basic_string<CharT>
-format(const std::basic_string<CharT, Traits>& fmt, const Streamable& tp);
-
    -
    -

    -Remarks: These functions do not participate in overload resolution unless -Streamable has a to_stream overload of the form described in the -previous section. -

    -

    -Effects: These functions create a formatted time stamp using the -arguments, returning the result in a std::string. -

    -
    -

    -If a locale is passed in, then that locale is used for -any formatting that requires a locale. If no locale -is passed in, then if a locale is required for formatting, a -default constructed locale will be used (which makes a copy of the -global locale). -

    -

    -The format string follows the rules as specified for -std::time_put with the following exceptions: -

    -
      -

    • -If %S or %T appears in the format string -and the argument tp has precision that can not be exactly represented -with seconds, then seconds -are formatted as a decimal floating point number with a fixed format and a -precision matching that of the precision of tp (or to a microseconds precision -if the conversion to floating point decimal seconds can not be made within 18 digits). -The character for the decimal point is localized according to the locale. -

      • - -

    • -If %z appears in the format, the behavior depends on the type of -tp: -

      -
        -
      • -local_time: An exception of type std::runtime_error is thrown. -
        • -
      • -zoned_time: The offset associated with tp.get_time_zone() is -used. -
        • -
      • -sys_time: "+0000" is used. -
        • -
      -

      -If %z is modified by either E or O -(that is, %Ez or %Oz), then a colon is inserted -between the hours and minutes: +00:00. -

      -
      • - -

    • -If %Z appears in the format, the behavior depends on the type of -tp: -

      -
        -
      • -local_time: An exception of type std::runtime_error is thrown. -
        • -
      • -zoned_time: The abbreviation associated with -tp.get_time_zone() is used. -
        • -
      • -sys_time: "UTC" is used. -
        • -
      -
      • - -
    - -

    -For the overloads taking a zoned_time it is the value returned by -tz.get_local_time() that is formatted. -

    -
    - -

    -Returns: The formatted string. -

    - -
    -
    - -

    from_stream

    -
    - -
    -template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year& y,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month& m,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, day& d,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, weekday& wd,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, year_month& ym,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits, class Alloc = std::allocator<CharT>>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt, month_day& md,
-            std::basic_string<CharT, Traits, Alloc>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            year_month_day& ymd, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Duration, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            sys_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Duration, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            local_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Rep, class Period, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            std::chrono::duration<Rep, Period>& d,
-            std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Duration, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            utc_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Duration, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            tai_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
-template <class Duration, class CharT, class Traits>
-void
-from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
-            gps_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
-            std::chrono::minutes* offset = nullptr);
-
    - -
    -

    -Effects: These functions attempt to parse an object out of -is according to fmt. If the parse is unsuccessful, -calls is.setstate(std::ios::failbit) which may throw an exception. -tp, *abbrev, and *offset are altered only in -the event of a successful parse, for the latter two, only if they are not equal to -nullptr. -

    -
    -

    -The format string follows the rules as specified for std::time_get -with the following exceptions: -

    -
      -

    • -If %F appears in the format string it is interpreted as -%Y-%m-%d. -

      • - -

    • -If %S or %T appears in the format string and the -argument tp has precision that is not implicitly convertible to seconds, then -the seconds are parsed as a double, and if that parse is successful -contributes to the time stamp as if -round<Duration>(duration<double>{s}) where s is a -local variable holding the parsed double. -

      • - -

    • -If %z appears in the format string and an offset is -successfully parsed, the overloads taking sys_time, utc_time, -tai_time and gps_time interpret the -parsed time as a local time and subtracts the offset prior to assigning the -value to tp, resulting in a value of tp representing a -UTC timestamp. The remaining overloads require a valid -parse of the offset, but then ignore the offset in assigning a value to -tp. If offset is not equal to nullptr, -on successful parse *offset will hold the value represented by -%z if present, or will be assigned 0min if -%z is not present. -

      -

      -The format of the offset is +/-hhmm. The leading plus or minus -sign is required. If the format string was modified (i.e. %Ez -or %Oz), a colon is required between hours and minutes, and the leading -hours digit is optional: -+/-[h]h:mm. -

      -
      • - -

    • -If %Z appears in the format string then an -abbreviation is required in that position for a successful parse. The -abbreviation will be parsed as a std::basic_string<CharT, Traits> -(delimited by white -space). The parsed abbreviation does not have to be a valid time zone -abbreviation, and has no impact on the value parsed into tp. If - abbrev is not equal to nullptr one can discover what -that parsed abbreviation is. On successful parse, and if abbrev != nullptr, -*abbrev will be -assigned the value represented by %Z if present, or assigned the -empty string if %Z is not present. -

      • -
    -
    -

    -Note: There is no unique mapping from a time zone abbreviation to a -time_zone. But given a time zone abbreviation and a sys_time -or local_time, one could make a list of potential time_zones. -Given a UTC offset, one might even narrow that list down further. -

    -
    -
    - -

    parse

    -
    -

    -Each of the functions below return a manipulator which can be used to extract the -desired information from a stream. These functions do not participate in overload -resolution unless Parsable has a corresponding from_stream -overload. -

    - -
    -template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const std::basic_string<CharT, Traits>& format, Parsable& tp);
-
-template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const std::basic_string<CharT, Traits>& format, Parsable& tp,
-      std::basic_string<CharT, Traits>& abbrev);
-
-template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const std::basic_string<CharT, Traits>& format, Parsable& tp,
-      std::chrono::minutes& offset);
-
-template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const std::basic_string<CharT, Traits>& format, Parsable& tp,
-      std::basic_string<CharT, Traits>& abbrev, std::chrono::minutes& offset);
-
-// const CharT* formats
-
-template <class Parsable, class CharT>
-unspecified
-parse(const CharT* format, Parsable& tp);
-
-template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const CharT* format, Parsable& tp, std::basic_string<CharT, Traits>& abbrev);
-
-template <class Parsable, class CharT>
-unspecified
-parse(const CharT* format, Parsable& tp, std::chrono::minutes& offset);
-
-template <class Parsable, class CharT, class Traits>
-unspecified
-parse(const CharT* format, Parsable& tp,
-      std::basic_string<CharT, Traits>& abbrev, std::chrono::minutes& offset);
-
    -
    -

    utc_clock

    @@ -2561,15 +2148,53 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

    -Effects: Streams t to os using the format "%F %T". This -differs from streaming sys_time only by the use of 60 for the -seconds specifier when the value represents an inserted leap second. +Effects: Calls to_stream(os, "%F %T", t).

    Returns: os.

    +
    +template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const utc_time<Duration>& tp);
+
    + +
    +

    +Effects: Inserts tp into os using the format +string fmt as specified by the +to_stream formatting flags. +Time points representing leap second insertions which format seconds will show +60 in the seconds field. +If %Z is in the formatting string "UTC" will be used. +If %z is in the formatting string "+0000" will be used. +

    +
    + +
    +template <class Duration, class CharT, class Traits>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            utc_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
    + +
    +

    +Effects: Extracts tp from is using the format string +fmt as specified by the +from_stream formatting flags. +If %z is present, the parsed offset will be subtracted from the parsed time. +If abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

    +
    +

    tai_clock

    @@ -2667,20 +2292,51 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

    -Effects: Creates a sys_time from t as if by: -

    -
    -auto tp = sys_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} -
-              (sys_days{1970_y/jan/1} - sys_days{1958_y/jan/1});
-
    -

    -And then streams that sys_time: os << tp. +Effects: Calls to_stream(os, "%F %T", t).

    Returns: os.

    +
    +template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const tai_time<Duration>& tp);
+
    + +
    +

    +Effects: Inserts tp into os using the format +string fmt as specified by the +to_stream formatting flags. +If %Z is in the formatting string "TAI" will be used. +If %z is in the formatting string "+0000" will be used. +

    +
    + +
    +template <class Duration, class CharT, class Traits>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            tai_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
    + +
    +

    +Effects: Extracts tp from is using the format string +fmt as specified by the +from_stream formatting flags. +If %z is present, the parsed offset will be subtracted from the parsed time. +If abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

    +
    +

    gps_clock

    @@ -2777,20 +2433,51 @@ operator<<(std::basic_ostream<class CharT, class Traits>& os, co

    -Effects: Creates a sys_time from t as if by: -

    -
    -auto tp = sys_time<common_type_t<Duration, seconds>>{t.time_since_epoch()} +
-              (sys_days{1980y/jan/sun[1]} - sys_days{1970y/jan/1});
-
    -

    -And then streams that sys_time: os << tp. +Effects: Calls to_stream(os, "%F %T", t).

    Returns: os.

    +
    +template <class CharT, class Traits, class Duration>
+void
+to_stream(std::basic_ostream<CharT, Traits>& os, const CharT* fmt,
+          const gps_time<Duration>& tp);
+
    + +
    +

    +Effects: Inserts tp into os using the format +string fmt as specified by the +to_stream formatting flags. +If %Z is in the formatting string "GPS" will be used. +If %z is in the formatting string "+0000" will be used. +

    +
    + +
    +template <class Duration, class CharT, class Traits>
+void
+from_stream(std::basic_istream<CharT, Traits>& is, const CharT* fmt,
+            gps_time<Duration>& tp, std::basic_string<CharT, Traits>* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
+
    + +
    +

    +Effects: Extracts tp from is using the format string +fmt as specified by the +from_stream formatting flags. +If %z is present, the parsed offset will be subtracted from the parsed time. +If abbrev is not equal to nullptr, the information parsed by +%Z (if present) will be placed in *abbrev. If +offset is not equal to nullptr, the information parsed by +%z (if present) will be placed in *offset. +

    +
    +

    [Example:

    @@ -2810,7 +2497,7 @@ int main() { using namespace date; - using namespace std::chrono; + using namespace std::chrono_literals; auto start = to_utc_time(sys_days{2015_y/jul/1} - 500ms); auto end = start + 2s; for (auto utc = start; utc < end; utc += 100ms) @@ -2818,10 +2505,10 @@ main() auto sys = to_sys_time(utc); auto tai = to_tai_time(utc); auto gps = to_gps_time(utc); - std::cout << sys << " SYS == " - << utc << " UTC == " - << tai << " TAI == " - << gps << " GPS\n"; + std::cout << format("%F %T SYS == ", sys) + << format("%F %T %Z == ", utc) + << format("%F %T %Z == ", tai) + << format("%F %T %Z\n", gps); } } @@ -2865,7 +2552,7 @@ class leap public: leap(const leap&) = default; leap& operator=(const leap&) = default; - + // Undocumented constructors sys_seconds date() const;