From 2437fd883a06bd5f7917352b507f9a1a496f161b Mon Sep 17 00:00:00 2001
From: Behdad Esfahbod <behdad@behdad.org>
Date: Sat, 12 Oct 2024 19:24:42 -0600
Subject: [PATCH] [face] Add hb_face_create_or_fail()

New API:
+ hb_face_create_or_fail()
---
 docs/harfbuzz-sections.txt |  1 +
 src/hb-face.cc             | 28 ++++++++++++++++++++++++++++
 src/hb-face.h              |  4 ++++
 3 files changed, 33 insertions(+)

diff --git a/docs/harfbuzz-sections.txt b/docs/harfbuzz-sections.txt
index 0cd82f810..49cae7fbc 100644
--- a/docs/harfbuzz-sections.txt
+++ b/docs/harfbuzz-sections.txt
@@ -357,6 +357,7 @@ hb_directwrite_face_get_font_face
 hb_face_count
 hb_face_t
 hb_face_create
+hb_face_create_or_fail
 hb_reference_table_func_t
 hb_face_create_for_tables
 hb_face_get_empty
diff --git a/src/hb-face.cc b/src/hb-face.cc
index 9b4af16f4..8d429c688 100644
--- a/src/hb-face.cc
+++ b/src/hb-face.cc
@@ -263,6 +263,34 @@ hb_face_create (hb_blob_t    *blob,
   return face;
 }
 
+/**
+ * hb_face_create_or_fail:
+ * @blob: #hb_blob_t to work upon
+ * @index: The index of the face within @blob
+ *
+ * Like hb_face_create(), but returns `NULL` if the blob data
+ * contains no usable font face at the specified index.
+ *
+ * Return value: (transfer full): The new face object, or `NULL` if
+ * no face is found at the specified index
+ *
+ * XSince: REPLACEME
+ **/
+hb_face_t *
+hb_face_create_or_fail (hb_blob_t    *blob,
+			unsigned int  index)
+{
+  unsigned num_faces = hb_face_count (blob);
+  if (index >= num_faces)
+    return nullptr;
+
+  hb_face_t *face = hb_face_create (blob, index);
+  if (hb_object_is_immutable (face))
+    return nullptr;
+
+  return face;
+}
+
 /**
  * hb_face_get_empty:
  *
diff --git a/src/hb-face.h b/src/hb-face.h
index 98d0afec2..f37bd3ce5 100644
--- a/src/hb-face.h
+++ b/src/hb-face.h
@@ -59,6 +59,10 @@ HB_EXTERN hb_face_t *
 hb_face_create (hb_blob_t    *blob,
 		unsigned int  index);
 
+HB_EXTERN hb_face_t *
+hb_face_create_or_fail (hb_blob_t    *blob,
+			unsigned int  index);
+
 /**
  * hb_reference_table_func_t:
  * @face: an #hb_face_t to reference table for