ICalTime: libical-glib Reference Manual

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

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

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

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

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

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

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

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

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

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

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

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

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

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.