1<!-- ##### SECTION Title ##### --> 2Standard Macros 3 4<!-- ##### SECTION Short_Description ##### --> 5commonly-used macros. 6 7<!-- ##### SECTION Long_Description ##### --> 8<para> 9These macros provide a few commonly-used features. 10</para> 11 12<!-- ##### SECTION See_Also ##### --> 13<para> 14 15</para> 16 17<!-- ##### SECTION Stability_Level ##### --> 18 19 20<!-- ##### MACRO G_OS_WIN32 ##### --> 21<para> 22This macro is defined only on Windows. So you can bracket 23Windows-specific code in "#ifdef G_OS_WIN32". 24</para> 25 26 27 28<!-- ##### MACRO G_OS_BEOS ##### --> 29<para> 30This macro is defined only on BeOS. So you can bracket 31BeOS-specific code in "#ifdef G_OS_BEOS". 32</para> 33 34 35 36<!-- ##### MACRO G_OS_UNIX ##### --> 37<para> 38This macro is defined only on UNIX. So you can bracket 39UNIX-specific code in "#ifdef G_OS_UNIX". 40</para> 41 42 43 44<!-- ##### MACRO G_DIR_SEPARATOR ##### --> 45<para> 46The directory separator character. 47This is '/' on UNIX machines and '\' under Windows. 48</para> 49 50 51 52<!-- ##### MACRO G_DIR_SEPARATOR_S ##### --> 53<para> 54The directory separator as a string. 55This is "/" on UNIX machines and "\" under Windows. 56</para> 57 58 59 60<!-- ##### MACRO G_IS_DIR_SEPARATOR ##### --> 61<para> 62Checks whether a character is a directory 63separator. It returns %TRUE for '/' on UNIX 64machines and for '\' or '/' under Windows. 65</para> 66 67@c: a character 68@Since: 2.6 69 70 71<!-- ##### MACRO G_SEARCHPATH_SEPARATOR ##### --> 72<para> 73The search path separator character. 74This is ':' on UNIX machines and ';' under Windows. 75</para> 76 77 78 79<!-- ##### MACRO G_SEARCHPATH_SEPARATOR_S ##### --> 80<para> 81The search path separator as a string. 82This is ":" on UNIX machines and ";" under Windows. 83</para> 84 85 86 87<!-- ##### MACRO TRUE ##### --> 88<para> 89Defines the %TRUE value for the #gboolean type. 90</para> 91 92 93 94<!-- ##### MACRO FALSE ##### --> 95<para> 96Defines the %FALSE value for the #gboolean type. 97</para> 98 99 100 101<!-- ##### MACRO NULL ##### --> 102<para> 103Defines the standard %NULL pointer. 104</para> 105 106 107 108<!-- ##### MACRO MIN ##### --> 109<para> 110Calculates the minimum of @a and @b. 111</para> 112 113@a: a numeric value. 114@b: a numeric value. 115@Returns: the minimum of @a and @b. 116 117 118<!-- ##### MACRO MAX ##### --> 119<para> 120Calculates the maximum of @a and @b. 121</para> 122 123@a: a numeric value. 124@b: a numeric value. 125@Returns: the maximum of @a and @b. 126 127 128<!-- ##### MACRO ABS ##### --> 129<para> 130Calculates the absolute value of @a. 131The absolute value is simply the number with any negative sign taken away. 132</para> 133<para> 134For example, 135<itemizedlist> 136<listitem><para> 137ABS(-10) is 10. 138</para></listitem> 139<listitem><para> 140ABS(10) is also 10. 141</para></listitem> 142</itemizedlist> 143</para> 144 145@a: a numeric value. 146@Returns: the absolute value of @a. 147 148 149<!-- ##### MACRO CLAMP ##### --> 150<para> 151Ensures that @x is between the limits set by @low and @high. If @low is 152greater than @high the result is undefined. 153</para> 154<para> 155For example, 156<itemizedlist> 157<listitem><para> 158CLAMP(5, 10, 15) is 10. 159</para></listitem> 160<listitem><para> 161CLAMP(15, 5, 10) is 10. 162</para></listitem> 163<listitem><para> 164CLAMP(20, 15, 25) is 20. 165</para></listitem> 166</itemizedlist> 167</para> 168 169@x: the value to clamp. 170@low: the minimum value allowed. 171@high: the maximum value allowed. 172@Returns: the value of @x clamped to the range between @low and @high. 173 174 175<!-- ##### MACRO G_STRUCT_MEMBER ##### --> 176<para> 177Returns a member of a structure at a given offset, using the given type. 178</para> 179 180@member_type: the type of the struct field. 181@struct_p: a pointer to a struct. 182@struct_offset: the offset of the field from the start of the struct, in bytes. 183@Returns: the struct member. 184 185 186<!-- ##### MACRO G_STRUCT_MEMBER_P ##### --> 187<para> 188Returns an untyped pointer to a given offset of a struct. 189</para> 190 191@struct_p: a pointer to a struct. 192@struct_offset: the offset from the start of the struct, in bytes. 193@Returns: an untyped pointer to @struct_p plus @struct_offset bytes. 194 195 196<!-- ##### MACRO G_STRUCT_OFFSET ##### --> 197<para> 198Returns the offset, in bytes, of a member of a struct. 199</para> 200 201@struct_type: a structure type, e.g. <structname>GtkWidget</structname>. 202@member: a field in the structure, e.g. <structfield>window</structfield>. 203@Returns: the offset of @member from the start of @struct_type. 204 205 206<!-- ##### MACRO G_MEM_ALIGN ##### --> 207<para> 208Indicates the number of bytes to which memory will be aligned on the 209current platform. 210</para> 211 212 213 214<!-- ##### MACRO G_CONST_RETURN ##### --> 215<para> 216If %G_DISABLE_CONST_RETURNS is defined, this macro expands to nothing. 217By default, the macro expands to <literal>const</literal>. The macro 218should be used in place of <literal>const</literal> for functions that 219return a value that should not be modified. The purpose of this macro is 220to allow us to turn on <literal>const</literal> for returned constant 221strings by default, while allowing programmers who find that annoying to 222turn it off. This macro should only be used for return values and for 223<emphasis>out</emphasis> parameters, it doesn't make sense for 224<emphasis>in</emphasis> parameters. 225</para> 226 227 228 229