[glib: 7/26] glib: Deprecate API using GTimeVal in gtimer.h

[Philip Withnall <pwithnall src gnome org>]

commit b8540db1bf1a3e71248026393d895c63e8f7222e
Author: Philip Withnall <withnall endlessm com>
Date:   Tue Jun 18 12:35:09 2019 +0100

    glib: Deprecate API using GTimeVal in gtimer.h
    
    GTimeVal is not year-2038-safe.
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    
    Helps: #1438

 glib/gtimer.c | 29 ++++++++++++++++++++++++++++-
 glib/gtimer.h |  8 +++++---
 2 files changed, 33 insertions(+), 4 deletions(-)
---
diff --git a/glib/gtimer.c b/glib/gtimer.c
index 6b012549b..7d21ba822 100644
--- a/glib/gtimer.c
+++ b/glib/gtimer.c
@@ -286,7 +286,11 @@ g_usleep (gulong microseconds)
  *
  * Adds the given number of microseconds to @time_. @microseconds can
  * also be negative to decrease the value of @time_.
+ *
+ * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use `guint64` for
+ *    representing microseconds since the epoch, or use #GDateTime.
  **/
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 void 
 g_time_val_add (GTimeVal *time_, glong microseconds)
 {
@@ -314,6 +318,7 @@ g_time_val_add (GTimeVal *time_, glong microseconds)
        }      
     }
 }
+G_GNUC_END_IGNORE_DEPRECATIONS
 
 /* converts a broken down date representation, relative to UTC,
  * to a timestamp; it uses timegm() if it's available.
@@ -364,10 +369,21 @@ mktime_utc (struct tm *tm)
  *
  * Any leading or trailing space in @iso_date is ignored.
  *
+ * This function was deprecated, along with #GTimeVal itself, in GLib 2.62.
+ * Equivalent functionality is available using code like:
+ * |[
+ * GDateTime *dt = g_date_time_new_from_iso8601 (iso8601_string, NULL);
+ * gint64 time_val = g_date_time_to_unix (dt);
+ * g_date_time_unref (dt);
+ * ]|
+ *
  * Returns: %TRUE if the conversion was successful.
  *
  * Since: 2.12
+ * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use
+ *    g_date_time_new_from_iso8601() instead.
  */
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 gboolean
 g_time_val_from_iso8601 (const gchar *iso_date,
                         GTimeVal    *time_)
@@ -528,6 +544,7 @@ g_time_val_from_iso8601 (const gchar *iso_date,
 
   return *iso_date == '\0';
 }
+G_GNUC_END_IGNORE_DEPRECATIONS
 
 /**
  * g_time_val_to_iso8601:
@@ -557,7 +574,13 @@ g_time_val_from_iso8601 (const gchar *iso_date,
  * If @time_ represents a date which is too large to fit into a `struct tm`,
  * %NULL will be returned. This is platform dependent. Note also that since
  * `GTimeVal` stores the number of seconds as a `glong`, on 32-bit systems it
- * is subject to the year 2038 problem.
+ * is subject to the year 2038 problem. Accordingly, since GLib 2.62, this
+ * function has been deprecated. Equivalent functionality is available using:
+ * |[
+ * GDateTime *dt = g_date_time_new_from_unix_utc (time_val);
+ * iso8601_string = g_date_time_format_iso8601 (dt);
+ * g_date_time_unref (dt);
+ * ]|
  *
  * The return value of g_time_val_to_iso8601() has been nullable since GLib
  * 2.54; before then, GLib would crash under the same conditions.
@@ -566,7 +589,10 @@ g_time_val_from_iso8601 (const gchar *iso_date,
  *    or %NULL if @time_ was too large
  *
  * Since: 2.12
+ * Deprecated: 2.62: #GTimeVal is not year-2038-safe. Use
+ *    g_date_time_format_iso8601(dt) instead.
  */
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 gchar *
 g_time_val_to_iso8601 (GTimeVal *time_)
 {
@@ -624,3 +650,4 @@ g_time_val_to_iso8601 (GTimeVal *time_)
   
   return retval;
 }
+G_GNUC_END_IGNORE_DEPRECATIONS
diff --git a/glib/gtimer.h b/glib/gtimer.h
index 25679f331..28794d167 100644
--- a/glib/gtimer.h
+++ b/glib/gtimer.h
@@ -62,14 +62,16 @@ gboolean g_timer_is_active       (GTimer      *timer);
 GLIB_AVAILABLE_IN_ALL
 void     g_usleep                (gulong       microseconds);
 
-GLIB_AVAILABLE_IN_ALL
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
+GLIB_DEPRECATED_IN_2_62
 void     g_time_val_add          (GTimeVal    *time_, 
                                   glong        microseconds);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_new_from_iso8601)
 gboolean g_time_val_from_iso8601 (const gchar *iso_date,
                                  GTimeVal    *time_);
-GLIB_AVAILABLE_IN_ALL
+GLIB_DEPRECATED_IN_2_62_FOR(g_date_time_format)
 gchar*   g_time_val_to_iso8601   (GTimeVal    *time_) G_GNUC_MALLOC;
+G_GNUC_END_IGNORE_DEPRECATIONS
 
 G_END_DECLS