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);
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);
GList*              jana_utils_event_get_instances      (JanaEvent *event,
                                                         JanaTime *range_start,
                                                         JanaTime *range_end,
                                                         glong offset);
void                jana_utils_instance_list_free       (GList *instances);
gchar*              jana_utils_get_local_tzname         ();

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_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_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_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.