libchimara/datetime.c

   1 #include <glib.h>
   2 #include "glk.h"
   3
   4 /**
   5  * glk_current_time:
   6  * @time: pointer to a #glktimeval_t structure.
   7  *
   8  * The current Unix time is stored in the structure @time. (The argument may not
   9  * be %NULL.) This is the number of seconds since the beginning of 1970 (UTC).
  10  *
  11  * The first two values in the structure should be considered a single
  12  * <emphasis>signed</emphasis> 64-bit number. This allows the #glktimeval_t to
  13  * store a reasonable range of values in the future and past. The @high_sec
  14  * value will remain zero until sometime in 2106. If your computer is running in
  15  * 1969, perhaps due to an unexpected solar flare, then @high_sec will be
  16  * negative.
  17  *
  18  * The third value in the structure represents a fraction of a second, in
  19  * microseconds (from 0 to 999999). The resolution of the glk_current_time()
  20  * call is platform-dependent; the @microsec value may not be updated
  21  * continuously.
  22  */
  23 void
  24 glk_current_time(glktimeval_t *time)
  25 {
  26         g_return_if_fail(time != NULL);
  27 }
  28
  29 /**
  30  * glk_current_simple_time:
  31  * @factor: Factor by which to divide the time value.
  32  *
  33  * If dealing with 64-bit values is awkward, you can also get the current time
  34  * as a lower-resolution 32-bit value. This is simply the Unix time divided by
  35  * the @factor argument (which must not be zero). For example, if factor is 60,
  36  * the result will be the number of minutes since 1970 (rounded towards negative
  37  * infinity). If factor is 1, you will get the Unix time directly, but the value
  38  * will be truncated starting some time in 2038.
  39  *
  40  * Returns: Unix time divided by @factor, truncated to 32 bits.
  41  */
  42 glsi32
  43 glk_current_simple_time(glui32 factor)
  44 {
  45         g_return_val_if_fail(factor != 0, -1);
  46
  47         return -1;
  48 }
  49
  50 /**
  51  * glk_time_to_date_utc:
  52  * @time: A #glktimeval_t structure as returned by glk_current_time().
  53  * @date: An empty #glkdate_t structure to fill in.
  54  *
  55  * Convert the given timestamp (as returned by glk_current_time()) to a
  56  * broken-out structure. This function returns a date and time in universal time
  57  * (GMT).
  58  *
  59  * <note><para>
  60  *   The seconds value may be 60 because of a leap second.
  61  * </para></note>
  62  */
  63 void
  64 glk_time_to_date_utc(glktimeval_t *time, glkdate_t *date)
  65 {
  66         g_return_if_fail(time != NULL);
  67         g_return_if_fail(date != NULL);
  68 }
  69
  70 /**
  71  * glk_time_to_date_local:
  72  * @time: A #glktimeval_t structure as returned by glk_current_time().
  73  * @date: An empty #glkdate_t structure to fill in.
  74  *
  75  * Does the same thing as glk_time_to_date_utc(), but this function returns
  76  * local time.
  77  */
  78 void
  79 glk_time_to_date_local(glktimeval_t *time, glkdate_t *date)
  80 {
  81         g_return_if_fail(time != NULL);
  82         g_return_if_fail(date != NULL);
  83 }
  84
  85 /**
  86  * glk_simple_time_to_date_utc:
  87  * @time: Timestamp as returned by glk_current_simple_time().
  88  * @factor: Factor by which to multiply @time in order to get seconds.
  89  * @date: An empty #glkdate_t structure to fill in.
  90  *
  91  * Convert the given timestamp (as returned by glk_current_simple_time()) to a
  92  * broken-out structure in universal time. The @time argument is multiplied by
  93  * @factor to produce a Unix timestamp.
  94  *
  95  * Since the resolution of glk_simple_time_to_date_utc() and
  96  * glk_simple_time_to_date_local() is no better than seconds, they will return
  97  * zero for the microseconds value.
  98  */
  99 void
 100 glk_simple_time_to_date_utc(glsi32 time, glui32 factor, glkdate_t *date)
 101 {
 102         g_return_if_fail(factor != 0);
 103         g_return_if_fail(date != NULL);
 104 }
 105
 106 /**
 107  * glk_simple_time_to_date_local:
 108  * @time: Timestamp as returned by glk_current_simple_time().
 109  * @factor: Factor by which to multiply @time in order to get seconds.
 110  * @date: An empty #glkdate_t structure to fill in.
 111  *
 112  * Does the same thing as glk_simple_time_to_date_utc(), but fills in the @date
 113  * structure in local time.
 114  */
 115 void
 116 glk_simple_time_to_date_local(glsi32 time, glui32 factor, glkdate_t *date)
 117 {
 118         g_return_if_fail(factor != 0);
 119         g_return_if_fail(date != NULL);
 120 }
 121
 122 /**
 123  * glk_date_to_time_utc:
 124  * @date: A date in the form of a #glkdate_t structure.
 125  * @time: An empty #glktimeval_t structure to fill in.
 126  *
 127  * Convert the broken-out structure (interpreted as universal time) to a
 128  * timestamp. The weekday value in @date is ignored. The other values need not
 129  * be in their normal ranges; they will be normalized.
 130  *
 131  * If the time cannot be represented by the platform's time library, this may
 132  * return -1 for the seconds value. (I.e., the @high_sec and @low_sec fields
 133  * both $FFFFFFFF. The microseconds field is undefined in this case.)
 134  */
 135 void
 136 glk_date_to_time_utc(glkdate_t *date, glktimeval_t *time)
 137 {
 138         g_return_if_fail(date != NULL);
 139         g_return_if_fail(time != NULL);
 140 }
 141
 142 /**
 143  * glk_date_to_time_local:
 144  * @date: A date in the form of a #glkdate_t structure.
 145  * @time: An empty #glktimeval_t structure to fill in.
 146  *
 147  * Does the same thing as glk_date_to_time_utc(), but interprets the broken-out
 148  * structure as local time.
 149  *
 150  * The glk_date_to_time_local() function may not be smart about Daylight Saving
 151  * Time conversions.
 152  * <note><para>
 153  *   If implemented with the mktime() libc function, it should use the negative
 154  *   @tm_isdst flag to <quote>attempt to divine whether summer time is in
 155  *   effect</quote>.
 156  * </para></note>
 157  */
 158 void
 159 glk_date_to_time_local(glkdate_t *date, glktimeval_t *time)
 160 {
 161         g_return_if_fail(date != NULL);
 162         g_return_if_fail(time != NULL);
 163 }
 164
 165 /**
 166  * glk_date_to_simple_time_utc:
 167  * @date: A date in the form of a #glkdate_t structure.
 168  * @factor: Factor by which to divide the time value.
 169  *
 170  * Convert the broken-out structure (interpreted as universal time) to a
 171  * timestamp divided by @factor. The weekday value in @date is ignored. The
 172  * other values need not be in their normal ranges; they will be normalized.
 173  *
 174  * If the time cannot be represented by the platform's time library, this may
 175  * return -1.
 176  *
 177  * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
 178  * error.
 179  */
 180 glsi32
 181 glk_date_to_simple_time_utc(glkdate_t *date, glui32 factor)
 182 {
 183         g_return_val_if_fail(date != NULL, -1);
 184         g_return_val_if_fail(factor != 0, -1);
 185
 186         return -1;
 187 }
 188
 189 /**
 190  * glk_date_to_simple_time_local:
 191  * @date: A date in the form of a #glkdate_t structure.
 192  * @factor: Factor by which to divide the time value.
 193  *
 194  * Does the same thing as glk_date_to_simple_time_utc(), but interprets the
 195  * broken-out structure as local time.
 196  *
 197  * Returns: a timestamp divided by @factor, and truncated to 32 bits, or -1 on
 198  * error.
 199  */
 200 glsi32
 201 glk_date_to_simple_time_local(glkdate_t *date, glui32 factor)
 202 {
 203         g_return_val_if_fail(date != NULL, -1);
 204         g_return_val_if_fail(factor != 0, -1);
 205
 206         return -1;
 207 }