ICalTime: libical-glib Reference Manual

## ICalTime ICalTime |

## Functions

ICalTime * | i_cal_time_new ()
ICalTime * | i_cal_time_clone ()
ICalTime * | i_cal_time_new_null_time ()
ICalTime * | i_cal_time_new_null_date ()
ICalTime * | i_cal_time_new_current_with_zone ()
ICalTime * | i_cal_time_new_today ()
ICalTime * | i_cal_time_new_from_timet_with_zone ()
ICalTime * | i_cal_time_new_from_string ()
ICalTime * | i_cal_time_new_from_day_of_year ()
time_t | i_cal_time_as_timet ()
time_t | i_cal_time_as_timet_with_zone ()
gchar * | i_cal_time_as_ical_string ()
ICalTimezone * | i_cal_time_get_timezone ()
void | i_cal_time_set_timezone ()
const gchar * | i_cal_time_get_tzid ()
gint | i_cal_time_day_of_year ()
gint | i_cal_time_day_of_week ()
gint | i_cal_time_start_doy_week ()
gint | i_cal_time_week_number ()
gboolean | i_cal_time_is_null_time ()
gboolean | i_cal_time_is_valid_time ()
gboolean | i_cal_time_is_date ()
gboolean | i_cal_time_is_utc ()
gint | i_cal_time_compare ()
gint | i_cal_time_compare_date_only ()
gint | i_cal_time_compare_date_only_tz ()
void | i_cal_time_adjust ()
ICalTime * | i_cal_time_normalize ()
void | i_cal_time_normalize_inplace ()
ICalTime * | i_cal_time_convert_to_zone ()
void | i_cal_time_convert_to_zone_inplace ()
gint | i_cal_time_days_in_month ()
gboolean | i_cal_time_days_is_leap_year ()
gint | i_cal_time_days_in_year ()
ICalTimeSpan * | i_cal_time_span_new ()
gint | i_cal_time_span_overlaps ()
gint | i_cal_time_span_contains ()
ICalTime * | i_cal_time_add ()
ICalDuration * | i_cal_time_subtract ()
gint | i_cal_time_get_year ()
void | i_cal_time_set_year ()
gint | i_cal_time_get_month ()
void | i_cal_time_set_month ()
gint | i_cal_time_get_day ()
void | i_cal_time_set_day ()
gint | i_cal_time_get_hour ()
void | i_cal_time_set_hour ()
gint | i_cal_time_get_minute ()
void | i_cal_time_set_minute ()
gint | i_cal_time_get_second ()
void | i_cal_time_set_second ()
void | i_cal_time_set_is_date ()
gboolean | i_cal_time_is_daylight ()
void | i_cal_time_set_is_daylight ()
void | i_cal_time_get_date ()
void | i_cal_time_set_date ()
void | i_cal_time_get_time ()
void | i_cal_time_set_time ()

## Types and Values

| ICalTime
struct | ICalTimeClass

## Object Hierarchy

        GObject
        ╰── ICalObject
            ╰── ICalTime

## Description

## Functions

### i_cal_time_new ()

    ICalTime *
    i_cal_time_new (void);

Creates a new ICalTime.

#### Returns

The newly created ICalTime. It is a null time.

[transfer full]

Since: 1.0

### i_cal_time_clone ()

    ICalTime *
    i_cal_time_clone (const ICalTime *timetype);

Creates a new ICalTime, copy of `timetype` .

#### Parameters

timetype | The ICalTime to clone |

#### Returns

The newly created ICalTime, copy of `timetype` .

[transfer full]

Since: 1.0

### i_cal_time_new_null_time ()

    ICalTime *
    i_cal_time_new_null_time (void);

Creates a default time which is an epoch time.

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_null_date ()

    ICalTime *
    i_cal_time_new_null_date (void);

Creates a null date, which indicates no time has been set.

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_current_with_zone ()

    ICalTime *
    i_cal_time_new_current_with_zone (ICalTimezone *zone);

Creates a ICalTime according to the timezone and current time.

#### Parameters

zone | The timezone used to create a ICalTime according to the current time. | [nullable]

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_today ()

    ICalTime *
    i_cal_time_new_today (void);

Creates a ICalTime representing today.

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_from_timet_with_zone ()

    ICalTime *
    i_cal_time_new_from_timet_with_zone (const time_t v,
                                         gint is_date,
                                         ICalTimezone *zone);

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

