date.sgml

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

  guint julian : 1;    /* julian is valid */
  guint dmy    : 1;    /* dmy is valid */

  /* DMY representation */
  guint day    : 6;
  guint month  : 4;
  guint year   : 16;
};
</programlisting>
<para>
Represents a day between January 1, Year 1 and a few thousand years in
the future. None of its members should be accessed directly. If the
<structname>GDate</structname> is obtained from <link linkend="g-date-new">g_date_new</link>(), it will
be safe to mutate but invalid and thus not safe for calendrical computations.
If it's declared on the stack, it will contain garbage so must be
initialized with <link linkend="g-date-clear">g_date_clear</link>(). <link linkend="g-date-clear">g_date_clear</link>() makes the date invalid
but sane. An invalid date doesn't represent a day, it's "empty." A
date becomes valid after you set it to a Julian day or you set a day,
month, and year.
</para></refsect2>
<refsect2>
<title><anchor id="GTime">GTime</title>
<programlisting>typedef gint32  GTime;
</programlisting>
<para>
Simply a replacement for <type>time_t</type>. Unrelated to <link linkend="GTimer">GTimer</link>.
</para></refsect2>
<refsect2>
<title><anchor id="GDateDMY">enum GDateDMY</title>
<programlisting>typedef enum
{
  G_DATE_DAY   = 0,
  G_DATE_MONTH = 1,
  G_DATE_YEAR  = 2
} GDateDMY;
</programlisting>
<para>
This enumeration isn't used in the API, but may be useful if you need
to mark a number as a day, month, or year.
</para></refsect2>
<refsect2>
<title><anchor id="GDateDay">GDateDay</title>
<programlisting>typedef guint8  GDateDay;   /* day of the month */
</programlisting>
<para>
Integer representing a day of the month; between 1 and
31. <link linkend="G-DATE-BAD-DAY-CAPS">G_DATE_BAD_DAY</link> represents an invalid day of the month.
</para></refsect2>
<refsect2>
<title><anchor id="GDateMonth">enum GDateMonth</title>
<programlisting>typedef enum
{
  G_DATE_BAD_MONTH = 0,
  G_DATE_JANUARY   = 1,
  G_DATE_FEBRUARY  = 2,
  G_DATE_MARCH     = 3,
  G_DATE_APRIL     = 4,
  G_DATE_MAY       = 5,
  G_DATE_JUNE      = 6,
  G_DATE_JULY      = 7,
  G_DATE_AUGUST    = 8,
  G_DATE_SEPTEMBER = 9,
  G_DATE_OCTOBER   = 10,
  G_DATE_NOVEMBER  = 11,
  G_DATE_DECEMBER  = 12
} GDateMonth;
</programlisting>
<para>
Enumeration representing a month; values are <link linkend="G-DATE-JANUARY-CAPS">G_DATE_JANUARY</link>,
<link linkend="G-DATE-FEBRUARY-CAPS">G_DATE_FEBRUARY</link>, etc. <link linkend="G-DATE-BAD-MONTH-CAPS">G_DATE_BAD_MONTH</link> is the invalid value.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_DATE_BAD_MONTH</literal></entry>
<entry>invalid value.
</entry>
</row>
<row>
<entry><literal>G_DATE_JANUARY</literal></entry>
<entry>January.
</entry>
</row>
<row>
<entry><literal>G_DATE_FEBRUARY</literal></entry>
<entry>February.
</entry>
</row>
<row>
<entry><literal>G_DATE_MARCH</literal></entry>
<entry>March.
</entry>
</row>
<row>
<entry><literal>G_DATE_APRIL</literal></entry>
<entry>April.
</entry>
</row>
<row>
<entry><literal>G_DATE_MAY</literal></entry>
<entry>May.
</entry>
</row>
<row>
<entry><literal>G_DATE_JUNE</literal></entry>
<entry>June.
</entry>
</row>
<row>
<entry><literal>G_DATE_JULY</literal></entry>
<entry>July.
</entry>
</row>
<row>
<entry><literal>G_DATE_AUGUST</literal></entry>
<entry>August.
</entry>
</row>
<row>
<entry><literal>G_DATE_SEPTEMBER</literal></entry>
<entry>September.
</entry>
</row>
<row>
<entry><literal>G_DATE_OCTOBER</literal></entry>
<entry>October.
</entry>
</row>
<row>
<entry><literal>G_DATE_NOVEMBER</literal></entry>
<entry>November.
</entry>
</row>
<row>
<entry><literal>G_DATE_DECEMBER</literal></entry>
<entry>December.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDateYear">GDateYear</title>
<programlisting>typedef guint16 GDateYear;
</programlisting>
<para>
Integer representing a year; <link linkend="G-DATE-BAD-YEAR-CAPS">G_DATE_BAD_YEAR</link> is the invalid
value. The year must be 1 or higher; negative (BC) years are not
allowed. The year is represented with four digits.
</para></refsect2>
<refsect2>
<title><anchor id="GDateWeekday">enum GDateWeekday</title>
<programlisting>typedef enum
{
  G_DATE_BAD_WEEKDAY  = 0,
  G_DATE_MONDAY       = 1,
  G_DATE_TUESDAY      = 2,
  G_DATE_WEDNESDAY    = 3,
  G_DATE_THURSDAY     = 4,
  G_DATE_FRIDAY       = 5,
  G_DATE_SATURDAY     = 6,
  G_DATE_SUNDAY       = 7
} GDateWeekday;
</programlisting>
<para>
Enumeration representing a day of the week; <link linkend="G-DATE-MONDAY-CAPS">G_DATE_MONDAY</link>,
<link linkend="G-DATE-TUESDAY-CAPS">G_DATE_TUESDAY</link>, etc. <link linkend="G-DATE-BAD-WEEKDAY-CAPS">G_DATE_BAD_WEEKDAY</link> is an invalid weekday.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_DATE_BAD_WEEKDAY</literal></entry>
<entry>invalid value.
</entry>
</row>
<row>
<entry><literal>G_DATE_MONDAY</literal></entry>
<entry>Monday.
</entry>
</row>
<row>
<entry><literal>G_DATE_TUESDAY</literal></entry>
<entry>Tuesday.
</entry>
</row>
<row>
<entry><literal>G_DATE_WEDNESDAY</literal></entry>
<entry>Wednesday.
</entry>
</row>
<row>
<entry><literal>G_DATE_THURSDAY</literal></entry>
<entry>Thursday.
</entry>
</row>
<row>
<entry><literal>G_DATE_FRIDAY</literal></entry>
<entry>Friday.
</entry>
</row>
<row>
<entry><literal>G_DATE_SATURDAY</literal></entry>
<entry>Saturday.
</entry>
</row>
<row>
<entry><literal>G_DATE_SUNDAY</literal></entry>
<entry>Sunday.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="G-DATE-BAD-DAY-CAPS">G_DATE_BAD_DAY</title>
<programlisting>#define G_DATE_BAD_DAY    0U
</programlisting>
<para>
Represents an invalid <link linkend="GDateDay">GDateDay</link>.
</para></refsect2>
<refsect2>
<title><anchor id="G-DATE-BAD-JULIAN-CAPS">G_DATE_BAD_JULIAN</title>
<programlisting>#define G_DATE_BAD_JULIAN 0U
</programlisting>
<para>
Represents an invalid Julian day number.
</para></refsect2>
<refsect2>
<title><anchor id="G-DATE-BAD-YEAR-CAPS">G_DATE_BAD_YEAR</title>
<programlisting>#define G_DATE_BAD_YEAR   0U
</programlisting>
<para>
Represents an invalid year.
</para></refsect2>
<refsect2>
<title><anchor id="g-date-new">g_date_new ()</title>
<programlisting><link linkend="GDate">GDate</link>*      g_date_new                      (void);</programlisting>
<para>
Allocates a <link linkend="GDate">GDate</link> and initializes it to a sane state. The new date will
be cleared (as if you'd called <link linkend="g-date-clear">g_date_clear</link>()) but invalid (it won't
represent an existing day). Free the return value with <link linkend="g-date-free">g_date_free</link>().
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated <link linkend="GDate">GDate</link>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-new-dmy">g_date_new_dmy ()</title>
<programlisting><link linkend="GDate">GDate</link>*      g_date_new_dmy                  (<link linkend="GDateDay">GDateDay</link> day,
                                             <link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> year);</programlisting>
<para>
Like <link linkend="g-date-new">g_date_new</link>(), but also sets the value of the date. Assuming the
day-month-year triplet you pass in represents an existing day, the
returned date will 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>day</parameter>&nbsp;:</entry>
<entry>day of the month.
</entry></row>
<row><entry align="right"><parameter>month</parameter>&nbsp;:</entry>
<entry>month of the year.
</entry></row>
<row><entry align="right"><parameter>year</parameter>&nbsp;:</entry>
<entry>year
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly-allocated <link linkend="GDate">GDate</link> initialized with <parameter>day</parameter>, <parameter>month</parameter>, and <parameter>year</parameter>.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-date-new-julian">g_date_new_julian ()</title>
<programlisting><link linkend="GDate">GDate</link>*      g_date_new_julian               (<link linkend="guint32">guint32</link> julian_day);</programlisting>
<para>
Like <link linkend="g-date-new">g_date_new</link>(), but also sets the value of the date. Assuming the
Julian day number you pass in is valid (greater than 0, less than an
unreasonably large number), the returned date will be valid.