## mrptime

mrptime

## Synopsis

    #include <libplanner/planner.h>

    typedef             mrptime;
    #define             MRP_TIME_INVALID
    #define             MRP_TIME_MIN
    #define             MRP_TIME_MAX
    mrptime             mrp_time_current_time               (void);
    mrptime             mrp_time_from_tm                    (struct tm *tm);
    mrptime             mrp_time_compose                    (gint year,
                                                             gint month,
                                                             gint day,
                                                             gint hour,
                                                             gint minute,
                                                             gint second);
    gboolean            mrp_time_decompose                  (mrptime t,
                                                             gint *year,
                                                             gint *month,
                                                             gint *day,
                                                             gint *hour,
                                                             gint *minute,
                                                             gint *second);
    mrptime             mrp_time_from_string                (const gchar *str,
                                                             GError **err);
    gchar *             mrp_time_to_string                  (mrptime t);
    mrptime             mrp_time_from_msdate_string         (const gchar *str);
    mrptime             mrp_time_align_day                  (mrptime t);
    gint                mrp_time_day_of_week                (mrptime t);
    gint                mrp_time_week_number                (mrptime t);
    const gchar *       mrp_time_day_name                   (mrptime t);
    const gchar *       mrp_time_month_name                 (mrptime t);
    const gchar *       mrp_time_month_name_initial         (mrptime t);
    gchar *             mrp_time_format                     (const gchar *format,
                                                             mrptime t);
    void                mrp_time_debug_print                (mrptime t);
    GParamSpec *        mrp_param_spec_time                 (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GParamFlags flags);

## Description

## Details

### mrptime

    typedef long mrptime;

Corresponds to the standard C time_t type.

### MRP_TIME_INVALID

    #define MRP_TIME_INVALID 0

Represents an invalid mrptime value.

### MRP_TIME_MIN

    #define MRP_TIME_MIN 0

Represents the minimum value for mrptime.

### MRP_TIME_MAX

    #define MRP_TIME_MAX 2147483647

Represents the maximium value for mrptime.

### mrp_time_current_time ()

    mrptime             mrp_time_current_time               (void);

Retrieves the current time as an mrptime value.

Returns : | Current time.

### mrp_time_from_tm ()

    mrptime             mrp_time_from_tm                    (struct tm *tm);

Converts a struct tm value to an mrptime value.

`tm` : | pointer to a struct tm time value
Returns : | mrptime value.

### mrp_time_compose ()

    mrptime             mrp_time_compose                    (gint year,
                                                             gint month,
                                                             gint day,
                                                             gint hour,
                                                             gint minute,
                                                             gint second);

Composes an mrptime value from the separate components.

`year` : | the year
`month` : | the month
`day` : | the day
`hour` : | the hour
`minute` : | the minute
`second` : | the second
Returns : | An mrptime value.

### mrp_time_decompose ()

    gboolean            mrp_time_decompose                  (mrptime t,
                                                             gint *year,
                                                             gint *month,
                                                             gint *day,
                                                             gint *hour,
                                                             gint *minute,
                                                             gint *second);

Splits up an mrptime value into its components.

`t` : | an mrptime value to decompose
`year` : | location to store year, or `NULL`
`month` : | location to store month, or `NULL`
`day` : | location to store day, or `NULL`
`hour` : | location to store hour, or `NULL`
`minute` : | location to store minute, or `NULL`
`second` : | location to store second, or `NULL`
Returns : | `TRUE` on success.

### mrp_time_from_string ()

    mrptime             mrp_time_from_string                (const gchar *str,
                                                             GError **err);

Parses an ISO8601 time string and converts it to an mrptime.

`str` : | a string with a time, ISO8601 format
`err` : | Location to store error, or `NULL`
Returns : | Converted time value.

### mrp_time_to_string ()

    gchar *             mrp_time_to_string                  (mrptime t);

Converts a time value to an ISO8601 string.

`t` : | an mrptime time
Returns : | Allocated string that needs to be freed.

### mrp_time_from_msdate_string ()

    mrptime             mrp_time_from_msdate_string         (const gchar *str);

### mrp_time_align_day ()

    mrptime             mrp_time_align_day                  (mrptime t);

Aligns a time value to the start of the day.

`t` : | an mrptime value
Returns : | Aligned value.

### mrp_time_day_of_week ()

    gint                mrp_time_day_of_week                (mrptime t);

Retrieves the day of week of the specified time.

`t` : | an mrptime value
Returns : | The day of week, in the range 0 to 6, where Sunday is 0.

### mrp_time_week_number ()

    gint                mrp_time_week_number                (mrptime t);

Retrieves the week number of the specified time.

`t` : | an mrptime value
Returns : | ISO standard week number.

### mrp_time_day_name ()

    const gchar *       mrp_time_day_name                   (mrptime t);

Retrieves the name of the day of the specified time.

`t` : | an mrptime value
Returns : | The day name, which is static data.

### mrp_time_month_name ()

    const gchar *       mrp_time_month_name                 (mrptime t);

Retrieves the name of the month of the specified time.

`t` : | an mrptime value
Returns : | The month name, which is static data.

### mrp_time_month_name_initial ()

    const gchar *       mrp_time_month_name_initial         (mrptime t);

Retrieves the initial letter for the month of the specified time.

`t` : | an mrptime value
Returns : | The initial, which is static data.

### mrp_time_format ()

    gchar *             mrp_time_format                     (const gchar *format,
                                                             mrptime t);

Formats a string with time values. The following format codes are allowed:

    %a     The abbreviated weekday name (Mon, Tue, ...)
    %A     The full weekday name (Monday, Tuesday, ...)
    %b     The abbreviated month name (Jan, Feb, ...)
    %B     The full month name (January, February, ...)
    %d     The day of the month (01 - 31).
    %e     The day of the month (1 - 31).
    %H     The hour using a 24-hour clock (00 - 23).
    %I     The hour using a 12-hour clock (01 - 12).
    %j     The day of the year (001 - 366).
    %k     The hour using a 24-hour clock (0 to 23).
    %l     The hour using a 12-hour clock (1 - 12).
    %m     The month number (01 to 12).
    %M     The minute (00 - 59).
    %p     Either 'AM' or 'PM' according  to the given time value.
    %P     Like %p but in lowercase.
    %R     The time in 24 hour notation (%H:%M).
    %S     The second (00 - 61).
    %U     The week number, (1 - 53), starting with the first Sunday as the first day of week 1.
    %W     The week number, (1 - 53), starting with the first Monday as the first day of week 1.
    %y     The year without a century (range 00 to 99).
    %Y     The year including the century.

`format` : | format string
`t` : | an mrptime value
Returns : | Newly created string that needs to be freed.

### mrp_time_debug_print ()

    void                mrp_time_debug_print                (mrptime t);

Prints the time on stdout, for debugging purposes.

`t` : | an mrptime

### mrp_param_spec_time ()

    GParamSpec *        mrp_param_spec_time                 (const gchar *name,
                                                             const gchar *nick,
                                                             const gchar *blurb,
                                                             GParamFlags flags);

Convenience function for creating a GParamSpec carrying an mrptime value.

`name` : | name of the property
`nick` : | nick for the propery
`blurb` : | blurb for the property
`flags` : | flags
Returns : | Newly created GparamSpec.