#### Parameters

v | The seconds past since epoch time |
is_date | Whether it is a date type, 1 if yes, 0 if not |
zone | The timezone, or `NULL`. | [nullable]

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_from_string ()

    ICalTime *
    i_cal_time_new_from_string (const gchar *str);

Creates a time from an ISO format string.

#### Parameters

str | The ISO format string |

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_new_from_day_of_year ()

    ICalTime *
    i_cal_time_new_from_day_of_year (const gint day,
                                     const gint year);

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

#### Parameters

day | The day of a year |
year | The year |

#### Returns

The newly created ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_as_timet ()

    time_t
    i_cal_time_as_timet (const ICalTime *tt);

Returns the time as seconds past the UNIX epoch.

#### Parameters

tt | The ICalTime 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 (const ICalTime *tt,
                                   const ICalTimezone *zone);

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

#### Parameters

tt | The ICalTime to be converted |
zone | The timezone. | [nullable]

#### Returns

The time as seconds past the UNIX epoch

Since: 1.0

### i_cal_time_as_ical_string ()

    gchar *
    i_cal_time_as_ical_string (const ICalTime *tt);

Returns a string representation of the time, in RFC2445 format.

#### Parameters

tt | The ICalTime to be converted |

#### Returns

The string representation.

[transfer full]

Since: 1.0

### i_cal_time_get_timezone ()

    ICalTimezone *
    i_cal_time_get_timezone (const ICalTime *tt);

Returns the timezone, the ICalTimezone object is cached and can be either unreferenced once the last instance is used or can be kept until `i_cal_object_free_global_objects()` is called (usually at the very end of the program).

#### Parameters

tt | The ICalTime to be queried. | [in][transfer none]

#### Returns

The timezone information.

[transfer none]

Since: 1.0

### i_cal_time_set_timezone ()

    void
    i_cal_time_set_timezone (ICalTime *tt,
                             const ICalTimezone *zone);

Sets the timezone of the `tt` .

#### Parameters

tt | The ICalTime |
zone | The timezone. | [nullable]

Since: 1.0

### i_cal_time_get_tzid ()

    const gchar *
    i_cal_time_get_tzid (const ICalTime *tt);

Returns the tzid, or NULL for a floating time.

#### Parameters

tt | The ICalTime to be queried. | [in][transfer none]

#### Returns

The tzid of ICalTime, or NULL if floating type.

[nullable][transfer none]

Since: 1.0

### i_cal_time_day_of_year ()

    gint
    i_cal_time_day_of_year (const ICalTime *tt);

Returns the day of the year of the given time.

#### Parameters

tt | The ICalTime 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 (const ICalTime *tt);

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

#### Parameters

tt | The ICalTime 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_week ()

    gint
    i_cal_time_start_doy_week (const ICalTime *tt,
                               gint fdow);

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

#### Parameters

tt | The ICalTime 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 (const ICalTime *tt);

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

#### Parameters

tt | The ICalTime 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 ()

    gboolean
    i_cal_time_is_null_time (const ICalTime *tt);

Returns true if the time is null.

#### Parameters

tt | The ICalTime 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 ()

    gboolean
    i_cal_time_is_valid_time (const ICalTime *tt);

Returns true if the time is null.

#### Parameters

tt | The ICalTime 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 ()

    gboolean
    i_cal_time_is_date (const ICalTime *tt);

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

#### Parameters

tt | The ICalTime 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 ()

    gboolean
    i_cal_time_is_utc (const ICalTime *tt);

Returns true if time is relative to UTC zone.

#### Parameters

tt | The ICalTime 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 (const ICalTime *a,
                        const ICalTime *b);

i_cal_time_compare returns an integer indicating the result of the comparison, as follow:

#### Parameters

a | The ICalTime to be compared. | [in][transfer none]
b | The ICalTime 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 (const ICalTime *a,
                                  const ICalTime *b);

Like `i_cal_time_compare()`, but only use the date parts.

#### Parameters

a | The ICalTime to be compared. | [in][transfer none]
b | The ICalTime 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 (const ICalTime *a,
                                     const ICalTime *b,
                                     ICalTimezone *zone);

Like `i_cal_time_compare_tz()`, but only use the date parts; accepts timezone.

#### Parameters

