Bug 471577 – GBoxed GType for PangoGlyphItem

2007-10-24  Behdad Esfahbod  <behdad@gnome.org>

        Bug 471577 – GBoxed GType for PangoGlyphItem

        * pango/pango-glyph-item.h:
        * pango/pango-glyph-item.c: 
        New public API: 

                PANGO_TYPE_GLYPH_ITEM
                pango_glyph_item_copy()
                pango_glyph_item_get_type()

        * pango/pango-layout.c: 
        New public API:
        
                pango_layout_iter_copy()

        * pango/fonts.c (pango_font_description_copy),
        (pango_font_description_copy_static),
        (pango_font_description_free), (pango_font_descriptions_free),
        (pango_font_metrics_ref), (pango_font_metrics_unref):
        * pango/glyphstring.c (pango_glyph_string_copy),
        (pango_glyph_string_free):
        * pango/pango-attributes.c (pango_attr_list_ref),
        (pango_attr_list_unref), (pango_attr_list_copy):
        * pango/pango-color.c (pango_color_copy), (pango_color_free):
        * pango/pango-item.c (pango_item_copy), (pango_item_free):
        * pango/pango-layout.c (pango_layout_line_ref),
        (pango_layout_line_unref), (pango_layout_iter_copy),
        (pango_layout_iter_free):
        * pango/pango-layout.h:
        * pango/pango-matrix.c (pango_matrix_copy), (pango_matrix_free):
        Update all copy/free functions to accept NULL as legitimate input.
        Previously all were g_return_[val_]if_fail()ing it.

        * pango/pango.def:
        * docs/pango-sections.txt:
        * docs/tmpl/glyphs.sgml:
        * docs/tmpl/layout.sgml:
        Update.


svn path=/trunk/; revision=2457

11 files changed, 165 insertions, 63 deletions

