date.sgml

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

<refentry id="glib-Date-and-Time-Functions">
<refmeta>
<refentrytitle>Date and Time Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Date and Time Functions</refname><refpurpose>calendrical calculations and miscellaneous time stuff.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;


#define     <link linkend="G-USEC-PER-SEC-CAPS">G_USEC_PER_SEC</link>
struct      <link linkend="GTimeVal">GTimeVal</link>;
void        <link linkend="g-get-current-time">g_get_current_time</link>              (<link linkend="GTimeVal">GTimeVal</link> *result);
void        <link linkend="g-usleep">g_usleep</link>                        (<link linkend="gulong">gulong</link> microseconds);
void        <link linkend="g-time-val-add">g_time_val_add</link>                  (<link linkend="GTimeVal">GTimeVal</link> *time,
                                             <link linkend="glong">glong</link> microseconds);

struct      <link linkend="GDate">GDate</link>;
typedef     <link linkend="GTime">GTime</link>;
enum        <link linkend="GDateDMY">GDateDMY</link>;
typedef     <link linkend="GDateDay">GDateDay</link>;
enum        <link linkend="GDateMonth">GDateMonth</link>;
typedef     <link linkend="GDateYear">GDateYear</link>;
enum        <link linkend="GDateWeekday">GDateWeekday</link>;

#define     <link linkend="G-DATE-BAD-DAY-CAPS">G_DATE_BAD_DAY</link>
#define     <link linkend="G-DATE-BAD-JULIAN-CAPS">G_DATE_BAD_JULIAN</link>
#define     <link linkend="G-DATE-BAD-YEAR-CAPS">G_DATE_BAD_YEAR</link>

<link linkend="GDate">GDate</link>*      <link linkend="g-date-new">g_date_new</link>                      (void);
<link linkend="GDate">GDate</link>*      <link linkend="g-date-new-dmy">g_date_new_dmy</link>                  (<link linkend="GDateDay">GDateDay</link> day,
                                             <link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> year);
<link linkend="GDate">GDate</link>*      <link linkend="g-date-new-julian">g_date_new_julian</link>               (<link linkend="guint32">guint32</link> julian_day);
void        <link linkend="g-date-clear">g_date_clear</link>                    (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_dates);
void        <link linkend="g-date-free">g_date_free</link>                     (<link linkend="GDate">GDate</link> *date);

