jana-utils

jana-utils — A set of utility functions

Functions

Description

jana-utils contains a collection of utility functions related to, and using the interfaces specified in libjana.

Functions

jana_utils_time_is_leap_year ()

gboolean
jana_utils_time_is_leap_year (guint16 year);

Determines if year is a leap year.

Parameters

year

A year

 

Returns

TRUE if year is a leap year, FALSE otherwise.


jana_utils_time_days_in_month ()

guint8
jana_utils_time_days_in_month (guint16 year,
                               guint8 month);

Determines the amount of days in the given month and year.

Parameters

year

A year

 

month

A month

 

Returns

The amount of days in the given month and year.


jana_utils_time_day_of_week ()

GDateWeekday
jana_utils_time_day_of_week (JanaTime *time);

Determines the day of the week that time occurs on.

Parameters

time

A JanaTime

 

Returns

The day of the week that time occurs on.


jana_utils_time_day_of_year ()

guint
jana_utils_time_day_of_year (JanaTime *time);

Determines what day of the year time is, where 1st January is the first day of the year.

Parameters

time

A JanaTime

 

Returns

The day of the year that time is.


jana_utils_time_set_start_of_week ()

GDateWeekday
jana_utils_time_set_start_of_week (JanaTime *start);

Moves start backwards to the start of the week (Monday), if it isn't already.

Parameters

start

A JanaTime

 

Returns

The day of the week start was on, before modification.


jana_utils_time_set_end_of_week ()

GDateWeekday
jana_utils_time_set_end_of_week (JanaTime *end);

Moves end forwards to the end of the week (Sunday), if it isn't already.

Parameters

end

A JanaTime

 

Returns

The day of the week end was on, before modification.


jana_utils_time_week_of_year ()

guint
jana_utils_time_week_of_year (JanaTime *time,
                              gboolean week_starts_monday);

Retrieves what week of the year time occurs within.

Parameters

time

A JanaTime

 

week_starts_monday

TRUE if the week begins on Monday, FALSE if it begins on Sunday

 

Returns

The week of the year time occurs within.


jana_utils_time_to_gdate ()

GDate *
jana_utils_time_to_gdate (JanaTime *time);

Converts a JanaTime to a GDate.

Parameters

time

A JanaTime

 

Returns

A newly allocated GDate, with fields set from time .


jana_utils_time_to_tm ()

struct tm
jana_utils_time_to_tm (JanaTime *time);

Converts time to a broken-down time structure, usable by libc time functions. tm_gmtoff and tm_zone components of this structure are not filled in, however, they can be completed using jana_time_get_offset() and jana_time_get_tzname().

Parameters

time

JanaTime implementation

 

Returns

A broken-down time structure


jana_utils_strftime ()

gchar *
jana_utils_strftime (JanaTime *time,
                     const gchar *format);

Create a formatted string of time , using strftime() and format .

Parameters

time

JanaTime implementation

 

format

Time formatting string

 

Returns

A newly allocated string, representing time using format , or NULL on failure.


jana_utils_time_compare ()

gint
jana_utils_time_compare (JanaTime *time1,
                         JanaTime *time2,
                         gboolean date_only);

Compares time1 to time2 , taking into account the offset field.

Parameters

time1

A JanaTime

 

time2

A JanaTime to compare with

 

date_only

Whether to only consider date fields

 

Returns

-1 if time1 occurs before time2 , 0 if time1 is equal to time2 , and 1 if time1 is after time2 .


jana_utils_time_copy ()

JanaTime *
jana_utils_time_copy (JanaTime *source,
                      JanaTime *dest);

Copies the contents of source to dest . This can be useful when you want to duplicate a time without creating a new JanaTime, or when you need to convert a time between different implementations of JanaTime. Fields are set in such an order as to not cause normalisation to alter the time.

Parameters

source

A JanaTime to copy from

 

dest

A JanaTime to copy to

 

Returns

dest .


jana_utils_time_diff ()

void
jana_utils_time_diff (JanaTime *t1,
                      JanaTime *t2,
                      gint *year,
                      gint *month,
                      gint *day,
                      gint *hours,
                      gint *minutes,
                      glong *seconds);

Gets the difference between two times. Times are compared so that if t2 is later than t1 , the difference is positive. If a parameter is ommitted, the result will be accumulated in the next nearest parameter. For example, if there were a years difference between t1 and t2 , but the year parameter was ommitted, the month parameter will accumulate 12 months. This function takes into account the relative time offsets of t1 and t2 , so no prior conversion is required.

Parameters

t1

A JanaTime

 

t2

A JanaTime

 

year

Return location for difference in years, or NULL

 

month

Return location for difference in months, or NULL

 

day

Return location for difference in days, or NULL

 

hours

Return location for difference in hours, or NULL

 

minutes

Return location for difference in minutes, or NULL

 

seconds

Return location for difference in seconds, or NULL

 

jana_utils_time_adjust ()

void
jana_utils_time_adjust (JanaTime *time,
                        gint year,
                        gint month,
                        gint day,
                        gint hours,
                        gint minutes,
                        gint seconds);

A convenience function to adjust a time by a specified amount on each field. The time will be adjusted in the order seconds, minutes, hours, days, months and years. It is important to take into account how a time may be normalised when adjusting. This function can be used in conjunction with jana_utils_time_diff() to adjust one time to be equal to another, while taking time offsets into account.

