src/libcaptive/include/captive/macros.h

   1 /* $Id$
   2  * Include file with general macros and typedefs used through Captive project
   3  * Copyright (C) 2002 Jan Kratochvil <project-captive@jankratochvil.net>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; exactly version 2 of June 1991 is required
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License
  15  * along with this program; if not, write to the Free Software
  16  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  17  */
  18
  19
  20 #ifndef _CAPTIVE_MACROS_H
  21 #define _CAPTIVE_MACROS_H 1
  22
  23
  24 #include <glib/gmacros.h>
  25 #include <glib/gmem.h>
  26 #include <stdarg.h>
  27 #include <string.h>     /* for memset() */
  28 #include <glib/galloca.h>
  29 #include <glib/gmessages.h>
  30
  31
  32 G_BEGIN_DECLS
  33
  34 /**
  35  * CAPTIVE_FAKEUSE:
  36  *
  37  * Prevent 'might be used uninitialized' warning.
  38  * Macro will fakes the use of the variable as sometimes GCC can't code flow
  39  * analyse #C correctly.
  40  *
  41  * <informalexample>
  42  * <programlisting>
  43  * g_some_type some_variable CAPTIVE_FAKEUSE;
  44  * </programlisting>
  45  * </informalexample>
  46  */
  47 #define CAPTIVE_FAKEUSE =0
  48
  49
  50 /**
  51  * captive_newn:
  52  * @objp: Variable with the pointer to the objects wished to be allocated.
  53  * Original value is discarded.
  54  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  55  *
  56  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  57  * Allocated memory may contain garbage.
  58  *
  59  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  60  * Value %NULL is returned iff @n==%0;
  61  */
  62 #define captive_newn(objp,n) ((objp)=g_new(typeof(*(objp)),(n)))
  63
  64
  65 /**
  66  * captive_new0n:
  67  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
  68  * Original value is discarded.
  69  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
  70  *
  71  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  72  * Allocated memory is precleared.
  73  *
  74  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
  75  * Value %NULL is returned iff @n==%0;
  76  */
  77 #define captive_new0n(objp,n) ((objp)=g_new0(typeof(*(objp)),(n)))
  78
  79
  80 /**
  81  * captive_renewn:
  82  * @objp: Variable with the pointer to the objects wished to be reallocated.
  83  * Value %NULL is permitted (g_malloc() effect).
  84  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  85  *
  86  * Macro to reallocate the original memory stored in @objp
  87  * to the size @n objects of type *@objp and to assign the resulting pointer to @objp.
  88  * New allocated space may contain garbage. Both @objp and @n can be nonexclusively
  89  * passed as zero.
  90  *
  91  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  92  * Value %NULL is returned iff @n==%0;
  93  */
  94 #define captive_renewn(objp,n) ({ \
  95                 typeof(&(objp)) _captive_renewn_objpp=&(objp); \
  96                 *_captive_renewn_objpp=g_renew(typeof(*(objp)),*_captive_renewn_objpp,(n)); \
  97                 (*_captive_renewn_objpp); \
  98                 })
  99
 100
 101 /**
 102  * captive_new:
 103  * @objp: Variable with the pointer to the object wished to be allocated.
 104  * Original value is discarded.
 105  *
 106  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 107  * Allocated memory may contain garbage. Equivalent to captive_newn(objp,1) call.
 108  *
 109  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 110  * Value %NULL is never returned.
 111  */
 112 #define captive_new(objp) (captive_newn((objp),1))
 113
 114
 115 /**
 116  * captive_new0:
 117  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 118  * Original value is discarded.
 119  *
 120  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 121  * Allocated memory is precleared. Equivalent to captive_new0n(objp,1) call.
 122  *
 123  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 124  * Value %NULL is never returned.
 125  */
 126 #define captive_new0(objp) (captive_new0n((objp),1))
 127
 128
 129 /**
 130  * captive_newn_alloca:
 131  * @objp: Variable with the pointer to the objects wished to be allocated.
 132  * Original value is discarded.
 133  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
 134  *
 135  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
 136  * Allocated memory may contain garbage.
 137  *
 138  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 139  * during exit of current function (or current block if variable sized variables present there).
 140  * You cannot deallocate or reallocate such memory in any other way.
 141  *
 142  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
 143  * Value %NULL is returned iff @n==%0;
 144  */
 145 #define captive_newn_alloca(objp,n) ({ \
 146                 gsize _captive_newn_alloca_n=(n); \
 147                 /* Fix 'g_alloca(0)!=NULL': */ \
 148                 ((objp)=(!_captive_newn_alloca_n ? NULL : g_alloca(sizeof(*(objp))*_captive_newn_alloca_n))); \
 149                 })
 150
 151
 152 /**
 153  * captive_new0n_alloca:
 154  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
 155  * Original value is discarded.
 156  * @n: Numbers of objects to be allocated. Value %0 is permitted (%NULL assignment effect).
 157  *
 158  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
 159  * Allocated memory is precleared.
 160  *
 161  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 162  * during exit of current function (or current block if variable sized variables present there).
 163  * You cannot deallocate or reallocate such memory in any other way.
 164  *
 165  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
 166  * Value %NULL is returned iff @n==%0;
 167  */
 168 #define captive_new0n_alloca(objp,n) ({ \
 169                 typeof(&(objp)) _captive_new0n_alloca_objpp=&(objp); \
 170                 captive_newn_alloca(*_captive_new0n_alloca_objpp,(n)); \
 171                 CAPTIVE_MEMZERO(*_captive_new0n_alloca_objpp); \
 172                 (*_captive_new0n_alloca_objpp); \
 173                 })
 174
 175
 176 /**
 177  * captive_new_alloca:
 178  * @objp: Variable with the pointer to the object wished to be allocated.
 179  * Original value is discarded.
 180  *
 181  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 182  * Allocated memory may contain garbage. Equivalent to captive_newn_alloca(objp,1) call.
 183  *
 184  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 185  * during exit of current function (or current block if variable sized variables present there).
 186  * You cannot deallocate or reallocate such memory in any other way.
 187  *
 188  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 189  * Value %NULL is never returned.
 190  */
 191 #define captive_new_alloca(objp) (captive_newn_alloca((objp),1))
 192
 193
 194 /**
 195  * captive_new0_alloca:
 196  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 197  * Original value is discarded.
 198  *
 199  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 200  * Allocated memory is precleared. Equivalent to captive_new0n_alloca(objp,1) call.
 201  *
 202  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 203  */
 204 #define captive_new0_alloca(objp) (captive_new0n_alloca((objp),1))
 205
 206
 207 /**
 208  * captive_va_arg:
 209  * @objp: Variable to be filled from the next argument of @ap.
 210  * @ap: Initialized #va_list type.
 211  *
 212  * Automatically determines the size of @objp.
 213  * Equivalent to objp=va_arg(ap,typeof(objp)) call.
 214  *
 215  * @Returns: Initialized @objp value.
 216  */
 217 #define captive_va_arg(objp,ap) ((objp)=va_arg((ap),typeof(objp)))
 218
 219
 220 /**
 221  * CAPTIVE_MEMZERO:
 222  * @objp: Pointer to the variable to be cleared.
 223  *
 224  * Clears the sizeof(*@objp) bytes of the given pointer with memset().
 225  * Pass _pointer_ to the object to be cleared.
 226  */
 227 #define CAPTIVE_MEMZERO(objp) (memset((objp),0,sizeof(*(objp))))
 228
 229
 230 /**
 231  * captive_printf_alloca:
 232  * @format: Format string. See the sprintf() documentation.
 233  * @args: Arguments for @format. See the sprintf() documentation.
 234  *
 235  * Format the given format string @format as in sprintf().
 236  * Output buffer is allocated automatically and it does not need to be deallocated
 237  * manually as it is managed by g_alloca().
 238  *
 239  * @Returns: Formatted output string located in g_alloca() memory.
 240  */
 241 #define captive_printf_alloca(format,args...) ({ \
 242                 gsize _captive_printf_alloca_size=captive_nv_printf_string_upper_bound((format) , ## args); \
 243                 gchar *_captive_printf_alloca_r=g_alloca(_captive_printf_alloca_size); \
 244                 g_snprintf(_captive_printf_alloca_r,_captive_printf_alloca_size,(format) , ## args); \
 245                 (const gchar *)_captive_printf_alloca_r; \
 246                 })
 247 static inline gsize captive_nv_printf_string_upper_bound(const gchar *format,...) G_GNUC_PRINTF(1,0) G_GNUC_UNUSED;
 248 static inline gsize captive_nv_printf_string_upper_bound(const gchar *format,...)
 249 {
 250 va_list ap;
 251 gsize r;
 252
 253         va_start(ap,format);
 254         r=g_printf_string_upper_bound(format,ap);
 255         va_end(ap);
 256         return r;
 257 }
 258
 259
 260 /**
 261  * captive_strdup_alloca:
 262  * @string: #const #gchar * string to duplicate.
 263  *
 264  * Macro to do g_strdup() equivalent in g_alloca() style.
 265  *
 266  * Memory is allocated on the stack frame by g_alloca() and it will be automatically deallocated
 267  * during exit of current function (or current block if variable sized variables present there).
 268  * You cannot deallocate or reallocate such memory in any other way.
 269  *
 270  * @Returns: Duplicated @string. You may modify its items if the length is not changed.
 271  */
 272 #define captive_strdup_alloca(string) ({ \
 273                 const gchar *_captive_strdup_alloca_string=(string); \
 274                 gchar *_captive_strdup_alloca_r=g_alloca(strlen(_captive_strdup_alloca_string)+1); \
 275                 strcpy(_captive_strdup_alloca_r,_captive_strdup_alloca_string); \
 276                 (const gchar *)(_captive_strdup_alloca_string); \
 277                 })
 278
 279 G_END_DECLS
 280
 281
 282 #endif /* _CAPTIVE_MACROS_H */