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
  28
  29 G_BEGIN_DECLS
  30
  31 /**
  32  * CAPTIVE_FAKEUSE:
  33  *
  34  * Prevent 'might be used uninitialized' warning.
  35  * Macro will fakes the use of the variable as sometimes GCC can't code flow
  36  * analyse #C correctly.
  37  *
  38  * <informalexample>
  39  * <programlisting>
  40  * g_some_type some_variable CAPTIVE_FAKEUSE;
  41  * </programlisting>
  42  * </informalexample>
  43  */
  44 #define CAPTIVE_FAKEUSE =0
  45
  46
  47 /**
  48  * captive_newn:
  49  * @objp: Variable with the pointer to the objects wished to be allocated.
  50  * Original value is discarded.
  51  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  52  *
  53  * Macto to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  54  * Allocated memory may contain garbage.
  55  *
  56  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  57  */
  58 #define captive_newn(objp,n) ((objp)=g_new(typeof(*(objp)),(n)))
  59
  60
  61 /**
  62  * captive_new0n:
  63  * @objp: Variable with the pointer to the objects wished to be allocated and precleared.
  64  * Original value is discarded.
  65  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  66  *
  67  * Macro to allocate @n objects of type *@objp and to assign the resulting pointer to @objp.
  68  * Allocated memory is precleared.
  69  *
  70  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp))*n.
  71  */
  72 #define captive_new0n(objp,n) ((objp)=g_new0(typeof(*(objp)),(n)))
  73
  74
  75 /**
  76  * captive_renewn:
  77  * @objp: Variable with the pointer to the objects wished to be reallocated.
  78  * Value %NULL is permitted (g_malloc() effect).
  79  * @n: Numbers of objects to be allocated. Value %0 is permitted (g_free() effect).
  80  *
  81  * Macro to reallocate the original memory stored in @objp
  82  * to the size @n objects of type *@objp and to assign the resulting pointer to @objp.
  83  * New allocated space may contain garbage. Both @objp and @n can be nonexclusively
  84  * passed as zero.
  85  *
  86  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp))*n.
  87  */
  88 #define captive_renewn(objp,n) ((objp)=g_renew(typeof(*(objp)),(objp),(n)))
  89
  90
  91 /**
  92  * captive_new:
  93  * @objp: Variable with the pointer to the object wished to be allocated.
  94  * Original value is discarded.
  95  *
  96  * Macto to allocate one object of type *@objp and to assign the resulting pointer to @objp.
  97  * Allocated memory may contain garbage. Equivalent to captive_newn(objp,1) call.
  98  *
  99  * @Returns: Initialized @objp value as the memory of size #sizeof(typeof(*objp)).
 100  */
 101 #define captive_new(objp) (captive_newn((objp),1))
 102
 103
 104 /**
 105  * captive_new0:
 106  * @objp: Variable with the pointer to the object wished to be allocated and precleared.
 107  * Original value is discarded.
 108  *
 109  * Macro to allocate one object of type *@objp and to assign the resulting pointer to @objp.
 110  * Allocated memory is precleared. Equivalent to captive_new0n(objp,1) call.
 111  *
 112  * @Returns: Initialized @objp value as the cleared memory of size #sizeof(typeof(*objp)).
 113  */
 114 #define captive_new0(objp) (captive_new0n((objp),1))
 115
 116
 117 /**
 118  * captive_va_arg:
 119  * @objp: Variable to be filled from the next argument of @ap.
 120  * @ap: Initialized #va_list type.
 121  *
 122  * Automatically determines the size of @objp.
 123  * Equivalent to objp=va_arg(ap,typeof(objp)) call.
 124  *
 125  * @Returns: Initialized @objp value.
 126  */
 127 #define captive_va_arg(objp,ap) ((objp)=va_arg((ap),typeof(objp)))
 128
 129 G_END_DECLS
 130
 131
 132 #endif /* _CAPTIVE_MACROS_H */