Time-Related Utility Functions
3
LIBEDATASERVER Library

# Time-Related Utility Functions

Utility functions for time structure manipulation.

## Synopsis

    enum        ETimeParseStatus;
    ETimeParseStatus e_time_parse_date_and_time (const char *value,
                                                 struct tm *result);
    ETimeParseStatus e_time_parse_date          (const char *value,
                                                 struct tm *result);
    ETimeParseStatus e_time_parse_time          (const char *value,
                                                 struct tm *result);
    void        e_time_format_date_and_time     (struct tm *date_tm,
                                                 gboolean use_24_hour_format,
                                                 gboolean show_midnight,
                                                 gboolean show_zero_seconds,
                                                 char *buffer,
                                                 int buffer_size);
    void        e_time_format_time              (struct tm *date_tm,
                                                 gboolean use_24_hour_format,
                                                 gboolean show_zero_seconds,
                                                 char *buffer,
                                                 int buffer_size);
    time_t      e_mktime_utc                    (struct tm *tm);
    void        e_localtime_with_offset         (time_t tt,
                                                 struct tm *tm,
                                                 int *offset);

## Description

## Details

### enum ETimeParseStatus

    typedef enum {
    	E_TIME_PARSE_OK,
    	E_TIME_PARSE_NONE,
    	E_TIME_PARSE_INVALID
    } ETimeParseStatus;

`E_TIME_PARSE_OK`

  The time string was parsed successfully.

`E_TIME_PARSE_NONE`

  The time string was empty.

`E_TIME_PARSE_INVALID`

  The time string was not formatted correctly.

### e_time_parse_date_and_time ()

    ETimeParseStatus e_time_parse_date_and_time (const char *value,
                                                 struct tm *result);

Parses a string `value` containing a date and a time and stores the result in `result`. The date in `value` is expected to be in a format like "Wed 3/13/00 14:20:00", though `gettext()` is used to support the appropriate local formats. There is also some leniency on the format of the string, e.g. the weekday can be skipped or 12-hour formats with am/pm can be used.

`value` :

  The string to parse a date and time from.

`result` :

  A tm to store the result in.

Returns :

  E_TIME_PARSE_OK if the string was successfully parsed, E_TIME_PARSE_NONE if the string was empty, or E_TIME_PARSE_INVALID if the string could not be parsed.

### e_time_parse_date ()

    ETimeParseStatus e_time_parse_date          (const char *value,
                                                 struct tm *result);

Takes in a date string entered by the user and tries to convert it to a struct tm.

`value` :

  A date string.

`result` :

  Return value for the parsed date.

Returns :

  An ETimeParseStatus result code indicating whether `value` was an empty string, a valid date, or an invalid date.

### e_time_parse_time ()

    ETimeParseStatus e_time_parse_time          (const char *value,
                                                 struct tm *result);

Parses `value`, a string containing a time. `value` is expected to be in a format like "14:20:00". `gettext()` is used to support the appropriate local formats and slightly different formats, such as 12-hour formats with am/pm, are accepted as well.

`value` :

  The string to parse a time from.

`result` :

  A tm to store the result in.

Returns :

  An ETimeParseStatus result code indicating whether `value` was an empty string, a valid date, or an invalid date.

### e_time_format_date_and_time ()

    void        e_time_format_date_and_time     (struct tm *date_tm,
                                                 gboolean use_24_hour_format,
                                                 gboolean show_midnight,
                                                 gboolean show_zero_seconds,
                                                 char *buffer,
                                                 int buffer_size);

Creates a string representation of the time value `date_tm` and stores it in `buffer`. `buffer_size` should be at least 64 to be safe. If `show_midnight` is FALSE, and the time is midnight, then only the date is stored in `buffer`. If `show_zero_seconds` is FALSE, then if the time has zero seconds only the hour and minute of the time are stored in `buffer`.

`date_tm` :

  The tm to convert to a string.

`use_24_hour_format` :

  A gboolean.

`show_midnight` :

  A gboolean.

`show_zero_seconds` :

  A gboolean.

`buffer` :

  A char buffer to store the time string in.

`buffer_size` :

  The length of `buffer`.

### e_time_format_time ()

    void        e_time_format_time              (struct tm *date_tm,
                                                 gboolean use_24_hour_format,
                                                 gboolean show_zero_seconds,
                                                 char *buffer,
                                                 int buffer_size);

Creates a string representation of a time value in `date_tm` and stores it in `buffer`. `buffer_size` should be at least 64.

`date_tm` :

  The tm to convert to a string.

`use_24_hour_format` :

  A gboolean.

`show_zero_seconds` :

  A gboolean.

`buffer` :

  The char buffer to store the result in.

`buffer_size` :

  The length of `buffer`.

### e_mktime_utc ()

    time_t      e_mktime_utc                    (struct tm *tm);

Like mktime(3), but assumes UTC instead of local timezone.

`tm` :

  The tm to convert to a calendar time representation.

Returns :

  The calendar time representation of `tm`.

### e_localtime_with_offset ()

    void        e_localtime_with_offset         (time_t tt,
                                                 struct tm *tm,
                                                 int *offset);

Converts the calendar time time representation `tt` to a broken-down time representation, store in `tm`, and provides the offset in seconds from UTC time, stored in `offset`.

`tt` :

  The time_t to convert.

`tm` :

  The tm to store the result in.

`offset` :

  The int to store the offset in.