![]() |
![]() |
![]() |
libjana Reference Manual | |
---|---|---|---|---|
Top | Description |
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
);
jana-utils contains a collection of utility functions related to, and using the interfaces specified in libjana.
gboolean jana_utils_time_is_leap_year (guint16 year
);
Determines if year
is a leap year.
guint8 jana_utils_time_days_in_month (guint16 year
,guint8 month
);
Determines the amount of days in the given month and year.
|
A year |
|
A month |
Returns : |
The amount of days in the given month and year. |
GDateWeekday jana_utils_time_day_of_week (JanaTime *time
);
Determines the day of the week that time
occurs on.
|
A JanaTime |
Returns : |
The day of the week that time occurs on. |
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.
|
A JanaTime |
Returns : |
The day of the year that time is. |
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.
|
A JanaTime |
Returns : |
The day of the week start was on, before modification. |
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.
|
A JanaTime |
Returns : |
The day of the week end was on, before modification. |
guint jana_utils_time_week_of_year (JanaTime *time
,gboolean week_starts_monday
);
Retrieves what week of the year time
occurs within.
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()
.
|
JanaTime implementation |
Returns : |
A broken-down time structure |
gchar * jana_utils_strftime (JanaTime *time
,const gchar *format
);
Create a formatted string of time
, using strftime()
and format
.
gint jana_utils_time_compare (JanaTime *time1
,JanaTime *time2
,gboolean date_only
);
Compares time1
to time2
, taking into account the offset field.
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.
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.
|
A JanaTime |
|
A JanaTime |
|
Return location for difference in years, or NULL
|
|
Return location for difference in months, or NULL
|
|
Return location for difference in days, or NULL
|
|
Return location for difference in hours, or NULL
|
|
Return location for difference in minutes, or NULL
|
|
Return location for difference in seconds, or NULL
|
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.
|
A JanaTime |
|
Years to add to time
|
|
Months to add to time
|
|
Days to add to time
|
|
Hours to add to time
|
|
Minutes to add to time
|
|
Seconds to add to time
|
JanaTime * jana_utils_time_now (JanaTime *time
);
Retrieves the current time, with the timezone and offset set.
|
A JanaTime to overwrite |
Returns : |
time . |
gboolean jana_utils_duration_contains (JanaDuration *duration
,JanaTime *time
);
Determines whether time
occurs within duration
.
|
A JanaDuration |
|
A JanaTime |
Returns : |
TRUE if time occurs within duration , FALSE otherwise. |
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.
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
.
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.
|
A JanaEvent |
|
The start boundary for instances, or NULL for no boundary |
|
The end boundary for instances, or NULL for no boundary |
|
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() . |
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.
|
A JanaComponent |
|
The category to insert |
|
The position to insert at |
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.
|
A JanaComponent |
|
The category to remove |
Returns : |
TRUE if a category was removed, FALSE otherwise. |
gboolean jana_utils_component_has_category (JanaComponent *component
,const gchar *category
);
Checks if the specified component has a particular category set.
|
A JanaComponent |
|
The category to search for |
Returns : |
TRUE if that category exists, FALSE otherwise. |
void jana_utils_instance_list_free (GList *instances
);
Frees an event instance list. See jana_utils_event_get_instances()
.
|
An instance list returned by jana_utils_event_get_instances()
|
gchar * jana_utils_get_local_tzname ();
Retrieves the local timezone name using system functions.
Returns : |
A newly allocated string with the local tzname. |
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.
|
A JanaRecurrence |
|
The start of the recurrence |
Returns : |
A newly allocated string with the human-readable recurrence info |
gboolean jana_utils_recurrence_diff (JanaRecurrence *r1
,JanaRecurrence *r2
);
Determines whether two recurrence rules are different.
|
A JanaRecurrence |
|
The JanaRecurrence to compare to |
Returns : |
TRUE if r1 is different to r2 , FALSE otherwise. |
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.
|
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. |
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.
|
A latitude, in decimal degrees |
|
The day of the year |
Returns : |
Hours of daylight |