docs/reference/glib/tmpl/types.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Basic Types
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 standard GLib types, defined for ease-of-use and portability
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 GLib defines a number of commonly used types, which can be divided into
  10 4 groups:
  11
  12 <itemizedlist>
  13 <listitem><para>
  14 New types which are not part of standard C (but are defined
  15 in various C standard library header files) -
  16 #gboolean, #gsize, #gssize, #goffset, #gintptr, #guintptr.
  17 </para></listitem>
  18
  19 <listitem><para>
  20 Integer types which are guaranteed to be the same size across all platforms -
  21 #gint8, #guint8, #gint16, #guint16, #gint32, #guint32, #gint64, #guint64.
  22 </para></listitem>
  23
  24 <listitem><para>
  25 Types which are easier to use than their standard C counterparts -
  26 #gpointer, #gconstpointer, #guchar, #guint, #gushort, #gulong.
  27 </para></listitem>
  28
  29 <listitem><para>
  30 Types which correspond exactly to standard C types, but are included
  31 for completeness - #gchar, #gint, #gshort, #glong, #gfloat, #gdouble.
  32 </para></listitem>
  33 </itemizedlist>
  34
  35 </para>
  36
  37 <!-- ##### SECTION See_Also ##### -->
  38 <para>
  39
  40 </para>
  41
  42 <!-- ##### SECTION Stability_Level ##### -->
  43
  44
  45 <!-- ##### SECTION Image ##### -->
  46
  47
  48 <!-- ##### TYPEDEF gboolean ##### -->
  49 <para>
  50 A standard <type>boolean</type> type.
  51 Variables of this type should only contain the value %TRUE or %FALSE.
  52 </para>
  53
  54
  55 <!-- ##### TYPEDEF gpointer ##### -->
  56 <para>
  57 An untyped pointer.
  58 #gpointer looks better and is easier to use than <type>void*</type>.
  59 </para>
  60
  61
  62 <!-- ##### TYPEDEF gconstpointer ##### -->
  63 <para>
  64 An untyped pointer to constant data.
  65 The data pointed to should not be changed.
  66 </para>
  67 <para>
  68 This is typically used in function prototypes to indicate that the
  69 data pointed to will not be altered by the function.
  70 </para>
  71
  72
  73 <!-- ##### TYPEDEF gchar ##### -->
  74 <para>
  75 Corresponds to the standard C <type>char</type> type.
  76 </para>
  77
  78
  79 <!-- ##### TYPEDEF guchar ##### -->
  80 <para>
  81 Corresponds to the standard C <type>unsigned char</type> type.
  82 </para>
  83
  84
  85 <!-- ##### TYPEDEF gint ##### -->
  86 <para>
  87 Corresponds to the standard C <type>int</type> type.
  88 Values of this type can range from #G_MININT to #G_MAXINT.
  89 </para>
  90
  91
  92 <!-- ##### TYPEDEF guint ##### -->
  93 <para>
  94 Corresponds to the standard C <type>unsigned int</type> type.
  95 Values of this type can range from 0 to #G_MAXUINT.
  96 </para>
  97
  98
  99 <!-- ##### TYPEDEF gshort ##### -->
 100 <para>
 101 Corresponds to the standard C <type>short</type> type.
 102 Values of this type can range from #G_MINSHORT to #G_MAXSHORT.
 103 </para>
 104
 105
 106 <!-- ##### TYPEDEF gushort ##### -->
 107 <para>
 108 Corresponds to the standard C <type>unsigned short</type> type.
 109 Values of this type can range from 0 to #G_MAXUSHORT.
 110 </para>
 111
 112
 113 <!-- ##### TYPEDEF glong ##### -->
 114 <para>
 115 Corresponds to the standard C <type>long</type> type.
 116 Values of this type can range from #G_MINLONG to #G_MAXLONG.
 117 </para>
 118
 119
 120 <!-- ##### TYPEDEF gulong ##### -->
 121 <para>
 122 Corresponds to the standard C <type>unsigned long</type> type.
 123 Values of this type can range from 0 to #G_MAXULONG.
 124 </para>
 125
 126
 127 <!-- ##### TYPEDEF gint8 ##### -->
 128 <para>
 129 A signed integer guaranteed to be 8 bits on all platforms.
 130 Values of this type can range from #G_MININT8 (= -128) to
 131 #G_MAXINT8 (= 127).
 132 </para>
 133
 134
 135 <!-- ##### TYPEDEF guint8 ##### -->
 136 <para>
 137 An unsigned integer guaranteed to be 8 bits on all platforms.
 138 Values of this type can range from 0 to #G_MAXUINT8 (= 255).
 139 </para>
 140
 141
 142 <!-- ##### TYPEDEF gint16 ##### -->
 143 <para>
 144 A signed integer guaranteed to be 16 bits on all platforms.
 145 Values of this type can range from #G_MININT16 (= -32,768) to
 146 #G_MAXINT16 (= 32,767).
 147 </para>
 148 <para>
 149 To print or scan values of this type, use
 150 %G_GINT16_MODIFIER and/or %G_GINT16_FORMAT.
 151 </para>
 152
 153
 154 <!-- ##### TYPEDEF guint16 ##### -->
 155 <para>
 156 An unsigned integer guaranteed to be 16 bits on all platforms.
 157 Values of this type can range from 0 to #G_MAXUINT16 (= 65,535).
 158 </para>
 159 <para>
 160 To print or scan values of this type, use
 161 %G_GINT16_MODIFIER and/or %G_GUINT16_FORMAT.
 162 </para>
 163
 164
 165 <!-- ##### TYPEDEF gint32 ##### -->
 166 <para>
 167 A signed integer guaranteed to be 32 bits on all platforms.
 168 Values of this type can range from #G_MININT32 (= -2,147,483,648) to
 169 #G_MAXINT32 (= 2,147,483,647).
 170 </para>
 171 <para>
 172 To print or scan values of this type, use
 173 %G_GINT32_MODIFIER and/or %G_GINT32_FORMAT.
 174 </para>
 175
 176
 177 <!-- ##### TYPEDEF guint32 ##### -->
 178 <para>
 179 An unsigned integer guaranteed to be 32 bits on all platforms.
 180 Values of this type can range from 0 to #G_MAXUINT32 (= 4,294,967,295).
 181 </para>
 182 <para>
 183 To print or scan values of this type, use
 184 %G_GINT32_MODIFIER and/or %G_GUINT32_FORMAT.
 185 </para>
 186
 187
 188 <!-- ##### MACRO G_HAVE_GINT64 ##### -->
 189 <para>
 190 This macro is defined if 64-bit signed and unsigned integers are available
 191 on the platform.
 192 </para>
 193
 194 @Deprecated: GLib requires 64-bit integer support since version 2.0, therefore
 195 %G_HAVE_GINT64 is <emphasis>always</emphasis> defined.
 196
 197
 198 <!-- ##### TYPEDEF gint64 ##### -->
 199 <para>
 200 A signed integer guaranteed to be 64 bits on all platforms.
 201 Values of this type can range from #G_MININT64 (= -9,223,372,036,854,775,808) to
 202 #G_MAXINT64 (= 9,223,372,036,854,775,807).
 203 </para>
 204 <para>
 205 To print or scan values of this type, use
 206 %G_GINT64_MODIFIER and/or %G_GINT64_FORMAT.
 207 </para>
 208
 209
 210 <!-- ##### TYPEDEF guint64 ##### -->
 211 <para>
 212 An unsigned integer guaranteed to be 64 bits on all platforms.
 213 Values of this type can range from 0 to #G_MAXUINT64 (= 18,446,744,073,709,551,615).
 214 </para>
 215 <para>
 216 To print or scan values of this type, use
 217 %G_GINT64_MODIFIER and/or %G_GUINT64_FORMAT.
 218 </para>
 219
 220
 221 <!-- ##### MACRO G_GINT64_CONSTANT ##### -->
 222 <para>
 223 This macro is used to insert 64-bit integer literals into the source code.
 224 </para>
 225
 226 @val: a literal integer value, e.g. 0x1d636b02300a7aa7.
 227
 228
 229 <!-- ##### MACRO G_GUINT64_CONSTANT ##### -->
 230 <para>
 231 This macro is used to insert 64-bit unsigned integer literals into the
 232 source code.
 233 </para>
 234
 235 @val: a literal integer value, e.g. 0x1d636b02300a7aa7U.
 236 @Since: 2.10
 237
 238
 239 <!-- ##### TYPEDEF gfloat ##### -->
 240 <para>
 241 Corresponds to the standard C <type>float</type> type.
 242 Values of this type can range from -#G_MAXFLOAT to #G_MAXFLOAT.
 243 </para>
 244
 245
 246 <!-- ##### TYPEDEF gdouble ##### -->
 247 <para>
 248 Corresponds to the standard C <type>double</type> type.
 249 Values of this type can range from -#G_MAXDOUBLE to #G_MAXDOUBLE.
 250 </para>
 251
 252
 253 <!-- ##### TYPEDEF gsize ##### -->
 254 <para>
 255 An unsigned integer type of the result of the sizeof operator, corresponding
 256 to the size_t type defined in C99. This type is wide enough to hold the numeric
 257 value of a pointer, so it is usually 32bit wide on a 32bit platform and
 258 64bit wide on a 64bit platform.
 259 Values of this type can range from 0 to #G_MAXSIZE.
 260 </para>
 261 <para>
 262 To print or scan values of this type, use
 263 %G_GSIZE_MODIFIER and/or %G_GSIZE_FORMAT.
 264 </para>
 265
 266
 267 <!-- ##### TYPEDEF gssize ##### -->
 268 <para>
 269 A signed variant of gsize, corresponding to the ssize_t defined on most platforms.
 270 Values of this type can range from #G_MINSSIZE to #G_MAXSSIZE.
 271 </para>
 272 <para>
 273 To print or scan values of this type, use
 274 %G_GSIZE_MODIFIER and/or %G_GSSIZE_FORMAT.
 275 </para>
 276
 277
 278 <!-- ##### TYPEDEF goffset ##### -->
 279 <para>
 280 A signed integer type that is used for file offsets, corresponding to the
 281 C99 type off64_t.
 282 Values of this type can range from #G_MINOFFSET to #G_MAXOFFSET.
 283 </para>
 284 <para>
 285 To print or scan values of this type, use
 286 %G_GOFFSET_MODIFIER and/or %G_GOFFSET_FORMAT.
 287 </para>
 288
 289 Since: 2.14
 290
 291
 292 <!-- ##### MACRO G_GOFFSET_CONSTANT ##### -->
 293 <para>
 294 This macro is used to insert #goffset 64-bit integer literals into the source code.
 295 See also #G_GINT64_CONSTANT.
 296 </para>
 297
 298 @val: a literal integer value, e.g. 0x1d636b02300a7aa7.
 299 Since: 2.20
 300
 301
 302 <!-- ##### TYPEDEF gintptr ##### -->
 303 <para>
 304 Corresponds to the C99 type <type>intptr_t</type>, a signed integer type that
 305 can hold any pointer.
 306 </para>
 307 <para>
 308 To print or scan values of this type, use
 309 %G_GINTPTR_MODIFIER and/or %G_GINTPTR_FORMAT.
 310 </para>
 311
 312 Since: 2.18
 313
 314
 315 <!-- ##### TYPEDEF guintptr ##### -->
 316 <para>
 317 Corresponds to the C99 type <type>uintptr_t</type>, an unsigned integer type that
 318 can hold any pointer.
 319 </para>
 320 <para>
 321 To print or scan values of this type, use
 322 %G_GINTPTR_MODIFIER and/or %G_GUINTPTR_FORMAT.
 323 </para>
 324
 325 Since: 2.18
 326
 327