Commit 0f601e4d authored by Debarshi Ray's avatar Debarshi Ray

docs: Clarify some expections of the json_object_get_*_member APIs

It is an error to use the following with a missing member:

 • json_object_get_int_member
 • json_object_get_double_member
 • json_object_get_boolean_member
 • json_object_get_null_member
 • json_object_get_string_member
 • json_object_get_array_member
 • json_object_get_object_member

Doing so will lead to CRITICALs like these:
  Json-CRITICAL **: json_object_get_string_member: assertion
    'node != NULL' failed

Instead one of these should be used to determine the existence of the
member:

 • json_object_get_member
 • json_object_has_member

Or, when available, one can use the corresponding
json_object_get_<type>_member_with_default.

#24
parent 279de977
Pipeline #5803 passed with stage
in 3 minutes and 1 second
......@@ -567,7 +567,7 @@ object_get_member_internal (JsonObject *object,
* a #JsonObject.
*
* Return value: (transfer none) (nullable): a pointer to the node for the
* requested object member, or %NULL
* requested object member, or %NULL if it does not exist.
*/
JsonNode *
json_object_get_member (JsonObject *object,
......@@ -625,9 +625,11 @@ json_object_get_ ##type_name## _member_with_default (JsonObject *object, \
* @member_name: the name of the @object member
*
* Convenience function that retrieves the integer value
* stored in @member_name of @object
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_int_member_with_default(),
* json_object_get_member() and json_object_has_member()
*
* Return value: the integer value of the object's member
*
......@@ -660,9 +662,11 @@ JSON_OBJECT_GET_DEFAULT (gint64, int)
* @member_name: the name of the member
*
* Convenience function that retrieves the floating point value
* stored in @member_name of @object
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_double_member_with_default(),
* json_object_get_member() and json_object_has_member()
*
* Return value: the floating point value of the object's member
*
......@@ -695,9 +699,11 @@ JSON_OBJECT_GET_DEFAULT (double, double)
* @member_name: the name of the member
*
* Convenience function that retrieves the boolean value
* stored in @member_name of @object
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_boolean_member_with_default(),
* json_object_get_member() and json_object_has_member()
*
* Return value: the boolean value of the object's member
*
......@@ -730,9 +736,11 @@ JSON_OBJECT_GET_DEFAULT (gboolean, boolean)
* @member_name: the name of the member
*
* Convenience function that retrieves the string value
* stored in @member_name of @object
* stored in @member_name of @object. It is an error to specify a
* @member_name that does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_string_member_with_default(),
* json_object_get_member() and json_object_has_member()
*
* Return value: the string value of the object's member
*
......@@ -765,9 +773,10 @@ JSON_OBJECT_GET_DEFAULT (const char *, string)
* @member_name: the name of the member
*
* Convenience function that checks whether the value
* stored in @member_name of @object is null
* stored in @member_name of @object is null. It is an error to
* specify a @member_name which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_member() and json_object_has_member()
*
* Return value: %TRUE if the value is null
*
......@@ -803,9 +812,10 @@ json_object_get_null_member (JsonObject *object,
* @member_name: the name of the member
*
* Convenience function that retrieves the array
* stored in @member_name of @object
* stored in @member_name of @object. It is an error to specify a
* @member_name which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_member() and json_object_has_member()
*
* Return value: (transfer none): the array inside the object's member
*
......@@ -839,7 +849,7 @@ json_object_get_array_member (JsonObject *object,
* stored in @member_name of @object. It is an error to specify a @member_name
* which does not exist.
*
* See also: json_object_get_member()
* See also: json_object_get_member() and json_object_has_member()
*
* Return value: (transfer none) (nullable): the object inside the object’s
* member, or %NULL if the value for the member is `null`
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment