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
*
* 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.
*
@ -466,7 +467,7 @@ struct _GTypeQuery
#define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
/**
* 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
* @c_type: The corresponding C type of @g_type
*
@ -474,15 +475,18 @@ struct _GTypeQuery
* and issues a warning if this is not the case. Returns @instance casted
* 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.
*/
#define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_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
*
* 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.
*
@ -491,10 +495,11 @@ struct _GTypeQuery
#define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_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
*
* 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.
*
@ -539,18 +544,18 @@ struct _GTypeQuery
*
* 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
* 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.
*/
#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_class: Location of a #GTypeClass structure
* @g_class: (nullable): Location of a #GTypeClass structure
* @g_type: The type to be checked
*
* 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.
*