1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module glib.PtrArray; 26 27 private import glib.ConstructionException; 28 private import glib.c.functions; 29 public import glib.c.types; 30 public import gtkc.glibtypes; 31 32 33 /** 34 * Contains the public fields of a pointer array. 35 */ 36 public class PtrArray 37 { 38 /** the main Gtk struct */ 39 protected GPtrArray* gPtrArray; 40 protected bool ownedRef; 41 42 /** Get the main Gtk struct */ 43 public GPtrArray* getPtrArrayStruct(bool transferOwnership = false) 44 { 45 if (transferOwnership) 46 ownedRef = false; 47 return gPtrArray; 48 } 49 50 /** the main Gtk struct as a void* */ 51 protected void* getStruct() 52 { 53 return cast(void*)gPtrArray; 54 } 55 56 /** 57 * Sets our main struct and passes it to the parent class. 58 */ 59 public this (GPtrArray* gPtrArray, bool ownedRef = false) 60 { 61 this.gPtrArray = gPtrArray; 62 this.ownedRef = ownedRef; 63 } 64 65 /** 66 * Number of pointers in the array 67 */ 68 public uint len() pure 69 { 70 return gPtrArray.len; 71 } 72 73 /** 74 * Returns the pointer at the given index of the pointer array. 75 * 76 * This does not perform bounds checking on the given index, so 77 * you are responsible for checking it against the array length. 78 */ 79 public void* index(uint idx) 80 { 81 return (gPtrArray.pdata)[idx]; 82 } 83 84 /** 85 */ 86 87 /** 88 * Adds a pointer to the end of the pointer array. The array will grow 89 * in size automatically if necessary. 90 * 91 * Params: 92 * data = the pointer to add 93 */ 94 public void add(void* data) 95 { 96 g_ptr_array_add(gPtrArray, data); 97 } 98 99 /** 100 * Checks whether @needle exists in @haystack. If the element is found, %TRUE is 101 * returned and the element’s index is returned in @index_ (if non-%NULL). 102 * Otherwise, %FALSE is returned and @index_ is undefined. If @needle exists 103 * multiple times in @haystack, the index of the first instance is returned. 104 * 105 * This does pointer comparisons only. If you want to use more complex equality 106 * checks, such as string comparisons, use g_ptr_array_find_with_equal_func(). 107 * 108 * Params: 109 * needle = pointer to look for 110 * index = return location for the index of 111 * the element, if found 112 * 113 * Returns: %TRUE if @needle is one of the elements of @haystack 114 * 115 * Since: 2.54 116 */ 117 public bool find(void* needle, out uint index) 118 { 119 return g_ptr_array_find(gPtrArray, needle, &index) != 0; 120 } 121 122 /** 123 * Checks whether @needle exists in @haystack, using the given @equal_func. 124 * If the element is found, %TRUE is returned and the element’s index is 125 * returned in @index_ (if non-%NULL). Otherwise, %FALSE is returned and @index_ 126 * is undefined. If @needle exists multiple times in @haystack, the index of 127 * the first instance is returned. 128 * 129 * @equal_func is called with the element from the array as its first parameter, 130 * and @needle as its second parameter. If @equal_func is %NULL, pointer 131 * equality is used. 132 * 133 * Params: 134 * needle = pointer to look for 135 * equalFunc = the function to call for each element, which should 136 * return %TRUE when the desired element is found; or %NULL to use pointer 137 * equality 138 * index = return location for the index of 139 * the element, if found 140 * 141 * Returns: %TRUE if @needle is one of the elements of @haystack 142 * 143 * Since: 2.54 144 */ 145 public bool findWithEqualFunc(void* needle, GEqualFunc equalFunc, out uint index) 146 { 147 return g_ptr_array_find_with_equal_func(gPtrArray, needle, equalFunc, &index) != 0; 148 } 149 150 alias foreac = foreach_; 151 /** 152 * Calls a function for each element of a #GPtrArray. @func must not 153 * add elements to or remove elements from the array. 154 * 155 * Params: 156 * func = the function to call for each array element 157 * userData = user data to pass to the function 158 * 159 * Since: 2.4 160 */ 161 public void foreach_(GFunc func, void* userData) 162 { 163 g_ptr_array_foreach(gPtrArray, func, userData); 164 } 165 166 /** 167 * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE 168 * it frees the memory block holding the elements as well. Pass %FALSE 169 * if you want to free the #GPtrArray wrapper but preserve the 170 * underlying array for use elsewhere. If the reference count of @array 171 * is greater than one, the #GPtrArray wrapper is preserved but the 172 * size of @array will be set to zero. 173 * 174 * If array contents point to dynamically-allocated memory, they should 175 * be freed separately if @free_seg is %TRUE and no #GDestroyNotify 176 * function has been set for @array. 177 * 178 * This function is not thread-safe. If using a #GPtrArray from multiple 179 * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() 180 * functions. 181 * 182 * Params: 183 * freeSeg = if %TRUE the actual pointer array is freed as well 184 * 185 * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. 186 * The pointer array should be freed using g_free(). 187 */ 188 public void** free(bool freeSeg) 189 { 190 return g_ptr_array_free(gPtrArray, freeSeg); 191 } 192 193 /** 194 * Inserts an element into the pointer array at the given index. The 195 * array will grow in size automatically if necessary. 196 * 197 * Params: 198 * index = the index to place the new element at, or -1 to append 199 * data = the pointer to add. 200 * 201 * Since: 2.40 202 */ 203 public void insert(int index, void* data) 204 { 205 g_ptr_array_insert(gPtrArray, index, data); 206 } 207 208 /** 209 * Creates a new #GPtrArray with a reference count of 1. 210 * 211 * Returns: the new #GPtrArray 212 * 213 * Throws: ConstructionException GTK+ fails to create the object. 214 */ 215 public this() 216 { 217 auto p = g_ptr_array_new(); 218 219 if(p is null) 220 { 221 throw new ConstructionException("null returned by new"); 222 } 223 224 this(cast(GPtrArray*) p); 225 } 226 227 /** 228 * Creates a new #GPtrArray with @reserved_size pointers preallocated 229 * and a reference count of 1. This avoids frequent reallocation, if 230 * you are going to add many pointers to the array. Note however that 231 * the size of the array is still 0. It also set @element_free_func 232 * for freeing each element when the array is destroyed either via 233 * g_ptr_array_unref(), when g_ptr_array_free() is called with 234 * @free_segment set to %TRUE or when removing elements. 235 * 236 * Params: 237 * reservedSize = number of pointers preallocated 238 * elementFreeFunc = A function to free elements with 239 * destroy @array or %NULL 240 * 241 * Returns: A new #GPtrArray 242 * 243 * Since: 2.30 244 * 245 * Throws: ConstructionException GTK+ fails to create the object. 246 */ 247 public this(uint reservedSize, GDestroyNotify elementFreeFunc) 248 { 249 auto p = g_ptr_array_new_full(reservedSize, elementFreeFunc); 250 251 if(p is null) 252 { 253 throw new ConstructionException("null returned by new_full"); 254 } 255 256 this(cast(GPtrArray*) p); 257 } 258 259 /** 260 * Creates a new #GPtrArray with a reference count of 1 and use 261 * @element_free_func for freeing each element when the array is destroyed 262 * either via g_ptr_array_unref(), when g_ptr_array_free() is called with 263 * @free_segment set to %TRUE or when removing elements. 264 * 265 * Params: 266 * elementFreeFunc = A function to free elements with 267 * destroy @array or %NULL 268 * 269 * Returns: A new #GPtrArray 270 * 271 * Since: 2.22 272 * 273 * Throws: ConstructionException GTK+ fails to create the object. 274 */ 275 public this(GDestroyNotify elementFreeFunc) 276 { 277 auto p = g_ptr_array_new_with_free_func(elementFreeFunc); 278 279 if(p is null) 280 { 281 throw new ConstructionException("null returned by new_with_free_func"); 282 } 283 284 this(cast(GPtrArray*) p); 285 } 286 287 alias doref = ref_; 288 /** 289 * Atomically increments the reference count of @array by one. 290 * This function is thread-safe and may be called from any thread. 291 * 292 * Returns: The passed in #GPtrArray 293 * 294 * Since: 2.22 295 */ 296 public PtrArray ref_() 297 { 298 auto p = g_ptr_array_ref(gPtrArray); 299 300 if(p is null) 301 { 302 return null; 303 } 304 305 return new PtrArray(cast(GPtrArray*) p); 306 } 307 308 /** 309 * Removes the first occurrence of the given pointer from the pointer 310 * array. The following elements are moved down one place. If @array 311 * has a non-%NULL #GDestroyNotify function it is called for the 312 * removed element. 313 * 314 * It returns %TRUE if the pointer was removed, or %FALSE if the 315 * pointer was not found. 316 * 317 * Params: 318 * data = the pointer to remove 319 * 320 * Returns: %TRUE if the pointer is removed, %FALSE if the pointer 321 * is not found in the array 322 */ 323 public bool remove(void* data) 324 { 325 return g_ptr_array_remove(gPtrArray, data) != 0; 326 } 327 328 /** 329 * Removes the first occurrence of the given pointer from the pointer 330 * array. The last element in the array is used to fill in the space, 331 * so this function does not preserve the order of the array. But it 332 * is faster than g_ptr_array_remove(). If @array has a non-%NULL 333 * #GDestroyNotify function it is called for the removed element. 334 * 335 * It returns %TRUE if the pointer was removed, or %FALSE if the 336 * pointer was not found. 337 * 338 * Params: 339 * data = the pointer to remove 340 * 341 * Returns: %TRUE if the pointer was found in the array 342 */ 343 public bool removeFast(void* data) 344 { 345 return g_ptr_array_remove_fast(gPtrArray, data) != 0; 346 } 347 348 /** 349 * Removes the pointer at the given index from the pointer array. 350 * The following elements are moved down one place. If @array has 351 * a non-%NULL #GDestroyNotify function it is called for the removed 352 * element. 353 * 354 * Params: 355 * index = the index of the pointer to remove 356 * 357 * Returns: the pointer which was removed 358 */ 359 public void* removeIndex(uint index) 360 { 361 return g_ptr_array_remove_index(gPtrArray, index); 362 } 363 364 /** 365 * Removes the pointer at the given index from the pointer array. 366 * The last element in the array is used to fill in the space, so 367 * this function does not preserve the order of the array. But it 368 * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL 369 * #GDestroyNotify function it is called for the removed element. 370 * 371 * Params: 372 * index = the index of the pointer to remove 373 * 374 * Returns: the pointer which was removed 375 */ 376 public void* removeIndexFast(uint index) 377 { 378 return g_ptr_array_remove_index_fast(gPtrArray, index); 379 } 380 381 /** 382 * Removes the given number of pointers starting at the given index 383 * from a #GPtrArray. The following elements are moved to close the 384 * gap. If @array has a non-%NULL #GDestroyNotify function it is 385 * called for the removed elements. 386 * 387 * Params: 388 * index = the index of the first pointer to remove 389 * length = the number of pointers to remove 390 * 391 * Returns: the @array 392 * 393 * Since: 2.4 394 */ 395 public PtrArray removeRange(uint index, uint length) 396 { 397 auto p = g_ptr_array_remove_range(gPtrArray, index, length); 398 399 if(p is null) 400 { 401 return null; 402 } 403 404 return new PtrArray(cast(GPtrArray*) p); 405 } 406 407 /** 408 * Sets a function for freeing each element when @array is destroyed 409 * either via g_ptr_array_unref(), when g_ptr_array_free() is called 410 * with @free_segment set to %TRUE or when removing elements. 411 * 412 * Params: 413 * elementFreeFunc = A function to free elements with 414 * destroy @array or %NULL 415 * 416 * Since: 2.22 417 */ 418 public void setFreeFunc(GDestroyNotify elementFreeFunc) 419 { 420 g_ptr_array_set_free_func(gPtrArray, elementFreeFunc); 421 } 422 423 /** 424 * Sets the size of the array. When making the array larger, 425 * newly-added elements will be set to %NULL. When making it smaller, 426 * if @array has a non-%NULL #GDestroyNotify function then it will be 427 * called for the removed elements. 428 * 429 * Params: 430 * length = the new length of the pointer array 431 */ 432 public void setSize(int length) 433 { 434 g_ptr_array_set_size(gPtrArray, length); 435 } 436 437 /** 438 * Creates a new #GPtrArray with @reserved_size pointers preallocated 439 * and a reference count of 1. This avoids frequent reallocation, if 440 * you are going to add many pointers to the array. Note however that 441 * the size of the array is still 0. 442 * 443 * Params: 444 * reservedSize = number of pointers preallocated 445 * 446 * Returns: the new #GPtrArray 447 */ 448 public static PtrArray sizedNew(uint reservedSize) 449 { 450 auto p = g_ptr_array_sized_new(reservedSize); 451 452 if(p is null) 453 { 454 return null; 455 } 456 457 return new PtrArray(cast(GPtrArray*) p); 458 } 459 460 /** 461 * Sorts the array, using @compare_func which should be a qsort()-style 462 * comparison function (returns less than zero for first arg is less 463 * than second arg, zero for equal, greater than zero if irst arg is 464 * greater than second arg). 465 * 466 * Note that the comparison function for g_ptr_array_sort() doesn't 467 * take the pointers from the array as arguments, it takes pointers to 468 * the pointers in the array. 469 * 470 * This is guaranteed to be a stable sort since version 2.32. 471 * 472 * Params: 473 * compareFunc = comparison function 474 */ 475 public void sort(GCompareFunc compareFunc) 476 { 477 g_ptr_array_sort(gPtrArray, compareFunc); 478 } 479 480 /** 481 * Like g_ptr_array_sort(), but the comparison function has an extra 482 * user data argument. 483 * 484 * Note that the comparison function for g_ptr_array_sort_with_data() 485 * doesn't take the pointers from the array as arguments, it takes 486 * pointers to the pointers in the array. 487 * 488 * This is guaranteed to be a stable sort since version 2.32. 489 * 490 * Params: 491 * compareFunc = comparison function 492 * userData = data to pass to @compare_func 493 */ 494 public void sortWithData(GCompareDataFunc compareFunc, void* userData) 495 { 496 g_ptr_array_sort_with_data(gPtrArray, compareFunc, userData); 497 } 498 499 /** 500 * Atomically decrements the reference count of @array by one. If the 501 * reference count drops to 0, the effect is the same as calling 502 * g_ptr_array_free() with @free_segment set to %TRUE. This function 503 * is thread-safe and may be called from any thread. 504 * 505 * Since: 2.22 506 */ 507 public void unref() 508 { 509 g_ptr_array_unref(gPtrArray); 510 } 511 }