i-cal-time

## i-cal-time i-cal-time |

## Synopsis

    #include <i-cal-time-span>
    #include <i-cal-timetype>
    #include <i-cal-timezone>

    ICalTimetype *      i_cal_time_null_time                (void);
    ICalTimetype *      i_cal_time_null_date                (void);
    ICalTimetype *      i_cal_time_current_time_with_zone   (ICalTimezone *zone);
    ICalTimetype *      i_cal_time_today                    (void);
    ICalTimetype *      i_cal_time_from_timet               (const time_t v,
                                                             gint is_date);
    ICalTimetype *      i_cal_time_from_timet_with_zone     (const time_t v,
                                                             gint is_date,
                                                             ICalTimezone *zone);
    ICalTimetype *      i_cal_time_from_string              (const gchar *str);
    ICalTimetype *      i_cal_time_from_day_of_year         (const gint day,
                                                             const gint year);
    time_t              i_cal_time_as_timet                 (ICalTimetype *tt);
    time_t              i_cal_time_as_timet_with_zone       (ICalTimetype *tt,
                                                             ICalTimezone *zone);
    gchar *             i_cal_time_as_ical_string_r         (ICalTimetype *tt);
    const ICalTimezone * i_cal_time_get_timezone            (ICalTimetype *tt);
    ICalTimetype *      i_cal_time_set_timezone             (ICalTimetype *tt,
                                                             ICalTimezone *zone);
    const gchar *       i_cal_time_get_tzid                 (ICalTimetype *tt);
    gint                i_cal_time_day_of_year              (ICalTimetype *tt);
    gint                i_cal_time_day_of_week              (ICalTimetype *tt);
    gint                i_cal_time_start_doy_of_week        (ICalTimetype *tt);
    gint                i_cal_time_start_doy_week           (ICalTimetype *tt,
                                                             gint fdow);
    gint                i_cal_time_week_number              (ICalTimetype *tt);
    gint                i_cal_time_is_null_time             (ICalTimetype *tt);
    gint                i_cal_time_is_valid_time            (ICalTimetype *tt);
    gint                i_cal_time_is_date                  (ICalTimetype *tt);
    gint                i_cal_time_is_utc                   (ICalTimetype *tt);
    gint                i_cal_time_compare                  (ICalTimetype *a,
                                                             ICalTimetype *b);
    gint                i_cal_time_compare_date_only        (ICalTimetype *a,
                                                             ICalTimetype *b);
    gint                i_cal_time_compare_date_only_tz     (ICalTimetype *a,
                                                             ICalTimetype *b,
                                                             ICalTimezone *zone);
    void                i_cal_time_adjust                   (ICalTimetype *tt,
                                                             const gint days,
                                                             const gint hours,
                                                             const gint minutes,
                                                             const gint seconds);
    ICalTimetype *      i_cal_time_normalize                (ICalTimetype *t);
    ICalTimetype *      i_cal_time_convert_to_zone          (ICalTimetype *t,
                                                             ICalTimezone *zone);
    gint                i_cal_time_days_in_month            (const gint month,
                                                             const gint year);
    gint                i_cal_time_days_is_leap_year        (const gint year);
    ICalTimeSpan *      i_cal_time_span_new                 (ICalTimetype *dtstart,
                                                             ICalTimetype *dtend,
                                                             gint is_busy);
    gint                i_cal_time_span_overlaps            (ICalTimeSpan *s1,
                                                             ICalTimeSpan *s2);
    gint                i_cal_time_span_contains            (ICalTimeSpan *s,
                                                             ICalTimeSpan *container);

## Description

## Details

### i_cal_time_null_time ()

    ICalTimetype *      i_cal_time_null_time                (void);

Create a default time which is an epoch time

Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_null_date ()

    ICalTimetype *      i_cal_time_null_date                (void);

Create a null date, which indicates no time has been set

Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_current_time_with_zone ()

    ICalTimetype *      i_cal_time_current_time_with_zone   (ICalTimezone *zone);

Create a ICalTimetype according to the timezone and current time

`zone` : | The timezone used to create a ICalTimetype according to the current time. [in][transfer none]
Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_today ()

    ICalTimetype *      i_cal_time_today                    (void);

Create a ICalTimetype representing today

Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_from_timet ()

    ICalTimetype *      i_cal_time_from_timet               (const time_t v,
                                                             gint is_date);

Convert seconds past UNIX epoch to a timetype

`v` : | The seconds past since epoch time
`is_date` : | Whether it is a date type, 1 if yes, 0 if not.
Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_from_timet_with_zone ()

    ICalTimetype *      i_cal_time_from_timet_with_zone     (const time_t v,
                                                             gint is_date,
                                                             ICalTimezone *zone);

Convert seconds past UNIX epoch to a timetype, using timezones.