void        <link linkend="g-date-set-day">g_date_set_day</link>                  (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateDay">GDateDay</link> day);
void        <link linkend="g-date-set-month">g_date_set_month</link>                (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateMonth">GDateMonth</link> month);
void        <link linkend="g-date-set-year">g_date_set_year</link>                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateYear">GDateYear</link> year);
void        <link linkend="g-date-set-dmy">g_date_set_dmy</link>                  (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GDateDay">GDateDay</link> day,
                                             <link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> y);
void        <link linkend="g-date-set-julian">g_date_set_julian</link>               (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint32">guint32</link> julian_date);
void        <link linkend="g-date-set-time">g_date_set_time</link>                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="GTime">GTime</link> time);
void        <link linkend="g-date-set-parse">g_date_set_parse</link>                (<link linkend="GDate">GDate</link> *date,
                                             const <link linkend="gchar">gchar</link> *str);

void        <link linkend="g-date-add-days">g_date_add_days</link>                 (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_days);
void        <link linkend="g-date-subtract-days">g_date_subtract_days</link>            (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_days);
void        <link linkend="g-date-add-months">g_date_add_months</link>               (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_months);
void        <link linkend="g-date-subtract-months">g_date_subtract_months</link>          (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_months);
void        <link linkend="g-date-add-years">g_date_add_years</link>                (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_years);
void        <link linkend="g-date-subtract-years">g_date_subtract_years</link>           (<link linkend="GDate">GDate</link> *date,
                                             <link linkend="guint">guint</link> n_years);
<link linkend="gint">gint</link>        <link linkend="g-date-days-between">g_date_days_between</link>             (const <link linkend="GDate">GDate</link> *date1,
                                             const <link linkend="GDate">GDate</link> *date2);
<link linkend="gint">gint</link>        <link linkend="g-date-compare">g_date_compare</link>                  (const <link linkend="GDate">GDate</link> *lhs,
                                             const <link linkend="GDate">GDate</link> *rhs);
void        <link linkend="g-date-clamp">g_date_clamp</link>                    (<link linkend="GDate">GDate</link> *date,
                                             const <link linkend="GDate">GDate</link> *min_date,
                                             const <link linkend="GDate">GDate</link> *max_date);
void        <link linkend="g-date-order">g_date_order</link>                    (<link linkend="GDate">GDate</link> *date1,
                                             <link linkend="GDate">GDate</link> *date2);

<link linkend="GDateDay">GDateDay</link>    <link linkend="g-date-get-day">g_date_get_day</link>                  (const <link linkend="GDate">GDate</link> *date);
<link linkend="GDateMonth">GDateMonth</link>  <link linkend="g-date-get-month">g_date_get_month</link>                (const <link linkend="GDate">GDate</link> *date);
<link linkend="GDateYear">GDateYear</link>   <link linkend="g-date-get-year">g_date_get_year</link>                 (const <link linkend="GDate">GDate</link> *date);
<link linkend="guint32">guint32</link>     <link linkend="g-date-get-julian">g_date_get_julian</link>               (const <link linkend="GDate">GDate</link> *date);
<link linkend="GDateWeekday">GDateWeekday</link> <link linkend="g-date-get-weekday">g_date_get_weekday</link>             (const <link linkend="GDate">GDate</link> *date);
<link linkend="guint">guint</link>       <link linkend="g-date-get-day-of-year">g_date_get_day_of_year</link>          (const <link linkend="GDate">GDate</link> *date);

<link linkend="guint8">guint8</link>      <link linkend="g-date-get-days-in-month">g_date_get_days_in_month</link>        (<link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> year);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-is-first-of-month">g_date_is_first_of_month</link>        (const <link linkend="GDate">GDate</link> *date);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-is-last-of-month">g_date_is_last_of_month</link>         (const <link linkend="GDate">GDate</link> *date);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-is-leap-year">g_date_is_leap_year</link>             (<link linkend="GDateYear">GDateYear</link> year);
<link linkend="guint">guint</link>       <link linkend="g-date-get-monday-week-of-year">g_date_get_monday_week_of_year</link>  (const <link linkend="GDate">GDate</link> *date);
<link linkend="guint8">guint8</link>      <link linkend="g-date-get-monday-weeks-in-year">g_date_get_monday_weeks_in_year</link> (<link linkend="GDateYear">GDateYear</link> year);
<link linkend="guint">guint</link>       <link linkend="g-date-get-sunday-week-of-year">g_date_get_sunday_week_of_year</link>  (const <link linkend="GDate">GDate</link> *date);
<link linkend="guint8">guint8</link>      <link linkend="g-date-get-sunday-weeks-in-year">g_date_get_sunday_weeks_in_year</link> (<link linkend="GDateYear">GDateYear</link> year);

<link linkend="gsize">gsize</link>       <link linkend="g-date-strftime">g_date_strftime</link>                 (<link linkend="gchar">gchar</link> *s,
                                             <link linkend="gsize">gsize</link> slen,
                                             const <link linkend="gchar">gchar</link> *format,
                                             const <link linkend="GDate">GDate</link> *date);
void        <link linkend="g-date-to-struct-tm">g_date_to_struct_tm</link>             (const <link linkend="GDate">GDate</link> *date,
                                             struct <link linkend="tm">tm</link> *tm);

<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid">g_date_valid</link>                    (const <link linkend="GDate">GDate</link> *date);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-day">g_date_valid_day</link>                (<link linkend="GDateDay">GDateDay</link> day);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-month">g_date_valid_month</link>              (<link linkend="GDateMonth">GDateMonth</link> month);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-year">g_date_valid_year</link>               (<link linkend="GDateYear">GDateYear</link> year);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-dmy">g_date_valid_dmy</link>                (<link linkend="GDateDay">GDateDay</link> day,
                                             <link linkend="GDateMonth">GDateMonth</link> month,
                                             <link linkend="GDateYear">GDateYear</link> year);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-julian">g_date_valid_julian</link>             (<link linkend="guint32">guint32</link> julian_date);
<link linkend="gboolean">gboolean</link>    <link linkend="g-date-valid-weekday">g_date_valid_weekday</link>            (<link linkend="GDateWeekday">GDateWeekday</link> weekday);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The <link linkend="GDate">GDate</link> data structure represents a day between January 1, Year 1,
and sometime a few thousand years in the future (right now it will go
to the year 65535 or so, but <link linkend="g-date-set-parse">g_date_set_parse</link>() only parses up to the
year 8000 or so - just count on "a few thousand"). <link linkend="GDate">GDate</link> is meant to
represent everyday dates, not astronomical dates or historical dates
or ISO timestamps or the like. It extrapolates the current Gregorian
calendar forward and backward in time; there is no attempt to change
the calendar to match time periods or locations. <link linkend="GDate">GDate</link> does not store
time information; it represents a <emphasis>day</emphasis>.
</para>

<para>
The <link linkend="GDate">GDate</link> implementation has several nice features; it is only a
64-bit struct, so storing large numbers of dates is very efficient. It
can keep both a Julian and day-month-year representation of the date,
since some calculations are much easier with one representation or the
other. A Julian representation is simply a count of days since some
fixed day in the past; for <link linkend="GDate">GDate</link> the fixed day is January 1, 1 AD.
("Julian" dates in the <link linkend="GDate">GDate</link> API aren't really Julian dates in the
technical sense; technically, Julian dates count from the start of the
Julian period, Jan 1, 4713 BC).
</para>

<para>
<link linkend="GDate">GDate</link> is simple to use. First you need a "blank" date; you can get a
dynamically allocated date from <link linkend="g-date-new">g_date_new</link>(), or you can declare an
automatic variable or array and initialize it to a sane state by
calling <link linkend="g-date-clear">g_date_clear</link>(). A cleared date is sane; it's safe to call
<link linkend="g-date-set-dmy">g_date_set_dmy</link>() and the other mutator functions to initialize the
value of a cleared date. However, a cleared date is initially
<emphasis>invalid</emphasis>, meaning that it doesn't represent a day
that exists. It is undefined to call any of the date calculation
routines on an invalid date. If you obtain a date from a user or other
unpredictable source, you should check its validity with the
<link linkend="g-date-valid">g_date_valid</link>() predicate. <link linkend="g-date-valid">g_date_valid</link>() is also used to check for
errors with <link linkend="g-date-set-parse">g_date_set_parse</link>() and other functions that can
fail. Dates can be invalidated by calling <link linkend="g-date-clear">g_date_clear</link>() again.
</para>

<para>
<emphasis>It is very important to use the API to access the <link linkend="GDate">GDate</link>
struct.</emphasis> Often only the day-month-year or only the Julian
representation is valid. Sometimes neither is valid. Use the API.
</para>

<para>
GLib doesn't contain any time-manipulation functions; however, there
is a <link linkend="GTime">GTime</link> typedef which is equivalent to <type>time_t</type>, and a <link linkend="GTimeVal">GTimeVal</link>
struct which represents a more precise time (with microseconds). You
can request the current time as a <link linkend="GTimeVal">GTimeVal</link> with <link linkend="g-get-current-time">g_get_current_time</link>().
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-USEC-PER-SEC-CAPS">G_USEC_PER_SEC</title>
<programlisting>#define G_USEC_PER_SEC 1000000
</programlisting>
<para>
Number of microseconds in one second (1 million). This macro is provided for
code readability.
</para></refsect2>
<refsect2>
<title><anchor id="GTimeVal">struct GTimeVal</title>
<programlisting>struct GTimeVal
{
  glong tv_sec;
  glong tv_usec;
};
</programlisting>
<para>
Represents a precise time, with seconds and microseconds. Same as the
<structname>struct timeval</structname> returned by the
<function><link linkend="gettimeofday">gettimeofday</link>()</function> UNIX call.
</para><informaltable pgwide="1" frame="none" role="struct">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><link linkend="glong">glong</link> <structfield>tv_sec</structfield></entry>
<entry>seconds.
</entry>
</row>
<row>
<entry><link linkend="glong">glong</link> <structfield>tv_usec</structfield></entry>
<entry>microseconds.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-current-time">g_get_current_time ()</title>
<programlisting>void        g_get_current_time              (<link linkend="GTimeVal">GTimeVal</link> *result);</programlisting>
<para>
Equivalent to the UNIX <function><link linkend="gettimeofday">gettimeofday</link>()</function> function, but portable.</para>
<para>
Equivalent to <function><link linkend="gettimeofday">gettimeofday</link>()</function>, but also works on
Win32. Returns the current time.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>result</parameter>&nbsp;:</entry>
<entry> <link linkend="GTimeVal">GTimeVal</link> structure in which to store current time.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-usleep">g_usleep ()</title>
<programlisting>void        g_usleep                        (<link linkend="gulong">gulong</link> microseconds);</programlisting>
<para>
Pauses the current thread for the given number of microseconds. There
are 1 million microseconds per second (represented by the
<link linkend="G-USEC-PER-SEC-CAPS">G_USEC_PER_SEC</link> macro). <link linkend="g-usleep">g_usleep</link>() may have limited precision,
depending on hardware and operating system; don't rely on the exact
length of the sleep.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>microseconds</parameter>&nbsp;:</entry>
<entry>number of microseconds to pause.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-time-val-add">g_time_val_add ()</title>
<programlisting>void        g_time_val_add                  (<link linkend="GTimeVal">GTimeVal</link> *time,
                                             <link linkend="glong">glong</link> microseconds);</programlisting>
<para>
Adds the given number of microseconds to <parameter>time</parameter>. <parameter>microseconds</parameter> can
also be negative to decrease the value of <parameter>time</parameter>.</para>
<para>

</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>time</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTimeVal">GTimeVal</link>
</entry></row>
<row><entry align="right"><parameter>microseconds</parameter>&nbsp;:</entry>
<entry> number of microseconds to add to <parameter>time</parameter>
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GDate">struct GDate</title>
<programlisting>struct GDate
{
  guint julian_days : 32; /* julian days representation - we use a
                           *  bitfield hoping that 64 bit platforms
                           *  will pack this whole struct in one big
                           *  int
                           */