Cosmetic: Improved comments

captive_renewn(): Prevented double evaluation of 'objp'
+captive_newn_alloca()
+captive_new0n_alloca()
+captive_new_alloca()
+captive_new0_alloca()

diff --git a/src/libcaptive/include/captive/macros.h b/src/libcaptive/include/captive/macros.h
index ffc300c..96d1ce6 100644 (file)
--- a/src/libcaptive/include/captive/macros.h
+++ b/src/libcaptive/include/captive/macros.h
@@ -25,6 +25,7 @@
 #include <glib/gmem.h>
 #include <stdarg.h>
 #include <string.h>    /* for memset() */
+#include <glib/galloca.h>
 
 
 G_BEGIN_DECLS
@@ -49,12 +50,13 @@ G_BEGIN_DECLS
  * captive_newn:
  * @objp: Variable with the pointer to the objects wished to be allocated.
  * Original value is discarded.
- * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
+ * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  *
- * Macto to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
+ * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  * Allocated memory may contain garbage.
  *
  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
+ * Value %NULL is returned iff @n==%0;
  */
 #define captive_newn(objp,n) ((objp)=g_new(typeof(*(objp)),(n)))
 
@@ -63,12 +65,13 @@ G_BEGIN_DECLS
  * captive_new0n:
  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
  * Original value is discarded.
- * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
+ * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  *
  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  * Allocated memory is precleared.
  * 
  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
+ * Value %NULL is returned iff @n==%0;
  */
 #define captive_new0n(objp,n) ((objp)=g_new0(typeof(*(objp)),(n)))
 
@@ -85,8 +88,13 @@ G_BEGIN_DECLS
  * passed as zero.
  * 
  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
+ * Value %NULL is returned iff @n==%0;
  */
-#define captive_renewn(objp,n) ((objp)=g_renew(typeof(*(objp)),(objp),(n)))
+#define captive_renewn(objp,n) ({ \
+               typeof(&(objp)) _captive_renewn_objpp=&(objp); \
+               *_captive_renewn_objpp=g_renew(typeof(*(objp)),*_captive_renewn_objpp,(n)); \
+               (*_captive_renewn_objpp); \
+               })
 
 
 /**
@@ -94,10 +102,11 @@ G_BEGIN_DECLS
  * @objp: Variable with the pointer to the object wished to be allocated.
  * Original value is discarded.
  *
- * Macto to allocate one object of type *@objp and to assign the resulting pointer to @objp.
+ * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
  * Allocated memory may contain garbage. Equivalent to captive_newn(objp,1) call.
  *
  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
+ * Value %NULL is never returned.
  */
 #define captive_new(objp) (captive_newn((objp),1))
 
@@ -111,11 +120,90 @@ G_BEGIN_DECLS
  * Allocated memory is precleared. Equivalent to captive_new0n(objp,1) call.
  * 
  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
+ * Value %NULL is never returned.
  */
 #define captive_new0(objp) (captive_new0n((objp),1))
 
 
 /**
+ * captive_newn_alloca:
+ * @objp: Variable with the pointer to the objects wished to be allocated.
+ * Original value is discarded.
+ * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
+ *
+ * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
+ * Allocated memory may contain garbage.
+ * 
+ * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
+ * during exit of current function (or current block if variable sized variables present there).
+ * You cannot deallocate or reallocate such memory in any other way.
+ *
+ * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
+ * Value %NULL is returned iff @n==%0;
+ */
+#define captive_newn_alloca(objp,n) ({ \
+               size_t _captive_newn_alloca_n=(n); \
+               /* Fix 'g_alloca(0)!=NULL': */ \
+               ((objp)=(!_captive_newn_alloca_n ? NULL : g_alloca(sizeof(*(objp))*_captive_newn_alloca_n))); \
+               })
+
+
+/**
+ * captive_new0n_alloca:
+ * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
+ * Original value is discarded.
+ * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
+ *
+ * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
+ * Allocated memory is precleared.
+ * 
+ * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
+ * during exit of current function (or current block if variable sized variables present there).
+ * You cannot deallocate or reallocate such memory in any other way.
+ * 
+ * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
+ * Value %NULL is returned iff @n==%0;
+ */
+#define captive_new0n_alloca(objp,n) ({ \
+               typeof(&(objp)) _captive_new0n_alloca_objpp=&(objp); \
+               captive_newn_alloca(*_captive_new0n_alloca_objpp,(n)); \
+               CAPTIVE_MEMZERO(*_captive_new0n_alloca_objpp); \
+               (*_captive_new0n_alloca_objpp); \
+               })
+
+
+/**
+ * captive_new_alloca:
+ * @objp: Variable with the pointer to the object wished to be allocated.
+ * Original value is discarded.
+ *
+ * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
+ * Allocated memory may contain garbage. Equivalent to captive_newn_alloca(objp,1) call.
+ * 
+ * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
+ * during exit of current function (or current block if variable sized variables present there).
+ * You cannot deallocate or reallocate such memory in any other way.
+ *
+ * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
+ * Value %NULL is never returned.
+ */
+#define captive_new_alloca(objp) (captive_newn_alloca((objp),1))
+
+
+/**
+ * captive_new0_alloca:
+ * @objp: Variable with the pointer to the object wished to be allocated and precleared.
+ * Original value is discarded.
+ *
+ * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
+ * Allocated memory is precleared. Equivalent to captive_new0n_alloca(objp,1) call.
+ * 
+ * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
+ */
+#define captive_new0_alloca(objp) (captive_new0n_alloca((objp),1))
+
+
+/**
  * captive_va_arg:
  * @objp: Variable to be filled from the next argument of @ap.
  * @ap: Initialized #va_list type.