clock: Add signed time utilities

Add utility to print signed value of time. This is useful to
trace running time values in gint64 or GstClockTimeDiff values.
Additionally, define GST_CLOCK_STIME_NONE to indicate an invalid
signed time value and validation macro. New macros are:

GST_CLOCK_STIME_NONE
GST_CLOCK_STIME_IS_VALID
GST_STIME_FORMAT
GST_STIME_ARGS

https://bugzilla.gnome.org/show_bug.cgi?id=740575

diff --git a/gst/gstclock.h b/gst/gstclock.h
index 9369755..165470e 100644 (file)
--- a/gst/gstclock.h
+++ b/gst/gstclock.h
@@ -79,6 +79,25 @@ typedef gpointer GstClockID;
  */
 #define GST_CLOCK_TIME_IS_VALID(time)   (((GstClockTime)(time)) != GST_CLOCK_TIME_NONE)
 
+/**
+ * GST_CLOCK_STIME_NONE:
+ *
+ * Constant to define an undefined clock time.
+ *
+ * Value: -9223372036854775808
+ * Type: #GstClockDiff
+ */
+#define GST_CLOCK_STIME_NONE             G_MININT64
+/**
+ * GST_CLOCK_STIME_IS_VALID:
+ * @time: signed clock time to validate
+ *
+ * Tests if a given #GstClockTimeDiff of #gint64 represents a valid defined time.
+ *
+ * Since 1.6
+ */
+#define GST_CLOCK_STIME_IS_VALID(time)   (((GstClockTimeDiff)(time)) != GST_CLOCK_STIME_NONE)
+
 /* FIXME: still need to explicitly force types on the defines below */
 /**
  * GST_SECOND:
@@ -238,6 +257,39 @@ G_STMT_START {                                                    \
         (guint) ((((GstClockTime)(t)) / GST_SECOND) % 60) : 99, \
         GST_CLOCK_TIME_IS_VALID (t) ? \
         (guint) (((GstClockTime)(t)) % GST_SECOND) : 999999999
+/**
+ * GST_STIME_FORMAT:
+ *
+ * A string that can be used in printf-like format strings to display a signed
+ * #GstClockTimeDiff or #gint64 value in h:m:s format.  Use GST_TIME_ARGS() to
+ * construct the matching arguments.
+ *
+ * Example:
+ * |[
+ * printf("%" GST_STIME_FORMAT "\n", GST_STIME_ARGS(ts));
+ * ]|
+ *
+ * Since 1.6
+ */
+#define GST_STIME_FORMAT "d:%02u:%02u.%09u"
+/**
+ * GST_STIME_ARGS:
+ * @t: a #GstClockTimeDiff or #gint64
+ *
+ * Format @t for the #GST_STIME_FORMAT format string. Note: @t will be
+ * evaluated more than once.
+ *
+ * Since 1.6
+ */
+#define GST_STIME_ARGS(t) \
+        GST_CLOCK_STIME_IS_VALID (t) ? \
+        (gint) ((GstClockTimeDiff)(t) / (GST_SECOND * 60 * 60)) : -99, \
+        GST_CLOCK_STIME_IS_VALID (t) ? \
+        (guint) ((((GstClockTime)ABS(t)) / (GST_SECOND * 60)) % 60) : 99, \
+        GST_CLOCK_STIME_IS_VALID (t) ? \
+        (guint) ((((GstClockTime)ABS(t)) / GST_SECOND) % 60) : 99, \
+        GST_CLOCK_STIME_IS_VALID (t) ? \
+        (guint) (((GstClockTime)ABS(t)) % GST_SECOND) : 999999999
 
 typedef struct _GstClockEntry   GstClockEntry;
 typedef struct _GstClock        GstClock;