gskdate

gskdate — Date parsing and printing code.

Synopsis




enum        GskDateFormatMask;
gboolean    gsk_date_parse                  (const char *date_str,
                                             struct tm *tm_out,
                                             int *tzoffset_out,
                                             GskDateFormatMask formats_allowed);
gboolean    gsk_date_parse_timet            (const char *date_str,
                                             time_t *out,
                                             GskDateFormatMask formats_allowed);
void        gsk_date_print                  (const struct tm *tm,
                                             char *date_str_out,
                                             int date_str_max_len,
                                             GskDateFormatMask format);
void        gsk_date_print_timet            (time_t t,
                                             char *date_str_out,
                                             int date_str_max_len,
                                             GskDateFormatMask format);
#define     GSK_DATE_MAX_LENGTH

Description

Code to parse and print dates in a number of standard documented formats.

Details

enum GskDateFormatMask

typedef enum
{
  /* rfc 822, obsoleted by rfc 1123:
   *     Sun, 06 Nov 1994 08:49:37 GMT
   */
  GSK_DATE_FORMAT_1123 = (1 << 0),

  /* rfc 850, obsoleted by rfc 1036:
   *     Sunday, 06-Nov-94 08:49:37 GMT
   */
  GSK_DATE_FORMAT_1036 = (1 << 1), /* rfc 850, obsoleted by rfc 1036 */

  /* ansi c's asctime () format:
   *     Sun Nov  6 08:49:37 1994
   */
  GSK_DATE_FORMAT_ANSI_C = (1 << 2),

  /* ISO 8601 defines a variety of timestamps:
       2003-04-04  YYYY-MM-DD
       2003-04
       2003
       2003-035    YYYY-DOY  [DOY=day-of-year]

       NOTE: hyphens may be omitted.

       plus optional time-of-day:

       23:59:59.34  HH:MM:SS.SS
       23:59:59     HH:MM:SS
       23:59        HH:MM   
       23           HH

       NOTE: colons may be omitted.

       Either a space or 'T' separate date/time.

       Timezone:
          Z suffix means UTC
	  +hh:mm or +hhmm or +hh   [or - versions]
     */

  GSK_DATE_FORMAT_ISO8601 = (1 << 3),


  GSK_DATE_FORMAT_HTTP = (GSK_DATE_FORMAT_1123 
                        | GSK_DATE_FORMAT_1036
			| GSK_DATE_FORMAT_ANSI_C)
} GskDateFormatMask;

Formats to accept when parsing with gsk_date_parse().

GSK_DATE_FORMAT_1123 As per RFC 1123.
GSK_DATE_FORMAT_1036 As per RFC 1036.
GSK_DATE_FORMAT_ANSI_C As per the ANSI C standard.
GSK_DATE_FORMAT_ISO8601
GSK_DATE_FORMAT_HTTP All formats permitted by the HTTP standard.

gsk_date_parse ()

gboolean    gsk_date_parse                  (const char *date_str,
                                             struct tm *tm_out,
                                             int *tzoffset_out,
                                             GskDateFormatMask formats_allowed);

Parse a date to a struct tm.

date_str : the string containing a date.
tm_out : location to store the time, as a struct tm. (That is, all the fields are broken out).
tzoffset_out : location to store the timezone offset. (offset stored in minutes)
formats_allowed : bitwise-OR of all the allowed date formats. The parser will try to find a date in any of the allowed formats.
Returns : whether the date was successfully parsed.

gsk_date_parse_timet ()

gboolean    gsk_date_parse_timet            (const char *date_str,
                                             time_t *out,
                                             GskDateFormatMask formats_allowed);

Parse a date to a unix time.

date_str : the string containing a date.
out : location to store the time, as a unix time. That is, the time since the start of 1970 GMT.
formats_allowed : bitwise-OR of all the allowed date formats. The parser will try to find a date in any of the allowed formats.
Returns : whether the date was successfully parsed.

gsk_date_print ()

void        gsk_date_print                  (const struct tm *tm,
                                             char *date_str_out,
                                             int date_str_max_len,
                                             GskDateFormatMask format);

Print the date to a buffer, in the format requested.

tm : the time, separated into pieces. (All fields, even derived fields like tm_wday, must be set.)
date_str_out : buffer to fill with the date as a string.
date_str_max_len : the length of date_str_out. This should be 80 or greater to prevent clipping.
format : which presentation of the date to use.

gsk_date_print_timet ()

void        gsk_date_print_timet            (time_t t,
                                             char *date_str_out,
                                             int date_str_max_len,
                                             GskDateFormatMask format);

Print the date to a buffer, in the format requested.

t : the time, as per unix tradition. That is, this is the time since the beginning of 1970 GMT.
date_str_out : buffer to fill with the date as a string.
date_str_max_len : the length of date_str_out. This should be 80 or greater to prevent clipping.
format : which presentation of the date to use.

GSK_DATE_MAX_LENGTH

#define GSK_DATE_MAX_LENGTH 256

Number of bytes required for any date format given in gsk-date, including the terminating NUL.