<!--
    Licensed to the Apache Software  Foundation (ASF) under one or more
    contributor  license agreements.  See  the NOTICE  file distributed
    with  this  work  for  additional information  regarding  copyright
    ownership.   The ASF  licenses this  file to  you under  the Apache
    License, Version  2.0 (the  License); you may  not use  this file
    except in  compliance with the License.   You may obtain  a copy of
    the License at

    http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the  License is distributed on an  "AS IS" BASIS,
    WITHOUT  WARRANTIES OR CONDITIONS  OF ANY  KIND, either  express or
    implied.   See  the License  for  the  specific language  governing
    permissions and limitations under the License.

    Copyright 1999-2007 Rogue Wave Software, Inc.
-->

<HTML>
<HEAD>
<TITLE>time_get</TITLE>
<LINK REL=StyleSheet HREF="../rw.css" TYPE="text/css" TITLE="Apache stdcxx Stylesheet"></HEAD>
<BODY BGCOLOR=#FFFFFF>
<A HREF="swap-ranges.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="time-get-byname.html"><IMG SRC="images/bnext.gif" WIDTH=25 HEIGHT=21 ALT="Next file" BORDER=O></A><DIV CLASS="DOCUMENTNAME"><B>Apache C++ Standard Library Reference Guide</B></DIV>
<H2>time_get</H2>
<P><B>Library:</B>&nbsp;&nbsp;<A HREF="2-6.html">Localization</A></P>

<PRE><HR>        <IMG SRC="images/inherits.gif"> <B><I>time_base</I></B> 
<B><I>time_get</I></B> 
        <IMG SRC="images/inherits.gif"> <B><I>locale::facet</I></B> <HR></PRE>
<UL>
<LI><A HREF="#sec1">Local Index</A></LI>
<LI><A HREF="#sec2">Summary</A></LI>
<LI><A HREF="#sec3">Synopsis</A></LI>
<LI><A HREF="#sec4">Specializations</A></LI>
<LI><A HREF="#sec5">Description</A></LI>
<LI><A HREF="#sec6">Interface</A></LI>
<LI><A HREF="#sec7">Member Types</A></LI>
<LI><A HREF="#sec8">Constructors</A></LI>
<LI><A HREF="#sec9">Destructor</A></LI>
<LI><A HREF="#sec10">Facet ID</A></LI>
<LI><A HREF="#sec11">Public Member Functions</A></LI>
<LI><A HREF="#sec12">Extensions of this Implementation</A></LI>
<LI><A HREF="#sec13">Protected Member Functions</A></LI>
<LI><A HREF="#sec14">Extension of this Implementation</A></LI>
<LI><A HREF="#sec15">Example</A></LI>
<LI><A HREF="#sec16">See Also</A></LI>
<LI><A HREF="#sec17">Standards Conformance</A></LI>
</UL>
<A NAME="sec1"><H3>Local Index</H3></A>
<H4>Members</H4>
<UL><TABLE CELLPADDING=3>
<TR><TD VALIGN=top>
<A HREF="#idx1227">char_type</A><BR>
<A HREF="#idx1232">date_order()</A><BR>
<A HREF="#idx1235">do_date_order()</A><BR>
<A HREF="#idx1241">do_get()</A><BR>
<A HREF="#idx1236">do_get_date()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx1237">do_get_monthname()</A><BR>
<A HREF="#idx1238">do_get_time()</A><BR>
<A HREF="#idx1239">do_get_weekday()</A><BR>
<A HREF="#idx1240">do_get_year()</A><BR>
<A HREF="#idx1233">get()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx1232">get_date()</A><BR>
<A HREF="#idx1232">get_monthname()</A><BR>
<A HREF="#idx1232">get_time()</A><BR>
<A HREF="#idx1232">get_weekday()</A><BR>
<A HREF="#idx1232">get_year()</A><BR>
</TD>
<TD VALIGN=top><A HREF="#idx1231">id</A><BR>
<A HREF="#idx1228">iter_type</A><BR>
<A HREF="#idx1229">time_get()</A><BR>
<A HREF="#idx1230">~time_get()</A><BR>
</TD></TR>
</TABLE></UL>