`v` : | The seconds past since epoch time
`is_date` : | Whether it is a date type, 1 if yes, 0 if not.
`zone` : | The timezone. [in][transfer none]
Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_from_string ()

    ICalTimetype *      i_cal_time_from_string              (const gchar *str);

create a time from an ISO format string

`str` : | The ISO format string
Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_from_day_of_year ()

    ICalTimetype *      i_cal_time_from_day_of_year         (const gint day,
                                                             const gint year);

Create a new time, given a day of year and a year.

`day` : | The day of a year
`year` : | The year
Returns : | The newly created ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_as_timet ()

    time_t              i_cal_time_as_timet                 (ICalTimetype *tt);

Return the time as seconds past the UNIX epoch

`tt` : | The ICalTimetype to be converted
Returns : | the time as seconds past the UNIX epoch

Since 1.0

### i_cal_time_as_timet_with_zone ()

    time_t              i_cal_time_as_timet_with_zone       (ICalTimetype *tt,
                                                             ICalTimezone *zone);

Return the time as seconds past the UNIX epoch, using timezones.

`tt` : | The ICalTimetype to be converted
`zone` : | The timezone. [in][transfer none]
Returns : | the time as seconds past the UNIX epoch

Since 1.0

### i_cal_time_as_ical_string_r ()

    gchar *             i_cal_time_as_ical_string_r         (ICalTimetype *tt);

Return a string represention of the time, in RFC2445 format.

`tt` : | The ICalTimetype to be converted
Returns : | The string representation. [transfer full]

Since 1.0

### i_cal_time_get_timezone ()

    const ICalTimezone * i_cal_time_get_timezone            (ICalTimetype *tt);

Return the timezone

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | The timezone information. [transfer full]

Since 1.0

### i_cal_time_set_timezone ()

    ICalTimetype *      i_cal_time_set_timezone             (ICalTimetype *tt,
                                                             ICalTimezone *zone);

Set the timezone

`tt` : | The ICalTimetype to be queried
`zone` : | The timezone. [transfer full]
Returns : | The ICalTimetype after being set. [transfer full]

Since 1.0

### i_cal_time_get_tzid ()

    const gchar *       i_cal_time_get_tzid                 (ICalTimetype *tt);

Return the tzid, or NULL for a floating time

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | The tzid of ICalTimetype, or NULL if floating type. [allow-none][transfer none]

Since 1.0

### i_cal_time_day_of_year ()

    gint                i_cal_time_day_of_year              (ICalTimetype *tt);

Return the day of the year of the given time

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | the day of the year of the given time

Since 1.0

### i_cal_time_day_of_week ()

    gint                i_cal_time_day_of_week              (ICalTimetype *tt);

Return the day of the week of the given time. Sunday is 1

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | the day of the week of the given time. Sunday is 1.

Since 1.0

### i_cal_time_start_doy_of_week ()

    gint                i_cal_time_start_doy_of_week        (ICalTimetype *tt);

Return the day of the year for the Sunday of the week that the given time is within.

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | the day of the year for the Sunday of the week that the given time is within.

Since 1.0

### i_cal_time_start_doy_week ()

    gint                i_cal_time_start_doy_week           (ICalTimetype *tt,
                                                             gint fdow);

Return the day of the year for the first day of the week that the given time is within.

`tt` : | The ICalTimetype to be queried. [in][transfer none]
`fdow` : | The first day of the week
Returns : | the day of the year for the Sunday of the week that the given time is within.

Since 1.0

### i_cal_time_week_number ()

    gint                i_cal_time_week_number              (ICalTimetype *tt);

Return the week number for the week the given time is within.

`tt` : | The ICalTimetype to be queried. [in][transfer none]
Returns : | the week number for the week the given time is within.

Since 1.0

### i_cal_time_is_null_time ()

    gint                i_cal_time_is_null_time             (ICalTimetype *tt);

Return true of the time is null.

`tt` : | The ICalTimetype to be checked. [in][transfer none]
Returns : | Whether `tt` is null_time. 1 if yes, 0 if not.

Since 1.0

### i_cal_time_is_valid_time ()

    gint                i_cal_time_is_valid_time            (ICalTimetype *tt);

Return true of the time is null.

`tt` : | The ICalTimetype to be checked. [in][transfer none]
Returns : | Whether `tt` is null_time. 1 if yes, 0 if not.

Since 1.0

### i_cal_time_is_date ()

    gint                i_cal_time_is_date                  (ICalTimetype *tt);

Returns true if time is of DATE type, false if DATE-TIME.

`tt` : | The ICalTimetype to be checked. [in][transfer none]
Returns : | true if time is of DATE type, false if DATE-TIME.

Since 1.0

### i_cal_time_is_utc ()

    gint                i_cal_time_is_utc                   (ICalTimetype *tt);

