e-cal-time-util
3
LIBECAL Library

# e-cal-time-util

Time management utility functions.

## Synopsis

    int         time_days_in_month              (int year,
                                                 int month);
    int         time_day_of_year                (int day,
                                                 int month,
                                                 int year);
    int         time_day_of_week                (int day,
                                                 int month,
                                                 int year);
    gboolean    time_is_leap_year               (int year);
    int         time_leap_years_up_to           (int year);
    char*       isodate_from_time_t             (time_t t);
    time_t      time_from_isodate               (const char *str);
    time_t      time_add_day                    (time_t time,
                                                 int days);
    time_t      time_add_week                   (time_t time,
                                                 int weeks);
    time_t      time_day_begin                  (time_t t);
    time_t      time_day_end                    (time_t t);
    time_t      time_add_day_with_zone          (time_t time,
                                                 int days,
                                                 icaltimezone *zone);
    time_t      time_add_week_with_zone         (time_t time,
                                                 int weeks,
                                                 icaltimezone *zone);
    time_t      time_add_month_with_zone        (time_t time,
                                                 int months,
                                                 icaltimezone *zone);
    time_t      time_year_begin_with_zone       (time_t time,
                                                 icaltimezone *zone);
    time_t      time_month_begin_with_zone      (time_t time,
                                                 icaltimezone *zone);
    time_t      time_week_begin_with_zone       (time_t time,
                                                 int week_start_day,
                                                 icaltimezone *zone);
    time_t      time_day_begin_with_zone        (time_t time,
                                                 icaltimezone *zone);
    time_t      time_day_end_with_zone          (time_t time,
                                                 icaltimezone *zone);
    void        time_to_gdate_with_zone         (GDate *date,
                                                 time_t time,
                                                 icaltimezone *zone);

## Description

## Details

### time_days_in_month ()

    int         time_days_in_month              (int year,
                                                 int month);

Returns the number of days in the month. Year is the normal year, e.g. 2001. Month is 0 (Jan) to 11 (Dec).

`year` :

  The year.

`month` :

  The month.

Returns :

  number of days in the given month/year.

### time_day_of_year ()

    int         time_day_of_year                (int day,
                                                 int month,
                                                 int year);

Returns the 1-based day number within the year of the specified date. Year is the normal year, e.g. 2001. Month is 0 to 11.

`day` :

  The day.

`month` :

  The month.

`year` :

  The year.

Returns :

  the day of the year.

### time_day_of_week ()

    int         time_day_of_week                (int day,
                                                 int month,
                                                 int year);

Returns the day of the week for the specified date, 0 (Sun) to 6 (Sat). For the days that were removed on the Gregorian reformation, it returns Thursday. Year is the normal year, e.g. 2001. Month is 0 to 11.

`day` :

  The day.

`month` :

  The month.

`year` :

  The year.

Returns :

  the day of the week for the given date.

### time_is_leap_year ()

    gboolean    time_is_leap_year               (int year);

Returns whether the specified year is a leap year. Year is the normal year, e.g. 2001.

`year` :

  The year.

Returns :

  TRUE if the year is leap, FALSE if not.

### time_leap_years_up_to ()

    int         time_leap_years_up_to           (int year);

Returns the number of leap years since year 1 up to (but not including) the specified year. Year is the normal year, e.g. 2001.

`year` :

  The year.

Returns :

  number of leap years.

### isodate_from_time_t ()

    char*       isodate_from_time_t             (time_t t);

Creates an ISO 8601 UTC representation from a time value.

`t` :

  A time value.

Returns :

  String with the ISO 8601 representation of the UTC time.

### time_from_isodate ()

    time_t      time_from_isodate               (const char *str);

Converts an ISO 8601 UTC time string into a time_t value.

`str` :

  Date/time value in ISO 8601 format.

Returns :

  Time_t corresponding to the specified ISO string. Note that we only allow UTC times at present.

### time_add_day ()

    time_t      time_add_day                    (time_t time,
                                                 int days);

Adds a day onto the time, using local time. Note that if clocks go forward due to daylight savings time, there are some non-existent local times, so the hour may be changed to make it a valid time. This also means that it may not be wise to keep calling `time_add_day()` to step through a certain period - if the hour gets changed to make it valid time, any further calls to `time_add_day()` will also return this hour, which may not be what you want.