<A NAME="sec2"><H3>Summary</H3></A>
<P>A time formatting facet for input, and for parsing of date and time values </P>
<A NAME="sec3"><H3>Synopsis</H3></A>

<PRE>#include &lt;locale&gt;

namespace std {
  class time_base;
  template &lt;class charT, class InputIterator = 
              istreambuf_iterator&lt;charT&gt; &gt;
  class time_get;
}
</PRE>
<A NAME="sec4"><H3>Specializations</H3></A>
<P>The primary template can be implicitly or explicitly specialized on any character type that satisfies the requirements on the type of character used by iostream class templates, and on any iterator type that satisfies the requirements of Input Iterator.</P>
<A NAME="sec5"><H3>Description</H3></A>
<P>Members of the <B><I>time_get</I></B> facet extract time and date components from a sequence of characters and store the resulting values in one or more members of a <SAMP>struct tm</SAMP> argument. The functions parse the input sequence according to the same locale-specific format as the one used by the <A HREF="time-put.html">time_put</A> facet to format time and date values. If the sequence does not match the format, the facet indicates an error by setting <SAMP>ios_base::failbit</SAMP> in <SAMP>err</SAMP>. See member function descriptions for details.</P>
<P>The <B><I>time_base</I></B> class includes a set of values for specifying the order in which the three parts of a date appear. The <SAMP>dateorder</SAMP> function returns one of these five possible values, as illustrated in <A HREF="time-get.html#Table&nbsp;33">Table&nbsp;33</A>:</P>
<H4><A NAME="Table&nbsp;33">Table&nbsp;33: Possible values of the dateorder function of the time_base class&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Order</B>
</td>
<td valign=top><B>Meaning</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>no_order</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Date format has no set ordering</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>dmy</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Date order is day, month, year</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>mdy</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Date order is month, day, year</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ymd</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Date order is year, month, day</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>ydm</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Date order is year, day, month</P>
</td>
</tr>
</TABLE>
<A NAME="sec6"><H3>Interface</H3></A>

<UL><PRE>namespace std {
  class time_base {
    public:
    enum dateorder { no_order, dmy, mdy, ymd, ydm };
  };

  template &lt;class charT, class InputIterator = 
            istreambuf_iterator&lt;charT&gt; &gt;
  class time_get : public locale::facet, public time_base {

    public:
    typedef charT  char_type;
    typedef InputIterator  iter_type;
    explicit time_get(size_t = 0);
    dateorder date_order()  const;
    iter_type get_time(iter_type, iter_type, ios_base&amp;,
                       ios_base::iostate&amp;, tm*)  const;
    iter_type get_date(iter_type, iter_type, ios_base&amp;,
                       ios_base::iostate&amp;, tm*)  const;
    iter_type get_weekday(iter_type, iter_type, ios_base&amp;,
                          ios_base::iostate&amp;, tm*) const;
    iter_type get_monthname(iter_type, iter_type, ios_base&amp;,
                            ios_base::iostate&amp;, tm*) const;
    iter_type get_year(iter_type, iter_type, ios_base&amp;,
                       ios_base::iostate&amp;, tm*) const;

     // extension of this implementation 
     iter_type
     get (iter_type, iter_type, ios_base&amp;, ios_base::iostate&amp;,
          tm*, const char_type*, const char_type*) const; 

     // extension of this implementation 
     iter_type 
     get (iter_type, iter_type, ios_base&amp;, ios_base::iostate&amp;,
          tm*, char, char) const;

    static locale::id id;

    protected:
    virtual dateorder do_date_order()  const;
    virtual iter_type do_get_time(iter_type, iter_type,
           ios_base&amp;, ios_base::iostate&amp;, tm*) const;
    virtual iter_type do_get_date(iter_type, iter_type,
          ios_base&amp;, ios_base::iostate&amp;, tm*) const;
    virtual iter_type do_get_weekday(iter_type, iter_type,
          ios_base&amp;, ios_base::iostate&amp;, tm*) const;
    virtual iter_type do_get_monthname(iter_type, iter_type,
          ios_base&amp;, ios_base::iostate&amp;, tm*) const;
    virtual iter_type do_get_year(iter_type, iter_type,
          ios_base&amp;, ios_base::iostate&amp;, tm*) const;
 
    // extension of this implementation 
    virtual iter_type 
    do_get (iter_type, iter_type, ios_base&amp;, ios_base::iostate&amp;,
            tm*, char, char) const;
  };
}
</PRE></UL>
<A NAME="sec7"><H3>Member Types</H3></A>

