Add from_stream

tz.html

@@ -26,7 +26,7 @@
 <br/>
 <br/>
 <a href="mailto:howard.hinnant@gmail.com">Howard E. Hinnant</a><br/>
-2017-02-26<br/>
+2017-03-02<br/>
 </address>
 <hr/>
 <h1 align=center>Time Zone Database Parser</h1>
@@ -59,6 +59,7 @@
     <li><a href="#make_zoned"><code>make_zoned</code></a></li>
     <li><a href="#to_stream"><code>to_stream</code></a></li>
     <li><a href="#format"><code>format</code></a></li>
+    <li><a href="#from_stream"><code>from_stream</code></a></li>
     <li><a href="#parse"><code>parse</code></a></li>
     <li><a href="#utc_clock"><code>utc_clock</code></a></li>
     <li><a href="#tai_clock"><code>tai_clock</code></a></li>
@@ -2172,74 +2173,62 @@ For the overloads taking a <code>zoned_time</code> it is the value returned by
 </blockquote>
 </blockquote>
 
-<a name="parse"></a><h3><code>parse</code></h3>
+<a name="from_stream"></a><h3><code>from_stream</code></h3>
 <blockquote>
-<p>
-One can parse in a <code>year_month_day</code>, <code>sys_time&lt;Duration&gt;</code>,
-<code>local_time&lt;Duration&gt;</code>, <code>utc_time&lt;Duration&gt;</code>,
-<code>tai_time&lt;Duration&gt;</code>, <code>gps_time&lt;Duration&gt;</code>,
-or a <code>duration&lt;Rep, Period&gt;</code>.
-Optionally, one can also pass in a reference
-to a <code>std::string</code> in order to capture the time zone abbreviation, or one
-can pass in a reference to a <code>std::chrono::minutes</code> to capture a time zone
-UTC offset (formatted as <code>+0000</code>), or one can pass in both in either order.
-</p>
-
-<p>
-Each of the functions below return a <code>parse_manip</code> <i>manipulator</i> which is
-specialized on the type to be parsed, and which can be used to extract the desired
-information from a stream.
-</p>
 
 <pre>
-template &lt;class Parsable, class CharT, class Traits = std::char_traits&lt;CharT&gt;&gt;
+template &lt;class CharT, class Traits&gt;
-struct parse_manip;
+void
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
+            year_month_day&amp; ymd, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-template &lt;class Parsable, class CharT, class Traits&gt;
+template &lt;class Duration, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT, Traits&gt;::type
+void
-parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp);
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
+            sys_time&lt;Duration&gt;&amp; tp, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-template &lt;class Parsable, class CharT, class Traits&gt;
+template &lt;class Duration, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT, Traits&gt;::type
+void
-parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
-      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev);
+            local_time&lt;Duration&gt;&amp; tp, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-template &lt;class Parsable, class CharT, class Traits&gt;
+template &lt;class Rep, class Period, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT, Traits&gt;::type
+void
-parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
-      std::chrono::minutes&amp; offset);
+            std::chrono::duration&lt;Rep, Period&gt;&amp; d,
+            std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-template &lt;class Parsable, class CharT, class Traits&gt;
+template &lt;class Duration, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT, Traits&gt;::type
+void
-parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
-      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev, std::chrono::minutes&amp; offset);
+            utc_time&lt;Duration&gt;&amp; tp, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-// const CharT* formats
+template &lt;class Duration, class CharT, class Traits&gt;
+void
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
+            tai_time&lt;Duration&gt;&amp; tp, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
+            std::chrono::minutes* offset = nullptr);
 
-template &lt;class Parsable, class CharT&gt;
+template &lt;class Duration, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT&gt;::type
+void
-parse(const CharT* format, Parsable&amp; tp);
+from_stream(std::basic_istream&lt;CharT, Traits&gt;&amp; is, const CharT* fmt,
-
+            gps_time&lt;Duration&gt;&amp; tp, std::basic_string&lt;CharT, Traits&gt;* abbrev = nullptr,
-template &lt;class Parsable, class CharT, class Traits&gt;
+            std::chrono::minutes* offset = nullptr);
-typename parse_manip&lt;Parsable, CharT&gt;::type
-parse(const CharT* format, Parsable&amp; tp, std::basic_string&lt;CharT, Traits&gt;&amp; abbrev);
-
-template &lt;class Parsable, class CharT&gt;
-typename parse_manip&lt;Parsable, CharT&gt;::type
-parse(const CharT* format, Parsable&amp; tp, std::chrono::minutes&amp; offset);
-
-template &lt;class Parsable, class CharT, class Traits&gt;
-typename parse_manip&lt;Parsable, CharT&gt;::type
-parse(const CharT* format, Parsable&amp; tp,
-      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev, std::chrono::minutes&amp; offset);
 </pre>
+
 <blockquote>
 <p>
 <i>Effects:</i> These functions attempt to parse an object out of
-<code>is</code> according to <code>format</code>.  If the parse is unsuccessful,
+<code>is</code> according to <code>fmt</code>.  If the parse is unsuccessful,
 calls <code>is.setstate(std::ios::failbit)</code> which may throw an exception.