`time` :

  A time_t value.

`days` :

  Number of days to add.

Returns :

  a time_t value containing `time` plus the days added.

### time_add_week ()

    time_t      time_add_week                   (time_t time,
                                                 int weeks);

Adds the given number of weeks to a time value.

`time` :

  A time_t value.

`weeks` :

  Number of weeks to add.

Returns :

  a time_t value containing `time` plus the weeks added.

### time_day_begin ()

    time_t      time_day_begin                  (time_t t);

Returns the start of the day, according to the local time.

`t` :

  A time_t value.

Returns :

  the time corresponding to the beginning of the day.

### time_day_end ()

    time_t      time_day_end                    (time_t t);

Returns the end of the day, according to the local time.

`t` :

  A time_t value.

Returns :

  the time corresponding to the end of the day.

### time_add_day_with_zone ()

    time_t      time_add_day_with_zone          (time_t time,
                                                 int days,
                                                 icaltimezone *zone);

Adds or subtracts a number of days to/from the given time_t value, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`days` :

  Number of days to add.

`zone` :

  Timezone to use.

Returns :

  a time_t value containing `time` plus the days added.

### time_add_week_with_zone ()

    time_t      time_add_week_with_zone         (time_t time,
                                                 int weeks,
                                                 icaltimezone *zone);

Adds or subtracts a number of weeks to/from the given time_t value, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`weeks` :

  Number of weeks to add.

`zone` :

  Timezone to use.

Returns :

  a time_t value containing `time` plus the weeks added.

### time_add_month_with_zone ()

    time_t      time_add_month_with_zone        (time_t time,
                                                 int months,
                                                 icaltimezone *zone);

Adds or subtracts a number of months to/from the given time_t value, using the given timezone.

If the day would be off the end of the month (e.g. adding 1 month to 30th January, would lead to an invalid day, 30th February), it moves it down to the last day in the month, e.g. 28th Feb (or 29th in a leap year.)

NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`months` :

  Number of months to add.

`zone` :

  Timezone to use.

Returns :

  a time_t value containing `time` plus the months added.

### time_year_begin_with_zone ()

    time_t      time_year_begin_with_zone       (time_t time,
                                                 icaltimezone *zone);

Returns the start of the year containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`zone` :

  Timezone to use.

Returns :

  the beginning of the year.

### time_month_begin_with_zone ()

    time_t      time_month_begin_with_zone      (time_t time,
                                                 icaltimezone *zone);

Returns the start of the month containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`zone` :

  Timezone to use.

Returns :

  the beginning of the month.

### time_week_begin_with_zone ()

    time_t      time_week_begin_with_zone       (time_t time,
                                                 int week_start_day,
                                                 icaltimezone *zone);

Returns the start of the week containing the given time_t, using the given timezone. week_start_day should use the same values as `mktime()`, i.e. 0 (Sun) to 6 (Sat). NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`week_start_day` :

  Day to use as the starting of the week.

`zone` :

  Timezone to use.

Returns :

  the beginning of the week.

### time_day_begin_with_zone ()

    time_t      time_day_begin_with_zone        (time_t time,
                                                 icaltimezone *zone);

Returns the start of the day containing the given time_t, using the given timezone. NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`zone` :

  Timezone to use.

Returns :

  the beginning of the day.

### time_day_end_with_zone ()

    time_t      time_day_end_with_zone          (time_t time,
                                                 icaltimezone *zone);

Returns the end of the day containing the given time_t, using the given timezone. (The end of the day is the start of the next day.) NOTE: this function is only here to make the transition to the timezone functions easier. New code should use icaltimetype values and `icaltime_adjust()` to add or subtract days, hours, minutes & seconds.

`time` :

  A time_t value.

`zone` :

  Timezone to use.

Returns :

  the end of the day.

### time_to_gdate_with_zone ()

    void        time_to_gdate_with_zone         (GDate *date,
                                                 time_t time,
                                                 icaltimezone *zone);

Converts a time_t value to a GDate structure using the specified timezone. This is analogous to `g_date_set_time()` but takes the timezone into account.

`date` :

  Destination GDate value.

`time` :

  A time value.

`zone` :

  Desired timezone for destination `date`, or NULL if the UTC timezone is desired.