## 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

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