Returns true if time is relative to UTC zone.

`tt` : | The ICalTimetype to be checked. [in][transfer none]
Returns : | true if time is relative to UTC zone.

Since 1.0

### i_cal_time_compare ()

    gint                i_cal_time_compare                  (ICalTimetype *a,
                                                             ICalTimetype *b);

Return -1, 0, or 1 to indicate that a less than b, a==b or a larger than b.

`a` : | The ICalTimetype to be compared. [in][transfer none]
`b` : | The ICalTimetype to be compared. [in][transfer none]
Returns : | -1, 0, or 1 to indicate that a less than b, a==b or a larger than b.

Since 1.0

### i_cal_time_compare_date_only ()

    gint                i_cal_time_compare_date_only        (ICalTimetype *a,
                                                             ICalTimetype *b);

like icaltime_compare, but only use the date parts.

`a` : | The ICalTimetype to be compared. [in][transfer none]
`b` : | The ICalTimetype to be compared. [in][transfer none]
Returns : | -1, 0, or 1 to indicate that a less than b, a==b or a larger than b.

Since 1.0

### i_cal_time_compare_date_only_tz ()

    gint                i_cal_time_compare_date_only_tz     (ICalTimetype *a,
                                                             ICalTimetype *b,
                                                             ICalTimezone *zone);

like icaltime_compare_tz, but only use the date parts.

`a` : | The ICalTimetype to be compared. [in][transfer none]
`b` : | The ICalTimetype to be compared. [in][transfer none]
`zone` : | The target timezone. [transfer full]
Returns : | -1, 0, or 1 to indicate that a less than b, a==b or a larger than b.

Since 1.0

### i_cal_time_adjust ()

    void                i_cal_time_adjust                   (ICalTimetype *tt,
                                                             const gint days,
                                                             const gint hours,
                                                             const gint minutes,
                                                             const gint seconds);

like icaltime_compare_tz, but only use the date parts.

`tt` : | The ICalTimetype to be set
`days` : | difference of days adjusted
`hours` : | difference of hours adjusted
`minutes` : | difference of minutes adjusted
`seconds` : | difference of seconds adjusted

Since 1.0

### i_cal_time_normalize ()

    ICalTimetype *      i_cal_time_normalize                (ICalTimetype *t);

Normalize the icaltime, so that all fields are within the normal range.

`t` : | The ICalTimetype to be normalized. [in][transfer none]
Returns : | The ICalTimetype normalized. [transfer full]

Since 1.0

### i_cal_time_convert_to_zone ()

    ICalTimetype *      i_cal_time_convert_to_zone          (ICalTimetype *t,
                                                             ICalTimezone *zone);

Convert tt, of timezone tzid, into a utc time. Does nothing if the time is already UTC.

`t` : | The ICalTimetype to be normalized. [in][transfer none]
`zone` : | The target timezone. [transfer full]
Returns : | The converted ICalTimetype. [transfer full]

Since 1.0

### i_cal_time_days_in_month ()

    gint                i_cal_time_days_in_month            (const gint month,
                                                             const gint year);

Get the number of days in the target month in the target year.

`month` : | The target month
`year` : | The target year
Returns : | The number of days in the target month in the target year.

Since 1.0

### i_cal_time_days_is_leap_year ()

    gint                i_cal_time_days_is_leap_year        (const gint year);

Check whether a year is a leap year.

`year` : | The target year
Returns : | 1 if `year` is leap year, 0 if not.

Since 1.0

### i_cal_time_span_new ()

    ICalTimeSpan *      i_cal_time_span_new                 (ICalTimetype *dtstart,
                                                             ICalTimetype *dtend,
                                                             gint is_busy);

Create a new ICalTimeSpan.

`dtstart` : | The start of ICalTimeSpan
`dtend` : | The end of ICalTimeSpan
`is_busy` : | Whether this span is busy
Returns : | The newly create ICalTimeSpan. [transfer full]

Since 1.0

### i_cal_time_span_overlaps ()

    gint                i_cal_time_span_overlaps            (ICalTimeSpan *s1,
                                                             ICalTimeSpan *s2);

Check whether two spans overlap.

`s1` : | The first ICalTimeSpan
`s2` : | The second ICalTimeSpan
Returns : | Whether these two span are overlapped.

Since 1.0

### i_cal_time_span_contains ()

    gint                i_cal_time_span_contains            (ICalTimeSpan *s,
                                                             ICalTimeSpan *container);

Check whether one ICalTimeSpan is contained in another ICalTimeSpan.

`s` : | The test ICalTimeSpan
`container` : | The target container of ICalTimeSpan
Returns : | Whether one ICalTimeSpan is contained in another ICalTimeSpan.

Since 1.0