[evolution-data-server] evo-I#1042 - Show recurrence information with user-specified date format

[Milan Crha <mcrha src gnome org>]

commit 5f32066c942adcb9153438e3d88e67c85a463b9d
Author: Milan Crha <mcrha redhat com>
Date:   Thu Jul 30 12:26:10 2020 +0200

    evo-I#1042 - Show recurrence information with user-specified date format
    
    Related to https://gitlab.gnome.org/GNOME/evolution/-/issues/1042

 src/calendar/libecal/e-cal-recur.c | 59 ++++++++++++++++++++++++++++++++------
 src/calendar/libecal/e-cal-recur.h | 19 ++++++++++++
 2 files changed, 70 insertions(+), 8 deletions(-)
---
diff --git a/src/calendar/libecal/e-cal-recur.c b/src/calendar/libecal/e-cal-recur.c
index 98a5715e6..d8fcfbf3a 100644
--- a/src/calendar/libecal/e-cal-recur.c
+++ b/src/calendar/libecal/e-cal-recur.c
@@ -4956,10 +4956,11 @@ cal_comp_util_recurrence_count_by_xxx_and_free (GArray *array) /* gshort */
 }
 
 /**
- * e_cal_recur_describe_recurrence:
+ * e_cal_recur_describe_recurrence_ex:
  * @icalcomp: an #ICalComponent
  * @week_start_day: a day when the week starts
  * @flags: bit-or of #ECalRecurDescribeRecurrenceFlags
+ * @datetime_fmt_func: (nullable): formatting function for date/time value
  *
  * Describes some simple types of recurrences in a human-readable and localized way.
  * The @flags influence the output format and what to do when the @icalcomp
@@ -4968,6 +4969,9 @@ cal_comp_util_recurrence_count_by_xxx_and_free (GArray *array) /* gshort */
  * The @week_start_day is used for weekly recurrences, to start the list of selected
  * days at that day.
  *
+ * If @datetime_fmt_func is %NULL, the e_time_format_date_and_time() is used
+ * to format data/time value.
+ *
  * Free the returned string with g_free(), when no longer needed.
  *
  * Returns: (nullable) (transfer full): a newly allocated string, which
@@ -4975,12 +4979,13 @@ cal_comp_util_recurrence_count_by_xxx_and_free (GArray *array) /* gshort */
  *    doesn't recur or the recurrence is too complicated to describe, also
  *    according to given @flags.
  *
- * Since: 3.30
+ * Since: 3.38
  **/
 gchar *
-e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
-                                GDateWeekday week_start_day,
-                                guint32 flags)
+e_cal_recur_describe_recurrence_ex (ICalComponent *icalcomp,
+                                   GDateWeekday week_start_day,
+                                   guint32 flags,
+                                   ECalRecurFormatDateTimeFunc datetime_fmt_func)
 {
        gchar *prefix = NULL, *mid = NULL, *suffix = NULL, *result = NULL;
        ICalProperty *prop;
@@ -5771,7 +5776,6 @@ e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
                                        "for %d occurrences",
                                        i_cal_recurrence_get_count (rrule)), i_cal_recurrence_get_count 
(rrule));
                } else if (until && i_cal_time_get_year (until)) {
-                       struct tm tm;
                        gchar dt_str[256];
 
                        dt_str[0] = 0;
@@ -5789,9 +5793,15 @@ e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
                                i_cal_time_set_is_date (until, TRUE);
                        }
 
-                       tm = e_cal_util_icaltime_to_tm (until);
+                       if (datetime_fmt_func) {
+                               datetime_fmt_func (until, dt_str, 255);
+                       } else {
+                               struct tm tm;
 
-                       e_time_format_date_and_time (&tm, FALSE, FALSE, FALSE, dt_str, 255);
+                               tm = e_cal_util_icaltime_to_tm (until);
+
+                               e_time_format_date_and_time (&tm, FALSE, FALSE, FALSE, dt_str, 255);
+                       }
 
                        if (*dt_str) {
                                /* Translators: This is one of the last possible parts of a recurrence 
description.
@@ -5899,3 +5909,36 @@ e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
 
        return result;
 }
+
+/**
+ * e_cal_recur_describe_recurrence:
+ * @icalcomp: an #ICalComponent
+ * @week_start_day: a day when the week starts
+ * @flags: bit-or of #ECalRecurDescribeRecurrenceFlags
+ *
+ * Describes some simple types of recurrences in a human-readable and localized way.
+ * The @flags influence the output format and what to do when the @icalcomp
+ * contains more complicated recurrence, some which the function cannot describe.
+ *
+ * The @week_start_day is used for weekly recurrences, to start the list of selected
+ * days at that day.
+ *
+ * Uses e_time_format_date_and_time() to format the date/time value in the string.
+ * Call e_cal_recur_describe_recurrence_ex() with a custom formatting function.
+ *
+ * Free the returned string with g_free(), when no longer needed.
+ *
+ * Returns: (nullable) (transfer full): a newly allocated string, which
+ *    describes the recurrence of the @icalcomp, or #NULL, when the @icalcomp
+ *    doesn't recur or the recurrence is too complicated to describe, also
+ *    according to given @flags.
+ *
+ * Since: 3.30
+ **/
+gchar *
+e_cal_recur_describe_recurrence (ICalComponent *icalcomp,
+                                GDateWeekday week_start_day,
+                                guint32 flags)
+{
+       return e_cal_recur_describe_recurrence_ex (icalcomp, week_start_day, flags, NULL);
+}
diff --git a/src/calendar/libecal/e-cal-recur.h b/src/calendar/libecal/e-cal-recur.h
index f6d69370d..cafd170b7 100644
--- a/src/calendar/libecal/e-cal-recur.h
+++ b/src/calendar/libecal/e-cal-recur.h
@@ -114,6 +114,25 @@ gboolean   e_cal_recur_ensure_end_dates            (ECalComponent *comp,
 
 const gchar *  e_cal_recur_get_localized_nth           (gint nth);
 
+/**
+ * ECalRecurFormatDateTimeFunc:
+ * @itt: an #ICalTime to format to string
+ * @buffer: a buffer to fill with the result
+ * @buffer_size: the @buffer size, in bytes, not counting the NUL-terminator character
+ *
+ * Format the date/time value from @itt into @buffer, whose size cannot
+ * exceed @buffer_size letters.
+ *
+ * Since: 3.38
+ **/
+typedef void (* ECalRecurFormatDateTimeFunc)           (ICalTime *itt,
+                                                        gchar *buffer,
+                                                        gint buffer_size);
+
+gchar *                e_cal_recur_describe_recurrence_ex      (ICalComponent *icalcomp,
+                                                        GDateWeekday week_start_day,
+                                                        guint32 flags,
+                                                        ECalRecurFormatDateTimeFunc datetime_fmt_func);
 gchar *                e_cal_recur_describe_recurrence         (ICalComponent *icalcomp,
                                                         GDateWeekday week_start_day,
                                                         guint32 flags); /* bit-or of 
ECalRecurDescribeRecurrenceFlags */