Parameters

time

A JanaTime

 

year

Years to add to time

 

month

Months to add to time

 

day

Days to add to time

 

hours

Hours to add to time

 

minutes

Minutes to add to time

 

seconds

Seconds to add to time

 

jana_utils_time_now ()

JanaTime *
jana_utils_time_now (JanaTime *time);

Retrieves the current time, with the timezone and offset set.

Parameters

time

A JanaTime to overwrite

 

Returns

time .


jana_utils_duration_contains ()

gboolean
jana_utils_duration_contains (JanaDuration *duration,
                              JanaTime *time);

Determines whether time occurs within duration .

Parameters

duration

A JanaDuration

 

time

A JanaTime

 

Returns

TRUE if time occurs within duration , FALSE otherwise.


jana_utils_event_copy ()

JanaEvent *
jana_utils_event_copy (JanaEvent *source,
                       JanaEvent *dest);

Copies the contents of source into dest . This function copies all fields of source over those of dest , taking into account whether alarms, recurrences and custom properties are supported.

Parameters

source

A JanaEvent to copy from

 

dest

A JanaEvent to copy to

 

Returns

dest .


jana_utils_note_copy ()

JanaNote *
jana_utils_note_copy (JanaNote *source,
                      JanaNote *dest);

Copies the contents of source into dest . This function copies all fields of source over those of dest .

Parameters

source

A JanaNote to copy from

 

dest

A JanaNote to copy to

 

Returns

dest .


jana_utils_event_get_instances ()

GList *
jana_utils_event_get_instances (JanaEvent *event,
                                JanaTime *range_start,
                                JanaTime *range_end,
                                glong offset);

Splits an event across each day it occurs, taking into account offset , and returns a list of JanaDuration's for each day it occurs. The first and last instances have their start and end adjusted correctly. If the event doesn't occur over more than one day, the list will contain just one duration whose start and end match the start and end of the event, adjusted by offset . If range_end is NULL and event has an indefinite recurrence, the recurrence will be ignored. This is to avoid infinite loops; it is discouraged to call this function without bounds.

Parameters

event

A JanaEvent

 

range_start

The start boundary for instances, or NULL for no boundary

 

range_end

The end boundary for instances, or NULL for no boundary

 

offset

The offset, in seconds, to offset the event by

 

Returns

A list of JanaDuration's for each day event occurs. This list should be freed with jana_utils_instance_list_free().


jana_utils_component_insert_category ()

void
jana_utils_component_insert_category (JanaComponent *component,
                                      const gchar *category,
                                      gint position);

Inserts a category in the category list of the given component, at the given position. If position is -1, the category will be placed at the end of the list.

Parameters

component

A JanaComponent

 

category

The category to insert

 

position

The position to insert at

 

jana_utils_component_remove_category ()

gboolean
jana_utils_component_remove_category (JanaComponent *component,
                                      const gchar *category);

Removes the first occurrence of the given category from the component's category list.

Parameters

component

A JanaComponent

 

category

The category to remove

 

Returns

TRUE if a category was removed, FALSE otherwise.


jana_utils_component_has_category ()

gboolean
jana_utils_component_has_category (JanaComponent *component,
                                   const gchar *category);

Checks if the specified component has a particular category set.

Parameters

component

A JanaComponent

 

category

The category to search for

 

Returns

TRUE if that category exists, FALSE otherwise.


jana_utils_instance_list_free ()

void
jana_utils_instance_list_free (GList *instances);

Frees an event instance list. See jana_utils_event_get_instances().

Parameters

instances

An instance list returned by jana_utils_event_get_instances()

 

jana_utils_get_local_tzname ()

gchar *
jana_utils_get_local_tzname ();

Retrieves the local timezone name using system functions.

Returns

A newly allocated string with the local tzname.


jana_utils_recurrence_to_string ()

gchar *
jana_utils_recurrence_to_string (JanaRecurrence *recur,
                                 JanaTime *start);

Creates a localised string that represents recur in a human-readable format. If recur is NULL, a string representing no recurrence will be returned. If start is NULL, monthly recurrences will not be fully described.

Parameters

recur

A JanaRecurrence

 

start

The start of the recurrence

 

Returns

A newly allocated string with the human-readable recurrence info


jana_utils_recurrence_diff ()

gboolean
jana_utils_recurrence_diff (JanaRecurrence *r1,
                            JanaRecurrence *r2);

Determines whether two recurrence rules are different.

Parameters

r1

A JanaRecurrence

 

r2

The JanaRecurrence to compare to

 

Returns

TRUE if r1 is different to r2 , FALSE otherwise.


jana_utils_ab_day ()

const gchar *
jana_utils_ab_day (guint day);

Retrieves the first UTF-8 character of the abbreviated, locale-correct day name, in a null-terminated string. The returned string must not be freed and will be overwritten by subsequent calls to this function.

Parameters

day

The day number, where 0 is Monday, 1 is Tuesday, etc.

 

Returns

A NULL-terminated string containing the first character of the abbreviated day name.


jana_utils_time_daylight_hours ()

gdouble
jana_utils_time_daylight_hours (gdouble latitude,
                                guint day_of_year);

Calculates the amount of hours of daylight one should expect at a particular latitude and time of year.

Parameters

latitude

A latitude, in decimal degrees

 

day_of_year

The day of the year

 

Returns

Hours of daylight

Types and Values