jana-utils

jana-utils — A set of utility functions

Synopsis

gboolean            jana_utils_time_is_leap_year        (guint16 year);
guint8              jana_utils_time_days_in_month       (guint16 year,
                                                         guint8 month);
GDateWeekday        jana_utils_time_day_of_week         (JanaTime *time);
guint               jana_utils_time_day_of_year         (JanaTime *time);
GDateWeekday        jana_utils_time_set_start_of_week   (JanaTime *start);
GDateWeekday        jana_utils_time_set_end_of_week     (JanaTime *end);
guint               jana_utils_time_week_of_year        (JanaTime *time,
                                                         gboolean week_starts_monday);
GDate *             jana_utils_time_to_gdate            (JanaTime *time);
struct tm           jana_utils_time_to_tm               (JanaTime *time);
gchar *             jana_utils_strftime                 (JanaTime *time,
                                                         const gchar *format);
gint                jana_utils_time_compare             (JanaTime *time1,
                                                         JanaTime *time2,
                                                         gboolean date_only);
JanaTime *          jana_utils_time_copy                (JanaTime *source,
                                                         JanaTime *dest);
void                jana_utils_time_diff                (JanaTime *t1,
                                                         JanaTime *t2,
                                                         gint *year,
                                                         gint *month,
                                                         gint *day,
                                                         gint *hours,
                                                         gint *minutes,
                                                         glong *seconds);
void                jana_utils_time_adjust              (JanaTime *time,
                                                         gint year,
                                                         gint month,
                                                         gint day,
                                                         gint hours,
                                                         gint minutes,
                                                         gint seconds);
JanaTime *          jana_utils_time_now                 (JanaTime *time);
gboolean            jana_utils_duration_contains        (JanaDuration *duration,
                                                         JanaTime *time);
JanaEvent *         jana_utils_event_copy               (JanaEvent *source,
                                                         JanaEvent *dest);
JanaNote *          jana_utils_note_copy                (JanaNote *source,
                                                         JanaNote *dest);
GList *             jana_utils_event_get_instances      (JanaEvent *event,
                                                         JanaTime *range_start,
                                                         JanaTime *range_end,
                                                         glong offset);
void                jana_utils_component_insert_category
                                                        (JanaComponent *component,
                                                         const gchar *category,
                                                         gint position);
gboolean            jana_utils_component_remove_category
                                                        (JanaComponent *component,
                                                         const gchar *category);
gboolean            jana_utils_component_has_category   (JanaComponent *component,
                                                         const gchar *category);
void                jana_utils_instance_list_free       (GList *instances);
gchar *             jana_utils_get_local_tzname         ();
gchar *             jana_utils_recurrence_to_string     (JanaRecurrence *recur,
                                                         JanaTime *start);
gboolean            jana_utils_recurrence_diff          (JanaRecurrence *r1,
                                                         JanaRecurrence *r2);
const gchar *       jana_utils_ab_day                   (guint day);
gdouble             jana_utils_time_daylight_hours      (gdouble latitude,
                                                         guint day_of_year);

Description

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

Details

jana_utils_time_is_leap_year ()

gboolean            jana_utils_time_is_leap_year        (guint16 year);

Determines if year is a leap year.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

latitude :

A latitude, in decimal degrees

day_of_year :

The day of the year

Returns :

Hours of daylight