date.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>julian_day</parameter>&nbsp;:</entry>
<entry>days since January 1, Year 1.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated <link linkend="GDate">GDate</link> initialized with <parameter>julian_day</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-clear">g_date_clear ()</title>
<programlisting>void        g_date_clear                    (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_dates);</programlisting>
<para>
Initializes one or more <link linkend="GDate">GDate</link> structs to a sane but invalid
state. The cleared dates will not represent an existing date, but will
not contain garbage. Useful to init a date declared on the stack.
Validity can be tested with <link linkend="g-date-valid">g_date_valid</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>pointer to one or more dates to clear.
</entry></row>
<row><entry align="right"><parameter>n_dates</parameter>&nbsp;:</entry>
<entry>number of dates to clear.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-free">g_date_free ()</title>
<programlisting>void        g_date_free                     (<link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Frees a <link linkend="GDate">GDate</link> returned from <link linkend="g-date-new">g_date_new</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-day">g_date_set_day ()</title>
<programlisting>void        g_date_set_day                  (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateDay">GDateDay</link> day);</programlisting>
<para>
Sets the day of the month for a <link linkend="GDate">GDate</link>. If the resulting day-month-year
triplet is invalid, the date will be invalid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>day</parameter>&nbsp;:</entry>
<entry>day to set.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-month">g_date_set_month ()</title>
<programlisting>void        g_date_set_month                (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateMonth">GDateMonth</link> month);</programlisting>
<para>
Sets the month of the year for a <link linkend="GDate">GDate</link>.  If the resulting
day-month-year triplet is invalid, the date will be invalid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>month</parameter>&nbsp;:</entry>
<entry>month to set.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-year">g_date_set_year ()</title>
<programlisting>void        g_date_set_year                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateYear">GDateYear</link> year);</programlisting>
<para>
Sets the year for a <link linkend="GDate">GDate</link>. If the resulting day-month-year triplet is
invalid, the date will be invalid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>year</parameter>&nbsp;:</entry>
<entry>year to set.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-dmy">g_date_set_dmy ()</title>
<programlisting>void        g_date_set_dmy                  (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateDay">GDateDay</link> day,
                                             <link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> y);</programlisting>
<para>
Sets the value of a <link linkend="GDate">GDate</link> from a day, month, and year. The day-month-year 
triplet must be valid; if you aren't sure it is, call <link linkend="g-date-valid-dmy">g_date_valid_dmy</link>() to
check before you set it.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>day</parameter>&nbsp;:</entry>
<entry>day.
</entry></row>
<row><entry align="right"><parameter>month</parameter>&nbsp;:</entry>
<entry>month.
</entry></row>
<row><entry align="right"><parameter>y</parameter>&nbsp;:</entry>
<entry>year.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-julian">g_date_set_julian ()</title>
<programlisting>void        g_date_set_julian               (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint32">guint32</link> julian_date);</programlisting>
<para>
Sets the value of a <link linkend="GDate">GDate</link> from a Julian day number.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>julian_date</parameter>&nbsp;:</entry>
<entry>Julian day number (days since January 1, Year 1).


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-time">g_date_set_time ()</title>
<programlisting>void        g_date_set_time                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GTime">GTime</link> time);</programlisting>
<para>
Sets the value of a date from a <link linkend="GTime">GTime</link> (<type>time_t</type>) value. 
To set the value of a date to the current day, you could write:
<informalexample><programlisting>
g_date_set_time (date, time (NULL));
</programlisting></informalexample>
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link>.
</entry></row>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry><link linkend="GTime">GTime</link> value to set.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-set-parse">g_date_set_parse ()</title>
<programlisting>void        g_date_set_parse                (<link linkend="GDate">GDate</link> *date,
                                             const <link linkend="gchar">gchar</link> *str);</programlisting>
<para>
Parses a user-inputted string <parameter>str</parameter>, and try to figure out what date it
represents, taking the current locale into account. If the string is
successfully parsed, the date will be valid after the call. Otherwise,
it will be invalid. You should check using <link linkend="g-date-valid">g_date_valid</link>() to see
whether the parsing succeeded.
</para>

<para>
This function is not appropriate for file formats and the like; it
isn't very precise, and its exact behavior varies with the
locale. It's intended to be a heuristic routine that guesses what the
user means by a given string (and it does work pretty well in that
capacity).
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link> to fill in.
</entry></row>
<row><entry align="right"><parameter>str</parameter>&nbsp;:</entry>
<entry>string to parse.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-add-days">g_date_add_days ()</title>
<programlisting>void        g_date_add_days                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_days);</programlisting>
<para>
Increments a date some number of days. To move forward by weeks, add
weeks*7 days. The date must be valid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link> to increment.
</entry></row>
<row><entry align="right"><parameter>n_days</parameter>&nbsp;:</entry>
<entry>number of days to move the date forward.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-subtract-days">g_date_subtract_days ()</title>
<programlisting>void        g_date_subtract_days            (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_days);</programlisting>
<para>
Moves a date some number of days into the past. To move by weeks, just
move by weeks*7 days. The date must be valid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link> to decrement.
</entry></row>
<row><entry align="right"><parameter>n_days</parameter>&nbsp;:</entry>
<entry>number of days to move.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-add-months">g_date_add_months ()</title>
<programlisting>void        g_date_add_months               (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_months);</programlisting>
<para>
Increments a date by some number of months. If the day of the month is
greater than 28, this routine may change the day of the month (because
the destination month may not have the current day in it). The date
must be valid.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date</parameter>&nbsp;:</entry>
<entry>a <link linkend="GDate">GDate</link> to increment.
</entry></row>
<row><entry align="right"><parameter>n_months</parameter>&nbsp;:</entry>
<entry>number of months to move forward.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-subtract-months">g_date_subtract_months ()</title>