a | The ICalTime to be compared. | [in][transfer none]
b | The ICalTime to be compared. | [in][transfer none]
zone | The target timezone. | [nullable]

#### 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 (ICalTime *tt,
                       const gint days,
                       const gint hours,
                       const gint minutes,
                       const gint seconds);

Adds or subtracts a number of days, hours, minutes and seconds from `tt` .

#### Parameters

tt | The ICalTime 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 ()

    ICalTime *
    i_cal_time_normalize (const ICalTime *t);

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

#### Parameters

t | The ICalTime to be normalized. | [in][transfer none]

#### Returns

The ICalTime normalized.

[transfer full]

Since: 1.0

### i_cal_time_normalize_inplace ()

    void
    i_cal_time_normalize_inplace (ICalTime *tt);

Normalizes the `tt` , so that all fields are within the normal range.

#### Parameters

tt | The ICalTime to be normalized |

Since: 3.0.5

### i_cal_time_convert_to_zone ()

    ICalTime *
    i_cal_time_convert_to_zone (const ICalTime *tt,
                                ICalTimezone *zone);

Converts `tt` to `zone` and return new ICalTime object.

#### Parameters

tt | The ICalTime to be converted. | [in][transfer none]
zone | The target timezone. | [nullable]

#### Returns

The converted ICalTime.

[transfer full]

Since: 1.0

### i_cal_time_convert_to_zone_inplace ()

    void
    i_cal_time_convert_to_zone_inplace (ICalTime *tt,
                                        ICalTimezone *zone);

Converts `tt` to `zone` and store the result into `tt` .

#### Parameters

tt | The ICalTime to be converted |
zone | The target timezone. | [nullable]

Since: 3.0.5

### i_cal_time_days_in_month ()

    gint
    i_cal_time_days_in_month (gint month,
                              gint year);

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

#### Parameters

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

    gboolean
    i_cal_time_days_is_leap_year (gint year);

Checks whether a year is a leap year.

#### Parameters

year | The target year |

#### Returns

Whether the `year` is a leap year

Since: 1.0

### i_cal_time_days_in_year ()

    gint
    i_cal_time_days_in_year (gint year);

Returns the number of days in this year.

#### Parameters

year | The target year |

#### Returns

Days in this year.

Since: 2.0

### i_cal_time_span_new ()

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

Creates a new ICalTimeSpan.

#### Parameters

dtstart | The start of ICalTimeSpan |
dtend | The end of ICalTimeSpan |
is_busy | Whether this span is busy |

#### Returns

The newly created ICalTimeSpan.

[transfer full]

Since: 1.0

### i_cal_time_span_overlaps ()

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

Checks whether two spans overlap.

#### Parameters

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);

Checks whether one ICalTimeSpan is contained in another ICalTimeSpan.

#### Parameters

s | The test ICalTimeSpan |
container | The target container of ICalTimeSpan |

#### Returns

Whether one ICalTimeSpan is contained in another ICalTimeSpan.

Since: 1.0

### i_cal_time_add ()

    ICalTime *
    i_cal_time_add (ICalTime *t,
                    ICalDuration *d);

Adds a time duration on the time.

#### Parameters

t | A ICalTime to be operated on |
d | A ICalDuration as the difference |

#### Returns

The ICalTime results. The native object is the same. But since it is a bare object, so it won't cause segmentation.

[transfer full]

Since: 2.0

### i_cal_time_subtract ()

    ICalDuration *
    i_cal_time_subtract (ICalTime *t1,
                         ICalTime *t2);

Gets the duration between two time.

#### Parameters

t1 | The subtracted ICalTime |
t2 | The subtracting ICalTime |

#### Returns

The ICalDuration between two ICalTime.

[transfer full]

Since: 2.0

### i_cal_time_get_year ()

    gint
    i_cal_time_get_year (const ICalTime *timetype);

Gets the year of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The year.

Since: 1.0

### i_cal_time_set_year ()

    void
    i_cal_time_set_year (ICalTime *timetype,
                         gint year);

Sets the year of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
year | The year |

Since: 1.0

### i_cal_time_get_month ()

    gint
    i_cal_time_get_month (const ICalTime *timetype);

Gets the month of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The month.

Since: 1.0

### i_cal_time_set_month ()

    void
    i_cal_time_set_month (ICalTime *timetype,
                          gint month);

Sets the month of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
month | The month |

Since: 1.0

