Evolution-Data-Server Reference Manual: Time parsing and formatting

## Time parsing and formatting Time parsing and formatting |

## Functions

ETimeParseStatus | e_time_parse_date_and_time ()
ETimeParseStatus | e_time_parse_date ()
ETimeParseStatus | e_time_parse_date_and_time_ex ()
ETimeParseStatus | e_time_parse_date_ex ()
ETimeParseStatus | e_time_parse_time ()
void | e_time_format_date_and_time ()
void | e_time_format_time ()
time_t | e_mktime_utc ()
void | e_localtime_with_offset ()
gchar * | e_time_get_d_fmt_with_4digit_year ()

## Types and Values

enum | ETimeParseStatus

## Description

## Functions

### e_time_parse_date_and_time ()

    ETimeParseStatus
    e_time_parse_date_and_time (const gchar *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.

#### Parameters

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 gchar *value,
                       struct tm *result);

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

#### Parameters

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_date_and_time_ex ()

    ETimeParseStatus
    e_time_parse_date_and_time_ex (const gchar *value,
                                   struct tm *result,
                                   gboolean *two_digit_year);

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.

#### Parameters

value | The string to parse a date and time from. |
result | A tm to store the result in. |
two_digit_year | set to TRUE, is parsing with two-digit year, else FALSE, but only when not NULL. |

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

Since 2.22

### e_time_parse_date_ex ()

    ETimeParseStatus
    e_time_parse_date_ex (const gchar *value,
                          struct tm *result,
                          gboolean *two_digit_year);

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

#### Parameters

value | A date string. |
result | Return value for the parsed date. |
two_digit_year | set to TRUE, is parsing with two-digit year, else FALSE, but only when not NULL. |

#### Returns

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

Since 2.22

### e_time_parse_time ()

    ETimeParseStatus
    e_time_parse_time (const gchar *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.

#### Parameters

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,
                                 gchar *buffer,
                                 gint 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` .

#### Parameters

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,
                        gchar *buffer,
                        gint 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.

#### Parameters

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.

#### Parameters

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,
                             gint *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` .

#### Parameters

tt | The time_t to convert. |
tm | The tm to store the result in. |
offset | The int to store the offset in. |

### e_time_get_d_fmt_with_4digit_year ()

    gchar *
    e_time_get_d_fmt_with_4digit_year (void);

Retrieves a date format string with a 4-digit year (D_FMT on systems with `nl_langinfo()` available). Free the returned string with `g_free()`.

#### Returns

a newly-allocated date format string

Since 2.22

## Types and Values

### enum ETimeParseStatus

#### Members

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