luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-09-20 09:16:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

gobject: Document behaviour of GType checking macros on NULL

Browse Source 
The macros differ in their handling of NULL values — some macros ignore
them and pass through (e.g. G_TYPE_CHECK_INSTANCE_CAST) while others
will explicitly emit a warning if passed NULL (e.g.
G_TYPE_CHECK_INSTANCE).

Document their behaviour, so people don’t end up putting unnecessary
NULL checks in their code when doing checked type casts.

https://bugzilla.gnome.org/show_bug.cgi?id=735731
This commit is contained in:
Philip Withnall 2014-08-30 23:45:18 +01:00
parent c8330b80fc
commit 953c182d25
1 changed files with 13 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
gobject/gtype.h
View File

@ -457,7 +457,8 @@ struct _GTypeQuery
* @instance: Location of a #GTypeInstance structure * @instance: Location of a #GTypeInstance structure
* *
* Checks if @instance is a valid #GTypeInstance structure, * Checks if @instance is a valid #GTypeInstance structure,
* otherwise issues a warning and returns %FALSE. * otherwise issues a warning and returns %FALSE. %NULL is not a valid
* #GTypeInstance.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
* *
@ -466,23 +467,26 @@ struct _GTypeQuery
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance))) #define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
/** /**
* G_TYPE_CHECK_INSTANCE_CAST: * G_TYPE_CHECK_INSTANCE_CAST:
* @instance: Location of a #GTypeInstance structure * @instance: (nullable): Location of a #GTypeInstance structure
* @g_type: The type to be returned * @g_type: The type to be returned
* @c_type: The corresponding C type of @g_type * @c_type: The corresponding C type of @g_type
* *
* Checks that @instance is an instance of the type identified by @g_type * Checks that @instance is an instance of the type identified by @g_type
* and issues a warning if this is not the case. Returns @instance casted * and issues a warning if this is not the case. Returns @instance casted
* to a pointer to @c_type. * to a pointer to @c_type.
*
* No warning will be issued if @instance is %NULL, and %NULL will be returned.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
*/ */
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type)) #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
/** /**
* G_TYPE_CHECK_INSTANCE_TYPE: * G_TYPE_CHECK_INSTANCE_TYPE:
* @instance: Location of a #GTypeInstance structure. * @instance: (nullable): Location of a #GTypeInstance structure.
* @g_type: The type to be checked * @g_type: The type to be checked
* *
* Checks if @instance is an instance of the type identified by @g_type. * Checks if @instance is an instance of the type identified by @g_type. If
* @instance is %NULL, %FALSE will be returned.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
* *
@ -491,10 +495,11 @@ struct _GTypeQuery
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type))) #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
/** /**
* G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE: * G_TYPE_CHECK_INSTANCE_FUNDAMENTAL_TYPE:
* @instance: Location of a #GTypeInstance structure. * @instance: (nullable): Location of a #GTypeInstance structure.
* @g_type: The fundamental type to be checked * @g_type: The fundamental type to be checked
* *
* Checks if @instance is an instance of the fundamental type identified by @g_type. * Checks if @instance is an instance of the fundamental type identified by @g_type.
* If @instance is %NULL, %FALSE will be returned.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
* *
@ -539,18 +544,18 @@ struct _GTypeQuery
* *
* Checks that @g_class is a class structure of the type identified by @g_type * Checks that @g_class is a class structure of the type identified by @g_type
* and issues a warning if this is not the case. Returns @g_class casted * and issues a warning if this is not the case. Returns @g_class casted
* to a pointer to @c_type. * to a pointer to @c_type. %NULL is not a valid class structure.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
*/ */
#define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type)) #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
/** /**
* G_TYPE_CHECK_CLASS_TYPE: * G_TYPE_CHECK_CLASS_TYPE:
* @g_class: Location of a #GTypeClass structure * @g_class: (nullable): Location of a #GTypeClass structure
* @g_type: The type to be checked * @g_type: The type to be checked
* *
* Checks if @g_class is a class structure of the type identified by * Checks if @g_class is a class structure of the type identified by
* @g_type. * @g_type. If @g_class is %NULL, %FALSE will be returned.
* *
* This macro should only be used in type implementations. * This macro should only be used in type implementations.
* *