### i_cal_time_get_day ()

    gint
    i_cal_time_get_day (const ICalTime *timetype);

Gets the day of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The day.

Since: 1.0

### i_cal_time_set_day ()

    void
    i_cal_time_set_day (ICalTime *timetype,
                        gint day);

Sets the day of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
day | The day |

Since: 1.0

### i_cal_time_get_hour ()

    gint
    i_cal_time_get_hour (const ICalTime *timetype);

Gets the hour of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The hour.

Since: 1.0

### i_cal_time_set_hour ()

    void
    i_cal_time_set_hour (ICalTime *timetype,
                         gint hour);

Sets the hour of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
hour | The hour |

Since: 1.0

### i_cal_time_get_minute ()

    gint
    i_cal_time_get_minute (const ICalTime *timetype);

Gets the minute of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The minute.

Since: 1.0

### i_cal_time_set_minute ()

    void
    i_cal_time_set_minute (ICalTime *timetype,
                           gint minute);

Sets the minute of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
minute | The minute |

Since: 1.0

### i_cal_time_get_second ()

    gint
    i_cal_time_get_second (const ICalTime *timetype);

Gets the second of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The second.

Since: 1.0

### i_cal_time_set_second ()

    void
    i_cal_time_set_second (ICalTime *timetype,
                           gint second);

Sets the second of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
second | The second |

Since: 1.0

### i_cal_time_set_is_date ()

    void
    i_cal_time_set_is_date (ICalTime *timetype,
                            gboolean is_date);

Sets the is_date of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
is_date | The is_date |

Since: 1.0

### i_cal_time_is_daylight ()

    gboolean
    i_cal_time_is_daylight (const ICalTime *timetype);

Gets the is_daylight of ICalTime.

#### Parameters

timetype | The ICalTime to be queried |

#### Returns

The is_daylight.

Since: 1.0

### i_cal_time_set_is_daylight ()

    void
    i_cal_time_set_is_daylight (ICalTime *timetype,
                                gboolean is_daylight);

Sets the is_daylight of ICalTime.

#### Parameters

timetype | The ICalTime to be set |
is_daylight | The is_daylight |

Since: 1.0

### i_cal_time_get_date ()

    void
    i_cal_time_get_date (const ICalTime *timetype,
                         gint *year,
                         gint *month,
                         gint *day);

Gets the year/month/date parts of the `timetype` in one call.

#### Parameters

timetype | The ICalTime to be queried |
year | Out parameter for the 'year' part of the date. | [out caller-allocates][optional]
month | Out parameter for the 'month' part of the date. | [out caller-allocates][optional]
day | Out parameter for the 'day' part of the date. | [out caller-allocates][optional]

Since: 1.0

### i_cal_time_set_date ()

    void
    i_cal_time_set_date (ICalTime *timetype,
                         gint year,
                         gint month,
                         gint day);

Sets the year/month/date parts of the `timetype` in one call. This doesn't verify validity of the given date.

#### Parameters

timetype | The ICalTime to be set to |
year | The 'year' part of the date |
month | The 'month' part of the date |
day | The 'day' part of the date |

Since: 1.0

### i_cal_time_get_time ()

    void
    i_cal_time_get_time (const ICalTime *timetype,
                         gint *hour,
                         gint *minute,
                         gint *second);

Gets the hour/minute/second parts of the `timetype` in one call.

#### Parameters

timetype | The ICalTime to be queried |
hour | Out parameter for the 'hour' part of the time. | [out caller-allocates][optional]
minute | Out parameter for the 'minute' part of the time. | [out caller-allocates][optional]
second | Out parameter for the 'second' part of the time. | [out caller-allocates][optional]

Since: 1.0

### i_cal_time_set_time ()

    void
    i_cal_time_set_time (ICalTime *timetype,
                         gint hour,
                         gint minute,
                         gint second);

Sets the hour/minute/second parts of the `timetype` in one call. This doesn't verify validity of the given time.

#### Parameters

timetype | The ICalTime to be set to |
hour | The 'hour' part of the time |
minute | The 'minute' part of the time |
second | The 'second' part of the time |

Since: 1.0

## Types and Values

### ICalTime

    typedef struct _ICalTime ICalTime;

This is the ICalTime instance.

### struct ICalTimeClass

    struct ICalTimeClass {
    };

This is the ICalTime class.