# MIMEDirDateTime

## Name

MIMEDirDateTime -- date time object

## Synopsis

    #include <mimedir/mimedir-datetime.h>

    #define             MIMEDIR_DATETIME_NOTZ
    #define             MIMEDIR_DATETIME_UTC

                        MIMEDirDateTime;

    MIMEDirDateTime*    mimedir_datetime_new                (void);
    MIMEDirDateTime*    mimedir_datetime_new_now            (void);
    MIMEDirDateTime*    mimedir_datetime_new_from_datetime  (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);
    MIMEDirDateTime*    mimedir_datetime_new_from_date      (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);
    MIMEDirDateTime*    mimedir_datetime_new_from_time      (guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);
    MIMEDirDateTime*    mimedir_datetime_new_from_gdate     (const GDate *date);
    MIMEDirDateTime*    mimedir_datetime_new_from_time_t    (time_t t);
    MIMEDirDateTime*    mimedir_datetime_new_from_struct_tm (const struct tm *tm);
    void                mimedir_datetime_set_datetime       (MIMEDirDateTime *dt,
                                                             GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);
    void                mimedir_datetime_set_date           (MIMEDirDateTime *dt,
                                                             GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);
    void                mimedir_datetime_set_time           (MIMEDirDateTime *dt,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);
    void                mimedir_datetime_set_gdate          (MIMEDirDateTime *dt,
                                                             const GDate *date);
    void                mimedir_datetime_set_time_t         (MIMEDirDateTime *dt,
                                                             time_t t);
    void                mimedir_datetime_set_struct_tm      (MIMEDirDateTime *dt,
                                                             const struct tm *tm);
    void                mimedir_datetime_get_datetime       (MIMEDirDateTime *dt,
                                                             GDateYear *year,
                                                             GDateMonth *month,
                                                             GDateDay *day,
                                                             guint8 *hour,
                                                             guint8 *minute,
                                                             guint8 *second);
    void                mimedir_datetime_get_date           (MIMEDirDateTime *dt,
                                                             GDateYear *year,
                                                             GDateMonth *month,
                                                             GDateDay *day);
    void                mimedir_datetime_get_time           (MIMEDirDateTime *dt,
                                                             guint8 *hour,
                                                             guint8 *minute,
                                                             guint8 *second);
    void                mimedir_datetime_get_gdate          (MIMEDirDateTime *dt,
                                                             GDate *date);
    time_t              mimedir_datetime_get_time_t         (MIMEDirDateTime *dt);
    void                mimedir_datetime_get_struct_tm      (MIMEDirDateTime *dt,
                                                             struct tm *tm);
    gboolean            mimedir_datetime_is_valid           (MIMEDirDateTime *dt);
    gboolean            mimedir_datetime_is_valid_date      (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);
    gboolean            mimedir_datetime_is_valid_time      (guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);
    void                mimedir_datetime_to_utc             (MIMEDirDateTime *dt);
    gchar*              mimedir_datetime_to_string          (MIMEDirDateTime *dt);
    gint                mimedir_datetime_compare            (MIMEDirDateTime *dt1,
                                                             MIMEDirDateTime *dt2);

## Description

## Details

### MIMEDIR_DATETIME_NOTZ

    #define MIMEDIR_DATETIME_NOTZ (30000)

This date time object does not specify the time zone.

### MIMEDIR_DATETIME_UTC

    #define MIMEDIR_DATETIME_UTC  (30001)

The time is given in Universal Standard Time (UTC).

### MIMEDirDateTime

    typedef struct {
    	GObject parent;

    	GDateYear  year;
    	GDateMonth month;
    	GDateDay   day;
    	guint8     hour;
    	guint8     minute;
    	guint8     second;
    	gint16     timezone;

    	MIMEDirDateTimeFlags flags;

    	MIMEDirDateTimePriv *priv;
    } MIMEDirDateTime;

### mimedir_datetime_new ()

    MIMEDirDateTime*    mimedir_datetime_new                (void);

Creates a new MIME Directory Date/Time object.

Returns : | a new date/time object

### mimedir_datetime_new_now ()

    MIMEDirDateTime*    mimedir_datetime_new_now            (void);

Creates a new MIME Directory Date/Time object. The date and time will be set to the current date/time.

Returns : | a new date/time object

### mimedir_datetime_new_from_datetime ()

    MIMEDirDateTime*    mimedir_datetime_new_from_datetime  (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);

Creates a new MIME Directory Date/Time object and fills it with the supplied date and time.

`year` : |
`month` : |
`day` : |
`hour` : |
`minute` : |
`second` : |
Returns : | a new date/time object

### mimedir_datetime_new_from_date ()

    MIMEDirDateTime*    mimedir_datetime_new_from_date      (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);

Creates a new MIME Directory Date/Time object and fills it with the supplied date.

`year` : |
`month` : |
`day` : |
Returns : | a new date/time object

### mimedir_datetime_new_from_time ()

    MIMEDirDateTime*    mimedir_datetime_new_from_time      (guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);

Creates a new MIME Directory Date/Time object and fills it with the supplied time.

`hour` : |
`minute` : |
`second` : |
Returns : | a new date/time object

### mimedir_datetime_new_from_gdate ()

    MIMEDirDateTime*    mimedir_datetime_new_from_gdate     (const GDate *date);

Creates a new MIME Directory Date/Time object and fills it with the date from `date`.

`date` : | a GDate object
Returns : | a new date/time object

### mimedir_datetime_new_from_time_t ()

    MIMEDirDateTime*    mimedir_datetime_new_from_time_t    (time_t t);

Creates a new MIME Directory Date/Time object and fills it with the date from `t`.

`t` : | time
Returns : | a new date/time object

### mimedir_datetime_new_from_struct_tm ()

    MIMEDirDateTime*    mimedir_datetime_new_from_struct_tm (const struct tm *tm);

Creates a new MIME Directory Date/Time object and fills it with the date from `date`.

`tm` : | a struct tm pointer
Returns : | a new date/time object

### mimedir_datetime_set_datetime ()

    void                mimedir_datetime_set_datetime       (MIMEDirDateTime *dt,
                                                             GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);

Sets the date and time of `dt`.

`dt` : | a MIMEDirDateTime object
`year` : |
`month` : |
`day` : |
`hour` : |
`minute` : |
`second` : |

### mimedir_datetime_set_date ()

    void                mimedir_datetime_set_date           (MIMEDirDateTime *dt,
                                                             GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);

Sets the date of `dt`.

`dt` : | a MIMEDirDateTime object
`year` : |
`month` : |
`day` : |

### mimedir_datetime_set_time ()

    void                mimedir_datetime_set_time           (MIMEDirDateTime *dt,
                                                             guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);

Sets the time of `dt`.

`dt` : | a MIMEDirDateTime object
`hour` : |
`minute` : |
`second` : |

### mimedir_datetime_set_gdate ()

    void                mimedir_datetime_set_gdate          (MIMEDirDateTime *dt,
                                                             const GDate *date);

Sets `dt` to the date of `date`.

`dt` : | a MIMEDirDateTime object
`date` : | a GDate object

### mimedir_datetime_set_time_t ()

    void                mimedir_datetime_set_time_t         (MIMEDirDateTime *dt,
                                                             time_t t);

Sets `dt` to the date of `t`.

`dt` : | a MIMEDirDateTime object
`t` : | the time

### mimedir_datetime_set_struct_tm ()

    void                mimedir_datetime_set_struct_tm      (MIMEDirDateTime *dt,
                                                             const struct tm *tm);

Sets `dt` to the date of `tm`.

`dt` : | a MIMEDirDateTime object
`tm` : | a struct tm pointer

### mimedir_datetime_get_datetime ()

    void                mimedir_datetime_get_datetime       (MIMEDirDateTime *dt,
                                                             GDateYear *year,
                                                             GDateMonth *month,
                                                             GDateDay *day,
                                                             guint8 *hour,
                                                             guint8 *minute,
                                                             guint8 *second);

Gets the date and time of `dt`.

`dt` : | a MIMEDirDateTime object
`year` : |
`month` : |
`day` : |
`hour` : |
`minute` : |
`second` : |

### mimedir_datetime_get_date ()

    void                mimedir_datetime_get_date           (MIMEDirDateTime *dt,
                                                             GDateYear *year,
                                                             GDateMonth *month,
                                                             GDateDay *day);

Gets the date of `dt`.

`dt` : | a MIMEDirDateTime object
`year` : |
`month` : |
`day` : |

### mimedir_datetime_get_time ()

    void                mimedir_datetime_get_time           (MIMEDirDateTime *dt,
                                                             guint8 *hour,
                                                             guint8 *minute,
                                                             guint8 *second);

Gets the time of `dt`.

`dt` : | a MIMEDirDateTime object
`hour` : |
`minute` : |
`second` : |

### mimedir_datetime_get_gdate ()

    void                mimedir_datetime_get_gdate          (MIMEDirDateTime *dt,
                                                             GDate *date);

Gets the date as a GDate.

`dt` : | a MIMEDirDateTime object
`date` : | a GDate object

### mimedir_datetime_get_time_t ()

    time_t              mimedir_datetime_get_time_t         (MIMEDirDateTime *dt);

Gets the the date a time_t. If the date is not representable as time_t -1 is returned.

`dt` : | a MIMEDirDateTime object
Returns : | the time in seconds since the epoch or -1

### mimedir_datetime_get_struct_tm ()

    void                mimedir_datetime_get_struct_tm      (MIMEDirDateTime *dt,
                                                             struct tm *tm);

Gets the date as a struct tm.

`dt` : | a MIMEDirDateTime object
`tm` : | a struct tm pointer

### mimedir_datetime_is_valid ()

    gboolean            mimedir_datetime_is_valid           (MIMEDirDateTime *dt);

Checks whether `dt` is has a valid date and/or time.

`dt` : | a MIMEDirDateTime object
Returns : | validity indicator

### mimedir_datetime_is_valid_date ()

    gboolean            mimedir_datetime_is_valid_date      (GDateYear year,
                                                             GDateMonth month,
                                                             GDateDay day);

Check whether the given date is valid.

`year` : |
`month` : |
`day` : |
Returns : | validity indicator

### mimedir_datetime_is_valid_time ()

    gboolean            mimedir_datetime_is_valid_time      (guint8 hour,
                                                             guint8 minute,
                                                             guint8 second);

Check whether the given time is valid.

`hour` : |
`minute` : |
`second` : |
Returns : | validity indicator

### mimedir_datetime_to_utc ()

    void                mimedir_datetime_to_utc             (MIMEDirDateTime *dt);

Converts the date/time object to a UTC date/time.

`dt` : | a MIMEDirDateTime object

### mimedir_datetime_to_string ()

    gchar*              mimedir_datetime_to_string          (MIMEDirDateTime *dt);

Returns a human-readable, localized string that represents the date and/or the time this object represent. In case that neither date nor time is valid, NULL is returned. Otherwise the returned string must be freed with `g_free()`.

`dt` : | a MIMEDirDateTime object
Returns : | human-readable string representing the date and/or time

### mimedir_datetime_compare ()

    gint                mimedir_datetime_compare            (MIMEDirDateTime *dt1,
                                                             MIMEDirDateTime *dt2);

Compares the dates of `dt1` and `dt2` and return -1 if `dt1` is earlier than `dt2`, 0 if both dates are equal and 1 if `dt1` is later than `d2`. Both dates must be valid.

`dt1` : | a MIMEDirDateTime object
`dt2` : | a second MIMEDirDateTime object
Returns : | -1, 0, or 1