date.sgml

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

<programlisting>void        g_date_subtract_months          (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_months);</programlisting>
<para>
Moves a date some number of months into the past. If the current day of
the month doesn't exist in the destination month, the day of the month
may change. 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_months</parameter>&nbsp;:</entry>
<entry>number of months to move.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-add-years">g_date_add_years ()</title>
<programlisting>void        g_date_add_years                (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_years);</programlisting>
<para>
Increments a date by some number of years. If the date is February 29,
and the destination year is not a leap year, the date will be changed
to February 28. 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_years</parameter>&nbsp;:</entry>
<entry>number of years to move forward.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-subtract-years">g_date_subtract_years ()</title>
<programlisting>void        g_date_subtract_years           (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_years);</programlisting>
<para>
Moves a date some number of years into the past. If the current day
doesn't exist in the destination year (i.e. it's February 29 and you
move to a non-leap-year) then the day is changed to February 29. 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_years</parameter>&nbsp;:</entry>
<entry>number of years to move.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-days-between">g_date_days_between ()</title>
<programlisting><link linkend="gint">gint</link>        g_date_days_between             (const <link linkend="GDate">GDate</link> *date1,
                                             const <link linkend="GDate">GDate</link> *date2);</programlisting>
<para>
Computes the number of days between two dates.
If <parameter>date2</parameter> is prior to <parameter>date1</parameter>, the returned value is negative.
Both dates 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>date1</parameter>&nbsp;:</entry>
<entry>the first date.
</entry></row>
<row><entry align="right"><parameter>date2</parameter>&nbsp;:</entry>
<entry>the second date.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the number of days between <parameter>date1</parameter> and <parameter>date2</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-compare">g_date_compare ()</title>
<programlisting><link linkend="gint">gint</link>        g_date_compare                  (const <link linkend="GDate">GDate</link> *lhs,
                                             const <link linkend="GDate">GDate</link> *rhs);</programlisting>
<para>
<function><link linkend="qsort">qsort</link>()</function>-style comparsion function for dates. Both
dates 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>lhs</parameter>&nbsp;:</entry>
<entry>first date to compare.
</entry></row>
<row><entry align="right"><parameter>rhs</parameter>&nbsp;:</entry>
<entry>second date to compare.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>0 for equal, less than zero if <parameter>lhs</parameter> is less than <parameter>rhs</parameter>,
greater than zero if <parameter>lhs</parameter> is greater than <parameter>rhs</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-clamp">g_date_clamp ()</title>
<programlisting>void        g_date_clamp                    (<link linkend="GDate">GDate</link> *date,
                                             const <link linkend="GDate">GDate</link> *min_date,
                                             const <link linkend="GDate">GDate</link> *max_date);</programlisting>
<para>
If <parameter>date</parameter> is prior to <parameter>min_date</parameter>, sets <parameter>date</parameter> equal to <parameter>min_date</parameter>.
If <parameter>date</parameter> falls after <parameter>max_date</parameter>, sets <parameter>date</parameter> equal to <parameter>max_date</parameter>.
Either <parameter>min_date</parameter> and <parameter>max_date</parameter> may be <literal>NULL</literal>.  All non-<literal>NULL</literal> dates
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 clamp.
</entry></row>
<row><entry align="right"><parameter>min_date</parameter>&nbsp;:</entry>
<entry>minimum accepted value for <parameter>date</parameter>.
</entry></row>
<row><entry align="right"><parameter>max_date</parameter>&nbsp;:</entry>
<entry>maximum accepted value for <parameter>date</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-order">g_date_order ()</title>
<programlisting>void        g_date_order                    (<link linkend="GDate">GDate</link> *date1,
                                             <link linkend="GDate">GDate</link> *date2);</programlisting>
<para>
Checks if <parameter>date1</parameter> is less than or equal to <parameter>date2</parameter>,
and swap the values if this is not the case.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>date1</parameter>&nbsp;:</entry>
<entry>the first date.
</entry></row>
<row><entry align="right"><parameter>date2</parameter>&nbsp;:</entry>
<entry>the second date.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-day">g_date_get_day ()</title>
<programlisting><link linkend="GDateDay">GDateDay</link>    g_date_get_day                  (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the day of the month. 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 extract the day of the month from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>day of the month.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-month">g_date_get_month ()</title>
<programlisting><link linkend="GDateMonth">GDateMonth</link>  g_date_get_month                (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the month of the year. 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 get the month from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>month of the year as a <link linkend="GDateMonth">GDateMonth</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-year">g_date_get_year ()</title>
<programlisting><link linkend="GDateYear">GDateYear</link>   g_date_get_year                 (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the year of a <link linkend="GDate">GDate</link>. 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>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>year in which the date falls.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-julian">g_date_get_julian ()</title>
<programlisting><link linkend="guint32">guint32</link>     g_date_get_julian               (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the Julian day or "serial number" of the <link linkend="GDate">GDate</link>. The
Julian day is simply the number of days since January 1, Year 1; i.e.,
January 1, Year 1 is Julian day 1; January 2, Year 1 is Julian day 2,
etc. 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 extract the Julian day from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>Julian day.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-weekday">g_date_get_weekday ()</title>
<programlisting><link linkend="GDateWeekday">GDateWeekday</link> g_date_get_weekday             (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the day of the week for a <link linkend="GDate">GDate</link>. 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>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>day of the week as a <link linkend="GDateWeekday">GDateWeekday</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-day-of-year">g_date_get_day_of_year ()</title>
<programlisting><link linkend="guint">guint</link>       g_date_get_day_of_year          (const <link linkend="GDate">GDate</link> *date);</programlisting>
<para>
Returns the day of the year, where Jan 1 is the first day of the
year. 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 extract day of year from.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>day of the year.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-get-days-in-month">g_date_get_days_in_month ()</title>
<programlisting><link linkend="guint8">guint8</link>      g_date_get_days_in_month        (<link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> year);</programlisting>
<para>
Returns the number of days in a month, taking leap years into account.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>month</parameter>&nbsp;:</entry>
<entry>month.
</entry></row>
<row><entry align="right"><parameter>year</parameter>&nbsp;:</entry>