[docs] Qualify the object constructor failure guarantee (#6364)

The lifecycle chapter claimed that all constructors return empty
singletons on failure. Constructors ending in _or_fail instead return
NULL, including the established blob constructors.

Describe both conventions and require checking _or_fail results.
Validated the XML and reproduced the blob constructor behavior with
a nonexistent file and an oversized blob. Documentation only.

Fixes: https://github.com/harfbuzz/harfbuzz/issues/6359
Assisted-by: Codex
This commit is contained in:
Behdad Esfahbod authored and GitHub committed 2026-10-10 18:34:47 -06:00
1 parent 9d044f792d
commit aa5eff6b85
1 file changed
+9 -5
+9 -5
View File
@@ -172,11 +172,15 @@
they will need to make a duplicate of the original.
</para>
<para>
Finally, object constructors (and, indeed, as much of the
shaping API as possible) will never return
<literal>NULL</literal>. Instead, if there is an allocation
error, each constructor will return an “empty” object
singleton.
Finally, most object constructors return an “empty” object
singleton on allocation failure rather than
<literal>NULL</literal>. Constructors whose names end in
<literal>_or_fail</literal>, such as
<function>hb_blob_create_or_fail()</function> and
<function>hb_blob_create_from_file_or_fail()</function>, instead
return <literal>NULL</literal> on failure. Check their return
values before using the objects, and consult each constructor's
API Reference documentation for its failure behavior.
</para>
<para>
These empty-object singletons are inert and safe (although