-<code>tp</code>, <code>abbrev</code>, and <code>offset</code> are altered only in
+<code>tp</code>, <code>*abbrev</code>, and <code>*offset</code> are altered only in
-the event of a successful parse.
+the event of a successful parse, for the latter two, only if they are not equal to
+<code>nullptr</code>.
 </p>
 <blockquote>
 <p>
@@ -2253,23 +2242,24 @@ If <code>%F</code> appears in the <code>format</code> string it is interpreted a
 </p></li>
 
 <li><p>
-If <code>%S</code> or <code>%T</code> appears in the <code>format</code> string
+If <code>%S</code> or <code>%T</code> appears in the <code>format</code> string and the
-and the argument <code>tp</code> has precision finer than seconds, then the
+argument <code>tp</code> has precision that is not implicitly convertible to seconds, then
-seconds are parsed as a <code>double</code>, and if that parse is successful
+the seconds are parsed as a <code>double</code>, and if that parse is successful
 contributes to the time stamp as if
-<code>round&lt;Duration&gt;(duration&lt;double&gt;{s})</code> where
+<code>round&lt;Duration&gt;(duration&lt;double&gt;{s})</code> where <code>s</code> is a
-<code>s</code> is a local variable holding the parsed <code>double</code>.
+local variable holding the parsed <code>double</code>.
 </p></li>
 
 <li><p>
 If <code>%z</code> appears in the <code>format</code> string and an offset is
-successfully parsed, the overloads taking <code>sys_time</code> interprets the
+successfully parsed, the overloads taking <code>sys_time</code>, <code>utc_time</code>,
+<code>tai_time</code> and <code>gps_time</code> interpret the
 parsed time as a local time and subtracts the offset prior to assigning the
 value to <code>tp</code>, resulting in a value of <code>tp</code> representing a
-UTC timestamp.  The overloads taking <code>local_time</code> require a valid
+UTC timestamp.  The remaining overloads require a valid
-parse of the offset, but then ignore the offset in assigning a value to the
+parse of the offset, but then ignore the offset in assigning a value to
-<code>local_time&lt;Duration&gt;&amp; tp</code>.  If <code>offset</code> is
+<code>tp</code>.  If <code>offset</code> is not equal to <code>nullptr</code>,
-passed in, on successful parse it will hold the value represented by
+on successful parse <code>*offset</code> will hold the value represented by
 <code>%z</code> if present, or will be assigned <code>0min</code> if
 <code>%z</code> is not present.
 </p>
@@ -2285,11 +2275,13 @@ hours digit is optional:
 <li><p>
 If <code>%Z</code> appears in the <code>format</code> string then an
 abbreviation is required in that position for a successful parse.  The
-abbreviation will be parsed as a <code>std::string</code> (delimited by white
+abbreviation will be parsed as a <code>std::basic_string&lt;CharT, Traits&gt;</code>
+(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 <code>tp</code>.  Using
+abbreviation, and has no impact on the value parsed into <code>tp</code>.  If
-the overloads that take a <code>std::string&amp;</code> one can discover what
+ <code>abbrev</code> is not equal to <code>nullptr</code> one can discover what
-that parsed abbreviation is.  On successful parse, <code>abbrev</code> will be
+that parsed abbreviation is.  On successful parse, and if <code>abbrev != nullptr</code>,
+<code>*abbrev</code> will be
 assigned the value represented by <code>%Z</code> if present, or assigned the
 empty string if <code>%Z</code> is not present.
 </p></li>
@@ -2304,6 +2296,56 @@ Given a UTC offset, one might even narrow that list down further.
 </blockquote>
 </blockquote>
 
+<a name="parse"></a><h3><code>parse</code></h3>
+<blockquote>
+<p>
+Each of the functions below return a <i>manipulator</i> which can be used to extract the
+desired information from a stream.  These functions do not participate in overload
+resolution unless <code>Parsable</code> has a corresponding <code>from_stream</code>
+overload.
+</p>
+
+<pre>
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp);
+
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev);
+
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+      std::chrono::minutes&amp; offset);
+
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const std::basic_string&lt;CharT, Traits&gt;&amp; format, Parsable&amp; tp,
+      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev, std::chrono::minutes&amp; offset);
+
+// const CharT* formats
+
+template &lt;class Parsable, class CharT&gt;
+<i>unspecified</i>
+parse(const CharT* format, Parsable&amp; tp);
+
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const CharT* format, Parsable&amp; tp, std::basic_string&lt;CharT, Traits&gt;&amp; abbrev);
+
+template &lt;class Parsable, class CharT&gt;
+<i>unspecified</i>
+parse(const CharT* format, Parsable&amp; tp, std::chrono::minutes&amp; offset);
+
+template &lt;class Parsable, class CharT, class Traits&gt;
+<i>unspecified</i>
+parse(const CharT* format, Parsable&amp; tp,
+      std::basic_string&lt;CharT, Traits&gt;&amp; abbrev, std::chrono::minutes&amp; offset);
+</pre>
+</blockquote>
+
 <a name="utc_clock"></a><h3><code>utc_clock</code></h3>
 <blockquote>
 <pre>