<A NAME="idx1227"></A><PRE><B>char_type</B></PRE>
<UL>
<P>Type of the first template argument, <SAMP>charT</SAMP>.</P>
</UL>


<A NAME="idx1228"></A><PRE><B>iter_type</B></PRE>
<UL>
<P>Type of the second template argument, <SAMP>InputIterator</SAMP>.</P>
</UL>

<A NAME="sec8"><H3>Constructors</H3></A>

<A NAME="idx1229"></A><PRE>explicit <B>time_get</B>(size_t refs = 0) </PRE>
<UL>
<P>Constructs a <B><I>time_get</I></B> object. Calls<SAMP> locale::facet (refs)</SAMP>.</P>
<P>The <SAMP>refs</SAMP> argument is set to the initial value of the <B><I>time_get</I></B> object's reference count. A <B><I>time_get</I></B> object <SAMP>f</SAMP> constructed with <SAMP>(refs == 0)</SAMP> that is installed in one or more locale objects will be destroyed and the storage it occupies will be deallocated when the last locale object containing the facet is destroyed, as if by calling <SAMP>delete</SAMP> <SAMP>static_cast&lt;locale::facet*&gt;(&amp;f)</SAMP>. </P>
<P>A <B><I>time_get</I></B> object constructed with <SAMP>(refs != 0)</SAMP> will not be destroyed by any locale objects in which it may have been installed. </P>
</UL>

<A NAME="sec9"><H3>Destructor</H3></A>

<A NAME="idx1230"></A><PRE>virtual <B>~time_get</B>();</PRE>
<UL>
<P>Destroys the facet.</P>
</UL>

<A NAME="sec10"><H3>Facet ID</H3></A>

<A NAME="idx1231"></A><PRE>static locale::id <B>id</B>;</PRE>
<UL>
<P>Unique identifier for this type of facet. </P>
</UL>

<A NAME="sec11"><H3>Public Member Functions</H3></A>
<P>The public members of the <B><I>time_get</I></B> facet include an interface to protected members. Each public member function <SAMP>get_xxx()</SAMP> calls the corresponding protected virtual member function <SAMP>do_get_xxx()</SAMP>. For instance, the public function <SAMP>get_time()</SAMP> calls its protected cousin <SAMP>do_get_time()</SAMP>. The result   of the call may be cached. Subsequent calls to the public function with the same arguments may return the cached result to avoid the expense of repeatedly calling the virtual function.</P>

<A NAME="idx1232"></A><PRE>dateorder 
<B>date_order</B>()  const; 
iter_type 
<B>get_date</B>(iter_type s, iter_type end, ios_base&amp; f,
         ios_base::iostate&amp; err, tm* t)  const; 
iter_type 
<B>get_monthname</B>(iter_type s, iter_type end, ios_base&amp; f,
              ios_base::iostate&amp; err, tm* t) const; 
iter_type 
<B>get_time</B>(iter_type s, iter_type end, ios_base&amp; f,
         ios_base::iostate&amp; err, tm* t)  const; 
iter_type 
<B>get_weekday</B>(iter_type s, iter_type end, ios_base&amp; f,
            ios_base::iostate&amp; err, tm* t) const; 
