docs/reference/glib/tmpl/queue.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Double-ended Queues
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 double-ended queue data structure
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The #GQueue structure and its associated functions provide a standard
  10 queue data structure. Internally, #GQueue uses the same data structure as
  11 #GList to store elements.
  12 </para>
  13 <para>
  14 The data contained in each element can be either integer values, by using one
  15 of the
  16 <link linkend="glib-Type-Conversion-Macros">Type Conversion Macros</link>,
  17 or simply pointers to any type of data.
  18 </para>
  19 <para>
  20 To create a new #GQueue, use g_queue_new().
  21 </para>
  22 <para>
  23 To initialize a statically-allocated #GQueue, use #G_QUEUE_INIT or
  24 g_queue_init().
  25 </para>
  26 <para>
  27 To add elements, use g_queue_push_head(), g_queue_push_head_link(),
  28 g_queue_push_tail() and g_queue_push_tail_link().
  29 </para>
  30 <para>
  31 To remove elements, use g_queue_pop_head() and g_queue_pop_tail().
  32 </para>
  33 <para>
  34 To free the entire queue, use g_queue_free().
  35 </para>
  36
  37 <!-- ##### SECTION See_Also ##### -->
  38 <para>
  39
  40 </para>
  41
  42 <!-- ##### SECTION Stability_Level ##### -->
  43
  44
  45 <!-- ##### STRUCT GQueue ##### -->
  46 <para>
  47 Contains the public fields of a <link linkend="glib-queues">Queue</link>.
  48 </para>
  49
  50 @head: a pointer to the first element of the queue.
  51 @tail: a pointer to the last element of the queue.
  52 @length: the number of elements in the queue.
  53
  54 <!-- ##### FUNCTION g_queue_new ##### -->
  55 <para>
  56
  57 </para>
  58
  59 @Returns:
  60
  61
  62 <!-- ##### FUNCTION g_queue_free ##### -->
  63 <para>
  64
  65 </para>
  66
  67 @queue:
  68
  69
  70 <!-- ##### MACRO G_QUEUE_INIT ##### -->
  71 <para>
  72 A statically-allocated #GQueue must be initialized with this macro before it
  73 can be used.  This macro can be used to initialize a variable, but it cannot
  74 be assigned to a variable.  In that case you have to use g_queue_init().
  75 </para>
  76
  77 <informalexample>
  78 <programlisting>
  79 GQueue my_queue = G_QUEUE_INIT;
  80 </programlisting>
  81 </informalexample>
  82
  83 @Since: 2.14
  84
  85
  86 <!-- ##### FUNCTION g_queue_init ##### -->
  87 <para>
  88
  89 </para>
  90
  91 @queue:
  92
  93
  94 <!-- ##### FUNCTION g_queue_clear ##### -->
  95 <para>
  96
  97 </para>
  98
  99 @queue:
 100
 101
 102 <!-- ##### FUNCTION g_queue_is_empty ##### -->
 103 <para>
 104
 105 </para>
 106
 107 @queue:
 108 @Returns:
 109
 110
 111 <!-- ##### FUNCTION g_queue_get_length ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @queue:
 117 @Returns:
 118
 119
 120 <!-- ##### FUNCTION g_queue_reverse ##### -->
 121 <para>
 122
 123 </para>
 124
 125 @queue:
 126
 127
 128 <!-- ##### FUNCTION g_queue_copy ##### -->
 129 <para>
 130
 131 </para>
 132
 133 @queue:
 134 @Returns:
 135
 136
 137 <!-- ##### FUNCTION g_queue_foreach ##### -->
 138 <para>
 139
 140 </para>
 141
 142 @queue:
 143 @func:
 144 @user_data:
 145
 146
 147 <!-- ##### FUNCTION g_queue_find ##### -->
 148 <para>
 149
 150 </para>
 151
 152 @queue:
 153 @data:
 154 @Returns:
 155
 156
 157 <!-- ##### FUNCTION g_queue_find_custom ##### -->
 158 <para>
 159
 160 </para>
 161
 162 @queue:
 163 @data:
 164 @func:
 165 @Returns:
 166
 167
 168 <!-- ##### FUNCTION g_queue_sort ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @queue:
 174 @compare_func:
 175 @user_data:
 176
 177
 178 <!-- ##### FUNCTION g_queue_push_head ##### -->
 179 <para>
 180
 181 </para>
 182
 183 @queue:
 184 @data:
 185
 186
 187 <!-- ##### FUNCTION g_queue_push_tail ##### -->
 188 <para>
 189
 190 </para>
 191
 192 @queue:
 193 @data:
 194
 195
 196 <!-- ##### FUNCTION g_queue_push_nth ##### -->
 197 <para>
 198
 199 </para>
 200
 201 @queue:
 202 @data:
 203 @n:
 204
 205
 206 <!-- ##### FUNCTION g_queue_pop_head ##### -->
 207 <para>
 208
 209 </para>
 210
 211 @queue:
 212 @Returns:
 213
 214
 215 <!-- ##### FUNCTION g_queue_pop_tail ##### -->
 216 <para>
 217
 218 </para>
 219
 220 @queue:
 221 @Returns:
 222
 223
 224 <!-- ##### FUNCTION g_queue_pop_nth ##### -->
 225 <para>
 226
 227 </para>
 228
 229 @queue:
 230 @n:
 231 @Returns:
 232
 233
 234 <!-- ##### FUNCTION g_queue_peek_head ##### -->
 235 <para>
 236
 237 </para>
 238
 239 @queue:
 240 @Returns:
 241
 242
 243 <!-- ##### FUNCTION g_queue_peek_tail ##### -->
 244 <para>
 245
 246 </para>
 247
 248 @queue:
 249 @Returns:
 250
 251
 252 <!-- ##### FUNCTION g_queue_peek_nth ##### -->
 253 <para>
 254
 255 </para>
 256
 257 @queue:
 258 @n:
 259 @Returns:
 260
 261
 262 <!-- ##### FUNCTION g_queue_index ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @queue:
 268 @data:
 269 @Returns:
 270
 271
 272 <!-- ##### FUNCTION g_queue_remove ##### -->
 273 <para>
 274
 275 </para>
 276
 277 @queue:
 278 @data:
 279
 280
 281 <!-- ##### FUNCTION g_queue_remove_all ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @queue:
 287 @data:
 288
 289
 290 <!-- ##### FUNCTION g_queue_insert_before ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @queue:
 296 @sibling:
 297 @data:
 298
 299
 300 <!-- ##### FUNCTION g_queue_insert_after ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @queue:
 306 @sibling:
 307 @data:
 308
 309
 310 <!-- ##### FUNCTION g_queue_insert_sorted ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @queue:
 316 @data:
 317 @func:
 318 @user_data:
 319
 320
 321 <!-- ##### FUNCTION g_queue_push_head_link ##### -->
 322 <para>
 323
 324 </para>
 325
 326 @queue:
 327 @link_:
 328
 329
 330 <!-- ##### FUNCTION g_queue_push_tail_link ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @queue:
 336 @link_:
 337
 338
 339 <!-- ##### FUNCTION g_queue_push_nth_link ##### -->
 340 <para>
 341
 342 </para>
 343
 344 @queue:
 345 @n:
 346 @link_:
 347
 348
 349 <!-- ##### FUNCTION g_queue_pop_head_link ##### -->
 350 <para>
 351
 352 </para>
 353
 354 @queue:
 355 @Returns:
 356
 357
 358 <!-- ##### FUNCTION g_queue_pop_tail_link ##### -->
 359 <para>
 360
 361 </para>
 362
 363 @queue:
 364 @Returns:
 365
 366
 367 <!-- ##### FUNCTION g_queue_pop_nth_link ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @queue:
 373 @n:
 374 @Returns:
 375
 376
 377 <!-- ##### FUNCTION g_queue_peek_head_link ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @queue:
 383 @Returns:
 384
 385
 386 <!-- ##### FUNCTION g_queue_peek_tail_link ##### -->
 387 <para>
 388
 389 </para>
 390
 391 @queue:
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION g_queue_peek_nth_link ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @queue:
 401 @n:
 402 @Returns:
 403
 404
 405 <!-- ##### FUNCTION g_queue_link_index ##### -->
 406 <para>
 407
 408 </para>
 409
 410 @queue:
 411 @link_:
 412 @Returns:
 413
 414
 415 <!-- ##### FUNCTION g_queue_unlink ##### -->
 416 <para>
 417
 418 </para>
 419
 420 @queue:
 421 @link_:
 422
 423
 424 <!-- ##### FUNCTION g_queue_delete_link ##### -->
 425 <para>
 426
 427 </para>
 428
 429 @queue:
 430 @link_:
 431
 432