mirror of
https://github.com/storytold/harfbuzz.git
synced 2026-11-19 05:51:05 +01:00
[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:
1 parent
9d044f792d
commit
aa5eff6b85
1 file changed
+9
-5
@@ -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
|
||||
|
||||
Reference in new issue
Block a user