iter_type 
<B>get_year</B>(iter_type s, iter_type end, ios_base&amp; f,
         ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Each of these public functions calls the corresponding protected virtual <SAMP>do_xxx()</SAMP> function.</P>
</UL>

<A NAME="sec12"><H3>Extensions of this Implementation</H3></A>

<A NAME="idx1233"></A><PRE>iter_type 
<B>get</B> (iter_type s, iter_type end, ios_base &amp;io,<br>     ios_base::iostate &amp;err,tm *t, const char_type *pat, const<br>     char_type *pat_end) const; </PRE>
<P>The function iterates over characters in the range  <SAMP>[pat,  pat_end)</SAMP> that is composed of zero or more directives. Each directive is composed as follows: either a non-empty sequence of white-space characters (as determined by <SAMP>isspace(io.getloc(), c)</SAMP>); or an ordinary character other than <SAMP>'%'</SAMP> or white-space; or a conversion specification. Each conversion specification   is composed of a leading <SAMP>'%'</SAMP> character followed by an optional conversion modifier, <SAMP>mod</SAMP>, and then by a conversion specifier, <SAMP>fmt</SAMP>, which determines the interpretation of the input character(s). The modifier and specifier characters are obtained by converting the (possibly wide) characters following the leading <SAMP>'%'</SAMP> character extracted from the input sequence as if by <SAMP>use_facet&lt;ctype&lt;char_type&gt; &gt;(io.getloc()).narrow(c, '\0')</SAMP>.        </P>
<P>For each ordinary character other than white-space, the function extracts a character from the input sequence and compares the two.   If they are not equal, the function indicates an error by setting <SAMP>ios_base::failbit</SAMP> in <SAMP>err</SAMP> and the algorithm terminates. If the function reaches the end of the input sequence, it sets  <SAMP>ios_base::eofbit</SAMP> in  <SAMP>err</SAMP> and the algorithm terminates.</P>
<P>For each white-space character, the function extracts any white-space characters from the input sequence until it encounters a character other than white-space. If the function reaches   the   end   of   the   input   sequence,   it   sets <SAMP>ios_base::eofbit</SAMP> in <SAMP>err</SAMP> and the algorithm terminates.</P>
<P>For each conversion specification given by the characters <SAMP>fmt</SAMP> and <SAMP>mod</SAMP>, the function performs <SAMP>s = get (s, end, io, errtmp, t, fmt,  mod)</SAMP> with a <SAMP>errtmp</SAMP> argument of type <SAMP>ios_base::iostate</SAMP> initialized to  <SAMP>ios_base::good</SAMP>. If <SAMP>(errtmp  != ios_base::good)</SAMP> evaluates to true after the call, the function performs <SAMP>err |= errtmp</SAMP> and the algorithm terminates.</P>
<P>Returns an iterator pointing just beyond the last extracted character.</P>

<A NAME="idx1234"></A><PRE>
iter_type 
<B>get</B> (iter_type s, iter_type end, ios_base &amp;io, <br>     ios_base::iostate &amp;err, tm *t, char fmt, char mod = '\0')<br>     const; </PRE>
<UL>
<P>Returns <SAMP>do_get (s, end, io, err, t, fmt, mod)</SAMP>.</P>
</UL>

<A NAME="sec13"><H3>Protected Member Functions</H3></A>
<P>The facet functions parse the string input sequence according to the same locale-specific format as the one used by the <A HREF="time-put.html">time_put</A> facet to format time and date values. If the input sequence does not match the expected format, the functions indicate an error by setting <SAMP>ios_base::failbit</SAMP> in <SAMP>err</SAMP>. If the functions reach the end of the input sequence while attempting to extract additional characters, they set <SAMP>ios_base::eofbit</SAMP> in <SAMP>err</SAMP>. The <SAMP>io</SAMP> argument is used to obtain a reference to the <SAMP>ctype&lt;char_type&gt;</SAMP> facet installed in the object's locale. </P>
<P>The behavior of the functions is undefined if the <SAMP>t</SAMP> pointer does not point to a valid object of type <SAMP>tm</SAMP>. </P>

<A NAME="idx1235"></A><PRE>
virtual dateorder 
<B>do_date_order</B>()  const; </PRE>
<UL>
<P>Returns the a value indicating the relative ordering of the three basic parts of a date. Possible return values are:</P>
<UL>
<LI><P CLASS="LIST"><SAMP>no_order</SAMP>, indicating that the date format has no ordering, an ordering cannot be determined, or the date format contains components other than Month, Day and Year. <SAMP>no_order</SAMP> is never returned by the primary template, but may be used by derived classes. In the C  locale, the function returns <SAMP>mdy</SAMP>.</P></LI>
<LI><P CLASS="LIST">One of <SAMP>dmy</SAMP>, <SAMP>mdy</SAMP>, <SAMP>ymd</SAMP>, <SAMP>ydm</SAMP>, indicating the relative ordering of Day, Month, and Year.</P></LI>
</UL>
</UL>


<A NAME="idx1236"></A><PRE>
virtual iter_type 
<B>do_get_date</B>(iter_type s, iter_type end, ios_base &amp;io,
            ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Fills the appropriate members of the object pointed to by the <SAMP>t</SAMP> argument with values parsed from the character buffer specified by the range <SAMP>[s,end)</SAMP>. Alphabetic characters are compared without regard to case. If the input sequence does not contain a valid date representation corresponding to the <SAMP>"</SAMP><SAMP>%x</SAMP><SAMP>"</SAMP> <SAMP>time_put</SAMP> specifier, then the object pointed to by <SAMP>t</SAMP> is not modified and <SAMP>ios_base::failbit</SAMP> is set in the <SAMP>err</SAMP> argument. </P>
<P>Returns an iterator pointing just beyond the last extracted character. </P>
</UL>


<A NAME="idx1237"></A><PRE>virtual iter_type 
<B>do_get_monthname</B>(iter_type s, ios_base &amp;io,
                 ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Fills the <SAMP>t-&gt;tm_mon</SAMP> member with a month number (<SAMP>0</SAMP> for January) parsed from the character buffer specified by the range <SAMP>[s,end)</SAMP>. This name may be an abbreviation, but the function attempts to read a full name if valid characters are found after an abbreviation. For example, if a full name is <SAMP>"</SAMP><SAMP>December</SAMP><SAMP>"</SAMP>, and an abbreviation is <SAMP>"</SAMP><SAMP>Dec</SAMP><SAMP>"</SAMP>, then the string <SAMP>"</SAMP><SAMP>Dece</SAMP><SAMP>"</SAMP> causes an error. Characters are compared without regard to case. If an error occurs, then the object pointed to by <SAMP>t</SAMP> is not modified and <SAMP>ios_base::failbit</SAMP> is set in the <SAMP>err</SAMP> argument. </P>
<P>Returns an iterator pointing just beyond the last extracted character. </P>
</UL>


<A NAME="idx1238"></A><PRE>virtual iter_type 
<B>do_get_time</B>(iter_type s, iter_type end, os_base &amp;io,
            ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Fills out the appropriate members of the object pointed to by the <SAMP>t</SAMP> argument with time values parsed from the character buffer specified by the range <SAMP>[s,end)</SAMP>. Alphabetic characters are compared without regard to case. If the input sequence does not contain a valid date representation corresponding to the <SAMP>"</SAMP><SAMP>%X</SAMP><SAMP>"</SAMP> <SAMP>time_put</SAMP> specifier, then the object pointed to by <SAMP>t</SAMP> is not modified and <SAMP>ios_base::failbit</SAMP> is set in the <SAMP>err</SAMP> argument. </P>
<P>Returns an iterator pointing just beyond the last extracted character. </P>
</UL>


<A NAME="idx1239"></A><PRE>virtual iter_type 
<B>do_get_weekday</B>(iter_type s, iter_type end, ios_base &amp;io, 
               ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Fills the <SAMP>t-&gt;tm_wday</SAMP> member of the <SAMP>t</SAMP> argument with a weekday number (<SAMP>0</SAMP> for Sunday) parsed from the character buffer specified by the range <SAMP>[s,end)</SAMP>. This name may be an abbreviation, but the function attempts to read a full name if valid characters are found after an abbreviation. For instance, if a full name is <SAMP>"</SAMP><SAMP>Monday</SAMP><SAMP>"</SAMP>, and an abbreviation is <SAMP>"</SAMP><SAMP>Mon</SAMP><SAMP>"</SAMP>, then the string <SAMP>"</SAMP><SAMP>Mond</SAMP>" causes an error. Alphabetic characters are compared without regard to case. If an error occurs, then the object pointed to by <SAMP>t</SAMP> is not modified and <SAMP>ios_base::failbit</SAMP> is set in the <SAMP>err</SAMP> argument. </P>
<P>Returns an iterator pointing just beyond the last extracted character. </P>
</UL>


<A NAME="idx1240"></A><PRE>virtual iter_type 
<B>do_get_year</B>(iter_type s, iter_type end, ios_base &amp;io, 
            ios_base::iostate&amp; err, tm* t) const; </PRE>
<UL>
<P>Fills in the <SAMP>t-&gt;tm_year</SAMP> member of the <SAMP>t</SAMP> argument with a year parsed from the character buffer specified by the range <SAMP>[s,end)</SAMP>. Values in the range <SAMP>[69,99]</SAMP> are assumed to refer to years 1969 through 1999, and values in the range <SAMP>[0, 68]</SAMP> are assumed to refer to years 2000 through 2068; all other values are assumed to include the century. This behavior follows the requirement on the <SAMP>strptime()</SAMP> function of IEEE Std 1003.1-2001. If an error occurs, then <SAMP>ios_base::failbit </SAMP>is set in the <SAMP>err</SAMP> argument. </P>
<P>Returns an iterator pointing just beyond the last extracted character.</P>
</UL>

<A NAME="sec14"><H3>Extension of this Implementation</H3></A>

<A NAME="idx1241"></A><PRE>iter_type 
<B>do_get</B> (iter_type s, iter_type end, ios_base &amp;io,
        ios_base::iostate &amp;err, tm *t, char fmt, char mod)<br>        const; </PRE>
<UL>
<P>Fills the appropriate members of the object pointed to by the <SAMP>t</SAMP> argument with values parsed from the character sequence in the range <SAMP>[s,end)</SAMP> according to the corresponding format specifier and, optionally, modifier (when <SAMP>(mod != '\0')</SAMP> evaluates to <SAMP>true</SAMP>). Alphabetic characters are compared without regard to case. If the input sequence does not match the format of the corresponding specifier and modifier, then the object pointed to by <SAMP>t</SAMP> is not modified and <SAMP>ios_base::failbit</SAMP> is set in the <SAMP>err</SAMP> argument. </P>
<P>The following format specifiers and modifiers are recognized, as illustrated in <A HREF="time-get.html#Table&nbsp;34">Table&nbsp;34</A> and <A HREF="time-get.html#Table&nbsp;35">Table&nbsp;35</A>.</P>
<H4><A NAME="Table&nbsp;34">Table&nbsp;34: Recognized conversion specifiers&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Conversion Specifier</B>
</td>
<td valign=top><B>Description</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%a</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the day of the week. <SAMP>%a</SAMP> uses the locale's weekday names, specifiying either the abbreviated or full name.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%A</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Same as or equivalent to <SAMP>%a</SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%b</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the month. <SAMP>%b</SAMP> uses the locale's month names, specifiying either the abbreviated or full name.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%B</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Same as or equivalent to <SAMP>%b</SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%c</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents date and time formatted appropriate to the locale.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%d</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the day of the month as <SAMP>[01,31]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%D</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the date, expressed as <SAMP>%m / %d / %y</SAMP>. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%e</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Same as or equivalent to <SAMP>%d</SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%h</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Same as or equivalent to <SAMP>%b</SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%H</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the hour in 24-hour clock form as <SAMP>[00,23]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%I</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the hour in 12-hour clock form as <SAMP>[01,12]</SAMP>. Leading zeros are optional.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%j</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the day number of the year as <SAMP>[001,366]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%m</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the month number as <SAMP>[01,12]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%M</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Expresses the minute as <SAMP>[00,59]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%n</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents blank (white) space. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%p</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents "a.m "or "p.m" formatted as appropriate to the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%r</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the 12-hour clock time using the AM/PM notation. In the classic C locale, equivalent to <SAMP>%I : %M : %S %p</SAMP>.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%R</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the time as <SAMP>%H : %M</SAMP>. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%S</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the seconds as <SAMP>[00,60]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%t</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents blank (white) space. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%T</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the time as <SAMP>%H : %M : %S</SAMP>. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%U</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the week number of the year as a decimal number (<SAMP>[00,53]</SAMP>) with Sunday representing as the first day of the week . Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%w</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Expresses the weekday as a decimal number <SAMP>[0,6]</SAMP>. <SAMP>0 </SAMP>represents Sunday. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%W</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">The week number of the year (Monday as the first day of the week) as a decimal number <SAMP>[00,53]</SAMP>. Leading zeros are optional. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%x</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the date in the locale's date format. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%X</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the time in the locale's time format. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%y</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the year within the century. If a century is not specified, values in the range <SAMP>[59,99]</SAMP> will refer to years 1959 to 1999 inclusive, and values in the range <SAMP>[00,58]</SAMP> will refer to years 2000 to 2058 inclusive. Leading zeros are optional.</P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Y</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the year and includes the century (e.g. 1988). </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%%</SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents a literal <SAMP>%</SAMP> character. </P>
</td>
</tr>
</TABLE>
<P><A HREF="time-get.html#Table&nbsp;35">Table&nbsp;35</A> describes the recognized modified conversion specifiers.</P>
<H4><A NAME="Table&nbsp;35">Table&nbsp;35: Recognized modified conversion specifiers&nbsp;</A></H4>
<TABLE BORDER="1" CELLPADDING="3" CELLSPACING="3">
<tr><td valign=top><B>Name</B>
</td>
<td valign=top><B>Description</B>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Ec </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the locale's alternative appropriate date and time conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%EC </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the locale's alternative name of the base year (period) conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Ex </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the locale's alternative date conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%EX </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the locale's alternative time conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Ey </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the offset from <SAMP>%EC</SAMP> (year only) in an alternate locale conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%EY </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the full alternative year conversion. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Od </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the day of the month by using alternate locale numeric symbols. Note, leading zeros are permitted but not required. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Oe </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Same as or equivalent to <SAMP>%Od</SAMP>. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OH </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the hour in 24-hour clock form using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OI </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the hour in 12-hour clock form using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Om </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the month using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OM </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the minutes using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OS </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the seconds using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OU </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the week number of the year, with Sunday as the first day of the week, using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Ow </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the number of the weekday (<SAMP>Sunday=0</SAMP>) using alternative numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%OW </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the week number of the year, with Monday as the first day of the week, using alternate numeric symbols for the locale. </P>
</td>
</tr>
<tr><td valign=top><P CLASS="TABLE"><SAMP>%Oy </SAMP></P>
</td>
<td valign=top><P CLASS="TABLE">Represents the year (offset from <SAMP>%C</SAMP>) using alternate numeric symbols for the locale. </P>
</td>
</tr>
</TABLE>
<P>Returns an iterator pointing just beyond the last extracted character.</P>
</UL>

<A NAME="sec15"><H3>Example</H3></A>

<UL><PRE>#include &lt;ctime&gt;      // for struct tm
#include &lt;locale&gt;     // for locale, time_get
#include &lt;sstream&gt;    // for stringstream
#include &lt;iostream&gt;   // for cout, endl


// Print out a tm struct value in one atomic operation
std::ostream&amp; operator&lt;&lt; (std::ostream &amp;os, const std::tm &amp;t)
{
    std::stringstream strm;

    strm &lt;&lt; "Daylight Savings = "   &lt;&lt; t.tm_isdst
         &lt;&lt; "\nDay of year      = " &lt;&lt; t.tm_yday
         &lt;&lt; "\nDay of week      = " &lt;&lt; t.tm_wday
         &lt;&lt; "\nYear             = " &lt;&lt; t.tm_year
         &lt;&lt; "\nMonth            = " &lt;&lt; t.tm_mon
         &lt;&lt; "\nDay of month     = " &lt;&lt; t.tm_mday
         &lt;&lt; "\nHour             = " &lt;&lt; t.tm_hour
         &lt;&lt; "\nMinute           = " &lt;&lt; t.tm_min
         &lt;&lt; "\nSecond           = " &lt;&lt; t.tm_sec
         &lt;&lt; '\n';

    // guard for thread safety and output synchronization
    const std::ostream::sentry guard (os);

    if (guard)
        os.rdbuf ()-&gt;sputn (strm.str ().c_str (), strm.str ().size ());
    else
        os.setstate (os.failbit);

    return os;
}


int main ()
{
    typedef std::istreambuf_iterator&lt;char, std::char_traits&lt;char&gt; &gt; Iter;

    // time struct to parse date into
    static std::tm timeb;  // zero initialized

    // Unused, required by time_get
    std::ios_base::iostate state;

    // Stream object to read from
    std::istringstream ins ("");

    // Iterators into the stream object
    Iter begin (ins);
    Iter end;

    const std::locale loc ("C");

    // Get a reference to the time_get facet in locale loc.
    const std::time_get&lt;char, Iter&gt; &amp;tg =
        std::use_facet&lt;std::time_get&lt;char, Iter&gt; &gt;(loc);

    // Display time_base::dateorder value.
    std::cout &lt;&lt; "time_base::dateorder == " &lt;&lt; tg.date_order () &lt;&lt; ".\n";
  
    // Insert date string into stream.
    ins.str ("04/07/69");

    // get_date from the stream and output tm contents.
    tg.get_date (begin, end, ins, state, &amp;timeb);
    std::cout &lt;&lt; "Date: Apr 7 1969\n" &lt;&lt; timeb &lt;&lt; std::endl;

    // Insert weekday string into stream.
    ins.str ("Monday");

    // get_weekday from the stream and output tm contents.
    tg.get_weekday (begin, end, ins, state, &amp;timeb);
    std::cout &lt;&lt; "Weekday: Monday\n" &lt;&lt; timeb &lt;&lt; std::endl;
  
    // Insert time string into stream.
    ins.str ("06:47:32");

    // get_time from the stream and output tm contents.
    tg.get_time (begin, end, ins, state, &amp;timeb);
    std::cout &lt;&lt; "Time: 06:47:32\n" &lt;&lt; timeb &lt;&lt; std::endl;

    return 0;
}

Program Output:
time_base::dateorder == 2.
Date: Apr 7 1969
Daylight Savings = 0
Day of year      = 0
Day of week      = 0
Year             = 69
Month            = 3
Day of month     = 7
Hour             = 0
Minute           = 0
Second           = 0

Weekday: Monday
Daylight Savings = 0
Day of year      = 0
Day of week      = 1
Year             = 69
Month            = 3
Day of month     = 7
Hour             = 0
Minute           = 0
Second           = 0

Time: 06:47:32
Daylight Savings = 0
Day of year      = 0
Day of week      = 1
Year             = 69
Month            = 3
Day of month     = 7
Hour             = 6
Minute           = 47
Second           = 32
</PRE></UL>
<A NAME="sec16"><H3>See Also</H3></A>
<P><B><I><A HREF="locale.html">locale</A></I></B>, <A HREF="facets.html">Facets</A>, <B><I><A HREF="time-put.html">time_put</A></I></B></P>
<A NAME="sec17"><H3>Standards Conformance</H3></A>
<P><I>ISO/IEC 14882:1998 -- International Standard for Information Systems -- Programming Language C++, Section 22.2.5.1</I></P>
<P><I>IEEE Std 1003.1-2001 -- </I><I>The Open Group Base Specifications Issue 6, strptime</I></P>

<BR>
<HR>
<A HREF="swap-ranges.html"><IMG SRC="images/bprev.gif" WIDTH=20 HEIGHT=21 ALT="Previous file" BORDER=O></A><A HREF="noframes.html"><IMG SRC="images/btop.gif" WIDTH=56 HEIGHT=21 ALT="Top of Document" BORDER=O></A><A HREF="booktoc.html"><IMG SRC="images/btoc.gif" WIDTH=56 HEIGHT=21 ALT="Contents" BORDER=O></A><A HREF="tindex.html"><IMG SRC="images/bindex.gif" WIDTH=56 HEIGHT=21 ALT="Index page" BORDER=O></A><A HREF="time-get-byname.html"><IMG SRC="images/bnext.gif" WIDTH=20 HEIGHT=21 ALT="Next file" BORDER=O></A>

<!-- Google Analytics tracking code -->
<script src="http://www.google-analytics.com/urchin.js" type="text/javascript">
</script>
<script type="text/javascript">
    _uacct = "UA-1775151-1";
    urchinTracker();
</script>
<!-- end of Google Analytics tracking code -->

</BODY>
</HTML>