Index: doc/public/cairo-sections.txt
===================================================================
RCS file: /cvs/cairo/cairo/doc/public/cairo-sections.txt,v
retrieving revision 1.33
diff -u -p -r1.33 cairo-sections.txt
--- doc/public/cairo-sections.txt	24 Aug 2005 04:10:39 -0000	1.33
+++ doc/public/cairo-sections.txt	21 Jan 2006 16:10:06 -0000
@@ -202,6 +202,7 @@ cairo_scaled_font_status
 cairo_font_extents_t
 cairo_scaled_font_extents
 cairo_text_extents_t
+cairo_scaled_font_text_extents
 cairo_scaled_font_glyph_extents
 </SECTION>
 
Index: src/cairo-scaled-font.c
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo-scaled-font.c,v
retrieving revision 1.11
diff -u -p -r1.11 cairo-scaled-font.c
--- src/cairo-scaled-font.c	20 Jan 2006 23:25:55 -0000	1.11
+++ src/cairo-scaled-font.c	21 Jan 2006 16:10:06 -0000
@@ -585,14 +585,61 @@ cairo_scaled_font_extents (cairo_scaled_
 }
 
 /**
+ * cairo_scaled_font_text_extents:
+ * @scaled_font: a #cairo_scaled_font_t
+ * @utf8: a string of text, encoded in UTF-8
+ * @extents: a #cairo_text_extents_t which to store the retrieved extents.
+ *
+ * Gets the extents for a string of text. The extents describe a
+ * user-space rectangle that encloses the "inked" portion of the text
+ * drawn at the origin (0,0) (as it would be drawn by cairo_show_text()
+ * if the cairo graphics state were set to the same font_face,
+ * font_matrix, ctm, and font_options as @scaled_font).  Additionally,
+ * the x_advance and y_advance values indicate the amount by which the
+ * current point would be advanced by cairo_show_text().
+ *
+ * Note that whitespace characters do not directly contribute to the
+ * size of the rectangle (extents.width and extents.height). They do
+ * contribute indirectly by changing the position of non-whitespace
+ * characters. In particular, trailing whitespace characters are
+ * likely to not affect the size of the rectangle, though they will
+ * affect the x_advance and y_advance values.
+ **/
+void
+cairo_scaled_font_text_extents (cairo_scaled_font_t   *scaled_font,
+				const char            *utf8,
+				cairo_text_extents_t  *extents)
+{
+    cairo_status_t status = CAIRO_STATUS_SUCCESS;
+    cairo_glyph_t *glyphs;
+    int num_glyphs;
+
+    status = _cairo_scaled_font_text_to_glyphs (scaled_font, 0., 0., utf8, &glyphs, &num_glyphs);
+    if (status) {
+        _cairo_scaled_font_set_error (scaled_font, status);
+        return;
+    }
+    cairo_scaled_font_glyph_extents (scaled_font, glyphs, num_glyphs, extents);
+    free (glyphs);
+}
+
+/**
  * cairo_scaled_font_glyph_extents:
  * @scaled_font: a #cairo_scaled_font_t
  * @glyphs: an array of glyph IDs with X and Y offsets.
  * @num_glyphs: the number of glyphs in the @glyphs array
  * @extents: a #cairo_text_extents_t which to store the retrieved extents.
- * 
- * cairo_font_glyph_extents() gets the overall metrics for a string of
- * glyphs. The X and Y offsets in @glyphs are taken from an origin of 0,0. 
+ *
+ * Gets the extents for an array of glyphs. The extents describe a
+ * user-space rectangle that encloses the "inked" portion of the
+ * glyphs, (as they would be drawn by cairo_show_glyphs() if the cairo
+ * graphics state were set to the same font_face, font_matrix, ctm,
+ * and font_options as @scaled_font).  Additionally, the x_advance and
+ * y_advance values indicate the amount by which the current point
+ * would be advanced by cairo_show_glyphs.
+ *
+ * Note that whitespace glyphs do not contribute to the size of the
+ * rectangle (extents.width and extents.height).
  **/
 void
 cairo_scaled_font_glyph_extents (cairo_scaled_font_t   *scaled_font,
Index: src/cairo.h
===================================================================
RCS file: /cvs/cairo/cairo/src/cairo.h,v
retrieving revision 1.156
diff -u -p -r1.156 cairo.h
--- src/cairo.h	20 Jan 2006 23:25:55 -0000	1.156
+++ src/cairo.h	21 Jan 2006 16:10:06 -0000
@@ -928,6 +928,11 @@ cairo_scaled_font_extents (cairo_scaled_
 			   cairo_font_extents_t *extents);
 
 cairo_public void
+cairo_scaled_font_text_extents (cairo_scaled_font_t  *scaled_font,
+				const char  	     *utf8,
+				cairo_text_extents_t *extents);
+
+cairo_public void
 cairo_scaled_font_glyph_extents (cairo_scaled_font_t   *scaled_font,
 				 cairo_glyph_t         *glyphs, 
 				 int                   num_glyphs,