gstcaps: New gst_caps_steal_structure() method

This allows removing structures from caps without them being freed. Helpful when
plugins need to move around structures without having to do an expensive structure
copy.

API:gst_caps_steal_structure

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

docs/gst/gstreamer-sections.txt

@@ -288,6 +288,7 @@ gst_caps_append
 gst_caps_merge
 gst_caps_append_structure
 gst_caps_remove_structure
+gst_caps_steal_structure
 gst_caps_merge_structure
 gst_caps_get_size
 gst_caps_get_structure

gst/gstcaps.c

@@ -529,6 +529,28 @@ gst_caps_remove_and_get_structure (GstCaps * caps, guint idx)
   return s;
 }
 
+/**
+ * gst_caps_steal_structure:
+ * @caps: the #GstCaps to retrieve from
+ * @idx: Index of the structure to retrieve
+ *
+ * Retrieves the stucture with the given index from the list of structures
+ * contained in @caps. The caller becomes the owner of the returned structure.
+ *
+ * Returns: a pointer to the #GstStructure corresponding to @index.
+ */
+GstStructure *
+gst_caps_steal_structure (GstCaps * caps, guint idx)
+{
+  g_return_val_if_fail (caps != NULL, NULL);
+  g_return_val_if_fail (IS_WRITABLE (caps), NULL);
+
+  if (G_UNLIKELY (idx >= caps->structs->len))
+    return NULL;
+
+  return gst_caps_remove_and_get_structure (caps, idx);
+}
+
 static gboolean
 gst_structure_is_equal_foreach (GQuark field_id, const GValue * val2,
     gpointer data)

gst/gstcaps.h

@@ -205,6 +205,8 @@ void              gst_caps_merge_structure         (GstCaps       *caps,
 guint             gst_caps_get_size                (const GstCaps *caps);
 GstStructure *    gst_caps_get_structure           (const GstCaps *caps,
                                                     guint          index);
+GstStructure *    gst_caps_steal_structure         (GstCaps *caps,
+                                                    guint          index);
 GstCaps *         gst_caps_copy_nth                (const GstCaps *caps, guint nth);
 void              gst_caps_truncate                (GstCaps       *caps);
 void              gst_caps_set_value               (GstCaps       *caps,

win32/common/libgstreamer.def

@@ -171,6 +171,7 @@ EXPORTS
 	gst_caps_new_full_valist
 	gst_caps_new_simple
 	gst_caps_normalize
+	gst_caps_steal_structure
 	gst_caps_ref
 	gst_caps_remove_structure
 	gst_caps_replace