diff --git a/pango/fonts.c b/pango/fonts.c
index 0979ba1a..88627636 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -657,19 +657,21 @@ pango_font_description_better_match (const PangoFontDescription *desc,
 
 /**
  * pango_font_description_copy:
- * @desc: a #PangoFontDescription
+ * @desc: a #PangoFontDescription, may be %NULL
  *
  * Make a copy of a #PangoFontDescription.
  *
  * Return value: the newly allocated #PangoFontDescription, which should
- *               be freed with pango_font_description_free().
+ *               be freed with pango_font_description_free(), or %NULL
+ *               if @desc was %NULL.
  **/
 PangoFontDescription *
 pango_font_description_copy  (const PangoFontDescription  *desc)
 {
   PangoFontDescription *result;
 
-  g_return_val_if_fail (desc != NULL, NULL);
+  if (desc == NULL)
+    return NULL;
 
   result = g_slice_new (PangoFontDescription);
 
@@ -686,7 +688,7 @@ pango_font_description_copy  (const PangoFontDescription  *desc)
 
 /**
  * pango_font_description_copy_static:
- * @desc: a #PangoFontDescription
+ * @desc: a #PangoFontDescription, may be %NULL
  *
  * Like pango_font_description_copy(), but only a shallow copy is made
  * of the family name and other allocated fields. The result can only
@@ -694,14 +696,16 @@ pango_font_description_copy  (const PangoFontDescription  *desc)
  * when the copy is only needed temporarily.
  *
  * Return value: the newly allocated #PangoFontDescription, which should
- *               be freed with pango_font_description_free().
+ *               be freed with pango_font_description_free(), or %NULL
+ *               if @desc was %NULL.
  **/
 PangoFontDescription *
 pango_font_description_copy_static (const PangoFontDescription *desc)
 {
   PangoFontDescription *result;
 
-  g_return_val_if_fail (desc != NULL, NULL);
+  if (desc == NULL)
+    return NULL;
 
   result = g_slice_new (PangoFontDescription);
 
@@ -794,25 +798,25 @@ pango_font_description_hash (const PangoFontDescription *desc)
 
 /**
  * pango_font_description_free:
- * @desc: a #PangoFontDescription, or %NULL
+ * @desc: a #PangoFontDescription, may be %NULL
  *
  * Frees a font description.
  **/
 void
 pango_font_description_free  (PangoFontDescription  *desc)
 {
-  if (desc)
-    {
-      if (desc->family_name && !desc->static_family)
-	g_free (desc->family_name);
+  if (desc == NULL)
+    return;
 
-      g_slice_free (PangoFontDescription, desc);
-    }
+  if (desc->family_name && !desc->static_family)
+    g_free (desc->family_name);
+
+  g_slice_free (PangoFontDescription, desc);
 }
 
 /**
  * pango_font_descriptions_free:
- * @descs: a pointer to an array of #PangoFontDescription, or %NULL
+ * @descs: a pointer to an array of #PangoFontDescription, may be %NULL
  * @n_descs: number of font descriptions in @descs
  *
  * Frees a list of font descriptions from pango_font_map_list_fonts()
@@ -823,12 +827,12 @@ pango_font_descriptions_free (PangoFontDescription **descs,
 {
   int i;
 
-  if (descs)
-    {
-      for (i = 0; i<n_descs; i++)
-	pango_font_description_free (descs[i]);
-      g_free (descs);
-    }
+  if (descs == NULL)
+    return;
+
+  for (i = 0; i<n_descs; i++)
+    pango_font_description_free (descs[i]);
+  g_free (descs);
 }
 
 typedef struct
@@ -1455,7 +1459,7 @@ pango_font_metrics_new (void)
 
 /**
  * pango_font_metrics_ref:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a #PangoFontMetrics structure, may be %NULL
  *
  * Increase the reference count of a font metrics structure by one.
  *
@@ -1464,7 +1468,7 @@ pango_font_metrics_new (void)
 PangoFontMetrics *
 pango_font_metrics_ref (PangoFontMetrics *metrics)
 {
-  if (!metrics)
+  if (metrics == NULL)
     return NULL;
 
   metrics->ref_count++;
@@ -1474,7 +1478,7 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
 
 /**
  * pango_font_metrics_unref:
- * @metrics: a #PangoFontMetrics structure
+ * @metrics: a #PangoFontMetrics structure, may be %NULL
  *
  * Decrease the reference count of a font metrics structure by one. If
  * the result is zero, frees the structure and any associated
@@ -1483,8 +1487,9 @@ pango_font_metrics_ref (PangoFontMetrics *metrics)
 void
 pango_font_metrics_unref (PangoFontMetrics *metrics)
 {
-  if (!metrics)
+  if (metrics == NULL)
     return;
+
   g_return_if_fail (metrics->ref_count > 0 );
 
   metrics->ref_count--;
diff --git a/pango/glyphstring.c b/pango/glyphstring.c
index d8e4dd31..6aeba2b7 100644
--- a/pango/glyphstring.c
+++ b/pango/glyphstring.c
@@ -92,17 +92,23 @@ pango_glyph_string_get_type (void)
 
 /**
  * pango_glyph_string_copy:
- * @string: a #PangoGlyphString.
+ * @string: a #PangoGlyphString, may be %NULL
  *
- *  Copy a glyph string and associated storage.
+ * Copy a glyph string and associated storage.
  *
  * Return value: the newly allocated #PangoGlyphString, which
- *               should be freed with pango_glyph_string_free().
+ *               should be freed with pango_glyph_string_free(),
+ *               or %NULL if @string was %NULL.
  */
 PangoGlyphString *
 pango_glyph_string_copy (PangoGlyphString *string)
 {
-  PangoGlyphString *new_string = g_slice_new (PangoGlyphString);
+  PangoGlyphString *new_string;
+
+  if (new_string == NULL)
+    return NULL;
+  
+  new_string = g_slice_new (PangoGlyphString);
 
   *new_string = *string;
 
@@ -116,13 +122,15 @@ pango_glyph_string_copy (PangoGlyphString *string)
 
 /**
  * pango_glyph_string_free:
- * @string:    a #PangoGlyphString.
+ * @string: a #PangoGlyphString, may be %NULL
  *
  * Free a glyph string and associated storage.
  */
 void
 pango_glyph_string_free (PangoGlyphString *string)
 {
+  if (string == NULL)
+    return;
   g_free (string->glyphs);
   g_free (string->log_clusters);
   g_slice_free (PangoGlyphString, string);
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index a9a4c26a..1b864678 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -1060,7 +1060,7 @@ pango_attr_list_new (void)
 
 /**
  * pango_attr_list_ref:
- * @list: a #PangoAttrList
+ * @list: a #PangoAttrList, may be %NULL
  *
  * Increase the reference count of the given attribute list by one.
  *
@@ -1071,7 +1071,8 @@ pango_attr_list_new (void)
 PangoAttrList *
 pango_attr_list_ref (PangoAttrList *list)
 {
-  g_return_val_if_fail (list != NULL, NULL);
+  if (list == NULL)
+    return NULL;
 
   list->ref_count++;
 
@@ -1080,7 +1081,7 @@ pango_attr_list_ref (PangoAttrList *list)
 
 /**
  * pango_attr_list_unref:
- * @list: a #PangoAttrList
+ * @list: a #PangoAttrList, may be %NULL
  *
  * Decrease the reference count of the given attribute list by one.
  * If the result is zero, free the attribute list and the attributes
@@ -1091,7 +1092,9 @@ pango_attr_list_unref (PangoAttrList *list)
 {
   GSList *tmp_list;
 
-  g_return_if_fail (list != NULL);
+  if (list == NULL)
+    return;
+
   g_return_if_fail (list->ref_count > 0);
 
   list->ref_count--;
@@ -1114,13 +1117,14 @@ pango_attr_list_unref (PangoAttrList *list)
 
 /**
  * pango_attr_list_copy:
- * @list: a #PangoAttrList
+ * @list: a #PangoAttrList, may be %NULL
  *
  * Copy @list and return an identical new list.
  *
  * Return value: the newly allocated #PangoAttrList, with a
  *               reference count of one, which should
  *               be freed with pango_attr_list_unref().
+ *               Returns %NULL if @list was %NULL.
  **/
 PangoAttrList *
 pango_attr_list_copy (PangoAttrList *list)
@@ -1129,7 +1133,8 @@ pango_attr_list_copy (PangoAttrList *list)
   GSList *iter;
   GSList *new_attrs;
 
-  g_return_val_if_fail (list != NULL, NULL);
+  if (list == NULL)
+    return NULL;
 
   new = pango_attr_list_new ();
 
diff --git a/pango/pango-color.c b/pango/pango-color.c
index beae87fa..eec81ae4 100644
--- a/pango/pango-color.c
+++ b/pango/pango-color.c
@@ -42,7 +42,7 @@ pango_color_get_type (void)
 
 /**
  * pango_color_copy:
- * @src: color to copy
+ * @src: color to copy, may be %NULL
  *
  * Creates a copy of @src, which should be freed with
  * pango_color_free(). Primarily used by language bindings,
@@ -50,14 +50,16 @@ pango_color_get_type (void)
  * by assignment in C).
  *
  * Return value: the newly allocated #PangoColor, which should
- *               be freed with pango_color_free().
+ *               be freed with pango_color_free(), or %NULL
+ *               if @src was %NULL.
  **/
 PangoColor*
 pango_color_copy (const PangoColor *src)
 {
   PangoColor *ret;
 
-  g_return_val_if_fail (src != NULL, NULL);
+  if (src == NULL)
+    return NULL;
 
   ret = g_slice_new (PangoColor);
 
@@ -68,14 +70,15 @@ pango_color_copy (const PangoColor *src)
 
 /**
  * pango_color_free:
- * @color: an allocated #PangoColor
+ * @color: an allocated #PangoColor, may be %NULL
  *
  * Frees a color allocated by pango_color_copy().
  **/
 void
 pango_color_free (PangoColor *color)
 {
-  g_return_if_fail (color != NULL);
+  if (color == NULL)
+    return;
 
   g_slice_free (PangoColor, color);
 }
diff --git a/pango/pango-glyph-item.c b/pango/pango-glyph-item.c
index 07b844bc..1da934a4 100644
--- a/pango/pango-glyph-item.c
+++ b/pango/pango-glyph-item.c
@@ -24,6 +24,7 @@
 
 #include "pango-glyph-item.h"
 #include "pango-glyph-item-private.h"
+#include "pango-impl-utils.h"
 
 #define LTR(glyph_item) (((glyph_item)->item->analysis.level % 2) == 0)
 
@@ -130,8 +131,36 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 }
 
 /**
+ * pango_glyph_item_copy:
+ * @orig: a #PangoGlyphItem, may be %NULL
+ *
+ * Make a deep copy an existing #PangoGlyphItem structure.
+ *
+ * Return value: the newly allocated #PangoGlyphItem, which should
+ *               be freed with pango_glyph_item_free(), or %NULL
+ *               if @orig was %NULL.
+ *
+ * Since: 1.20
+ **/
+PangoGlyphItem *
+pango_glyph_item_copy  (PangoGlyphItem *orig)
+{
+  PangoGlyphItem *result;
+
+  if (orig == NULL)
+    return NULL;
+
+  result = g_slice_new (PangoGlyphItem);
+
+  result->item = pango_item_copy (orig->item);
+  result->glyphs = pango_glyph_string_copy (orig->glyphs);
+
+  return result;
+}
+
+/**
  * pango_glyph_item_free:
- * @glyph_item: a #PangoGlyphItem
+ * @glyph_item: a #PangoGlyphItem, may be %NULL
  *
  * Frees a #PangoGlyphItem and memory to which it points.
  *
@@ -140,6 +169,9 @@ pango_glyph_item_split (PangoGlyphItem *orig,
 void
 pango_glyph_item_free  (PangoGlyphItem *glyph_item)
 {
+  if (glyph_item == NULL)
+    return;
+
   if (glyph_item->item)
     pango_item_free (glyph_item->item);
   if (glyph_item->glyphs)
@@ -148,6 +180,18 @@ pango_glyph_item_free  (PangoGlyphItem *glyph_item)
   g_slice_free (PangoGlyphItem, glyph_item);
 }
 
+GType
+pango_glyph_item_get_type (void)
+{
+  static GType our_type = 0;
+
+  if (G_UNLIKELY (our_type == 0))
+    our_type = g_boxed_type_register_static (I_("PangoGlyphItem"),
+					     (GBoxedCopyFunc) pango_glyph_item_copy,
+					     (GBoxedFreeFunc) pango_glyph_item_free);
+  return our_type;
+}
+
 /**
  * _pango_glyph_item_iter_next_cluster:
  * @iter: a #PangoGlyphItemIter
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index fec086a4..4bad2651 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -37,9 +37,14 @@ struct _PangoGlyphItem
   PangoGlyphString *glyphs;
 };
 
+#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
+
+GType pango_glyph_item_get_type (void) G_GNUC_CONST;
+
 PangoGlyphItem *pango_glyph_item_split        (PangoGlyphItem *orig,
 					       const char     *text,
 					       int             split_index);
+PangoGlyphItem *pango_glyph_item_copy         (PangoGlyphItem *orig);
 void            pango_glyph_item_free         (PangoGlyphItem *glyph_item);
 GSList *        pango_glyph_item_apply_attrs  (PangoGlyphItem *glyph_item,
 					       const char     *text,
diff --git a/pango/pango-item.c b/pango/pango-item.c
index d5650827..3c7ff57c 100644
--- a/pango/pango-item.c
+++ b/pango/pango-item.c
@@ -42,18 +42,24 @@ pango_item_new (void)
 
 /**
  * pango_item_copy:
- * @item: a #PangoItem
+ * @item: a #PangoItem, may be %NULL
  *
  * Copy an existing #PangoItem structure.
  *
  * Return value: the newly allocated #PangoItem, which should
- *               be freed with pango_item_free().
+ *               be freed with pango_item_free(), or %NULL if
+ *               @item was NULL.
  **/
 PangoItem *
 pango_item_copy (PangoItem *item)
 {
   GSList *extra_attrs, *tmp_list;
-  PangoItem *result = g_slice_new (PangoItem);
+  PangoItem *result;
+
+  if (item == NULL)
+    return NULL;
+  
+  result = g_slice_new (PangoItem);
 
   result->offset = item->offset;
   result->length = item->length;
@@ -78,13 +84,16 @@ pango_item_copy (PangoItem *item)
 
 /**
  * pango_item_free:
- * @item: a #PangoItem
+ * @item: a #PangoItem, may be %NULL
  *
  * Free a #PangoItem and all associated memory.
  **/
 void
 pango_item_free (PangoItem *item)
 {
+  if (item == NULL)
+    return;
+
   if (item->analysis.extra_attrs)
     {
       g_slist_foreach (item->analysis.extra_attrs, (GFunc)pango_attribute_destroy, NULL);
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 0c6c7717..4ddb4b7c 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -3675,7 +3675,7 @@ pango_layout_check_lines (PangoLayout *layout)
 
 /**
  * pango_layout_line_ref:
- * @line: a #PangoLayoutLine
+ * @line: a #PangoLayoutLine, may be %NULL
  *
  * Increase the reference count of a #PangoLayoutLine by one.
  *
@@ -3688,7 +3688,8 @@ pango_layout_line_ref (PangoLayoutLine *line)
 {
   PangoLayoutLinePrivate *private = (PangoLayoutLinePrivate *)line;
 
-  g_return_val_if_fail (line != NULL, NULL);
+  if (line == NULL)
+    return NULL;
 
   private->ref_count++;
 
@@ -3708,7 +3709,9 @@ pango_layout_line_unref (PangoLayoutLine *line)
 {
   PangoLayoutLinePrivate *private = (PangoLayoutLinePrivate *)line;
 
-  g_return_if_fail (line != NULL);
+  if (line == NULL)
+    return;
+
   g_return_if_fail (private->ref_count > 0);
 
   private->ref_count--;
@@ -5153,12 +5156,27 @@ update_run (PangoLayoutIter *iter,
     }
 }
 
-static PangoLayoutIter *
+/**
+ * pango_layout_iter_copy:
+ * @iter: a #PangoLayoutIter, may be %NULL
+ *
+ * Copies a #PangLayoutIter.
+ *
+ * Return value: the newly allocated #PangoLayoutIter, which should
+ *               be freed with pango_layout_iter_free(), or %NULL if
+ *               @iter was %NULL.
+ *
+ * Since: 1.20
+ **/
+PangoLayoutIter *
 pango_layout_iter_copy (PangoLayoutIter *iter)
 {
   PangoLayoutIter *new;
   GSList *l;
 
+  if (iter == NULL)
+    return NULL;
+
   new = g_slice_new (PangoLayoutIter);
 
   new->layout = g_object_ref (iter->layout);
@@ -5269,14 +5287,15 @@ pango_layout_get_iter (PangoLayout *layout)
 
 /**
  * pango_layout_iter_free:
- * @iter: a #PangoLayoutIter
+ * @iter: a #PangoLayoutIter, may be %NULL
  *
  * Frees an iterator that's no longer in use.
  **/
 void
 pango_layout_iter_free (PangoLayoutIter *iter)
 {
-  g_return_if_fail (iter != NULL);
+  if (iter == NULL)
+    return;
 
   g_slist_foreach (iter->line_extents, (GFunc)extents_free, NULL);
   g_slist_free (iter->line_extents);
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 4e582b45..2deeedcf 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -243,6 +243,7 @@ typedef struct _PangoLayoutIter PangoLayoutIter;
 GType            pango_layout_iter_get_type (void) G_GNUC_CONST;
 
 PangoLayoutIter *pango_layout_get_iter  (PangoLayout     *layout);
+PangoLayoutIter *pango_layout_iter_copy (PangoLayoutIter *iter);
 void             pango_layout_iter_free (PangoLayoutIter *iter);
 
 int              pango_layout_iter_get_index  (PangoLayoutIter *iter);
diff --git a/pango/pango-matrix.c b/pango/pango-matrix.c
index 828d4f90..a8df59e3 100644
--- a/pango/pango-matrix.c
+++ b/pango/pango-matrix.c
@@ -41,7 +41,7 @@ pango_matrix_get_type (void)
 
 /**
  * pango_matrix_copy:
- * @matrix: a #PangoMatrix, can be %NULL
+ * @matrix: a #PangoMatrix, may be %NULL
  *
  * Copies a #PangoMatrix.
  *
@@ -56,31 +56,31 @@ pango_matrix_copy (const PangoMatrix *matrix)
 {
   PangoMatrix *new_matrix;
 
-  if (matrix)
-    {
-      new_matrix = g_slice_new (PangoMatrix);
-      *new_matrix = *matrix;
-    }
-  else
-    new_matrix = NULL;
+  if (matrix == NULL)
+    return NULL;
+
+  new_matrix = g_slice_new (PangoMatrix);
+
+  *new_matrix = *matrix;
 
   return new_matrix;
 }
 
 /**
  * pango_matrix_free:
- * @matrix: a #PangoMatrix, or %NULL
+ * @matrix: a #PangoMatrix, may be %NULL
  *
  * Free a #PangoMatrix created with pango_matrix_copy().
- * Does nothing if @matrix is %NULL.
  *
  * Since: 1.6
  **/
 void
 pango_matrix_free (PangoMatrix *matrix)
 {
-  if (matrix)
-    g_slice_free (PangoMatrix, matrix);
+  if (matrix == NULL)
+    return;
+
+  g_slice_free (PangoMatrix, matrix);
 }
 
 /**
diff --git a/pango/pango.def b/pango/pango.def
index 5dc464dc..3f822f6c 100644
--- a/pango/pango.def
+++ b/pango/pango.def
@@ -175,7 +175,9 @@ EXPORTS
 	pango_get_mirror_char
 	pango_get_sysconf_subdirectory
 	pango_glyph_item_apply_attrs
+	pango_glyph_item_copy
 	pango_glyph_item_free
+	pango_glyph_item_get_type
 	pango_glyph_item_letter_space
 	pango_glyph_item_split
 	pango_glyph_string_copy
@@ -243,6 +245,7 @@ EXPORTS
 	pango_layout_is_ellipsized
 	pango_layout_is_wrapped
 	pango_layout_iter_at_last_line
+	pango_layout_iter_copy
 	pango_layout_iter_free
 	pango_layout_iter_get_baseline
 	pango_layout_iter_get_char_extents