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 /** 151 * Calls a function for each element of a #GPtrArray. @func must not 152 * add elements to or remove elements from the array. 153 * 154 * Params: 155 * func = the function to call for each array element 156 * userData = user data to pass to the function 157 * 158 * Since: 2.4 159 */ 160 public void foreac(GFunc func, void* userData) 161 { 162 g_ptr_array_foreach(gPtrArray, func, userData); 163 } 164 165 /** 166 * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE 167 * it frees the memory block holding the elements as well. Pass %FALSE 168 * if you want to free the #GPtrArray wrapper but preserve the 169 * underlying array for use elsewhere. If the reference count of @array 170 * is greater than one, the #GPtrArray wrapper is preserved but the 171 * size of @array will be set to zero. 172 * 173 * If array contents point to dynamically-allocated memory, they should 174 * be freed separately if @free_seg is %TRUE and no #GDestroyNotify 175 * function has been set for @array. 176 * 177 * This function is not thread-safe. If using a #GPtrArray from multiple 178 * threads, use only the atomic g_ptr_array_ref() and g_ptr_array_unref() 179 * functions. 180 * 181 * Params: 182 * freeSeg = if %TRUE the actual pointer array is freed as well 183 * 184 * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. 185 * The pointer array should be freed using g_free(). 186 */ 187 public void** free(bool freeSeg) 188 { 189 return g_ptr_array_free(gPtrArray, freeSeg); 190 } 191 192 /** 193 * Inserts an element into the pointer array at the given index. The 194 * array will grow in size automatically if necessary. 195 * 196 * Params: 197 * index = the index to place the new element at, or -1 to append 198 * data = the pointer to add. 199 * 200 * Since: 2.40 201 */ 202 public void insert(int index, void* data) 203 { 204 g_ptr_array_insert(gPtrArray, index, data); 205 } 206 207 /** 208 * Creates a new #GPtrArray with a reference count of 1. 209 * 210 * Returns: the new #GPtrArray 211 * 212 * Throws: ConstructionException GTK+ fails to create the object. 213 */ 214 public this() 215 { 216 auto p = g_ptr_array_new(); 217 218 if(p is null) 219 { 220 throw new ConstructionException("null returned by new"); 221 } 222 223 this(cast(GPtrArray*) p); 224 } 225 226 /** 227 * Creates a new #GPtrArray with @reserved_size pointers preallocated 228 * and a reference count of 1. This avoids frequent reallocation, if 229 * you are going to add many pointers to the array. Note however that 230 * the size of the array is still 0. It also set @element_free_func 231 * for freeing each element when the array is destroyed either via 232 * g_ptr_array_unref(), when g_ptr_array_free() is called with 233 * @free_segment set to %TRUE or when removing elements. 234 * 235 * Params: 236 * reservedSize = number of pointers preallocated 237 * elementFreeFunc = A function to free elements with 238 * destroy @array or %NULL 239 * 240 * Returns: A new #GPtrArray 241 * 242 * Since: 2.30 243 * 244 * Throws: ConstructionException GTK+ fails to create the object. 245 */ 246 public this(uint reservedSize, GDestroyNotify elementFreeFunc) 247 { 248 auto p = g_ptr_array_new_full(reservedSize, elementFreeFunc); 249 250 if(p is null) 251 { 252 throw new ConstructionException("null returned by new_full"); 253 } 254 255 this(cast(GPtrArray*) p); 256 } 257 258 /** 259 * Creates a new #GPtrArray with a reference count of 1 and use 260 * @element_free_func for freeing each element when the array is destroyed 261 * either via g_ptr_array_unref(), when g_ptr_array_free() is called with 262 * @free_segment set to %TRUE or when removing elements. 263 * 264 * Params: 265 * elementFreeFunc = A function to free elements with 266 * destroy @array or %NULL 267 * 268 * Returns: A new #GPtrArray 269 * 270 * Since: 2.22 271 * 272 * Throws: ConstructionException GTK+ fails to create the object. 273 */ 274 public this(GDestroyNotify elementFreeFunc) 275 { 276 auto p = g_ptr_array_new_with_free_func(elementFreeFunc); 277 278 if(p is null) 279 { 280 throw new ConstructionException("null returned by new_with_free_func"); 281 } 282 283 this(cast(GPtrArray*) p); 284 } 285 286 /** 287 * Atomically increments the reference count of @array by one. 288 * This function is thread-safe and may be called from any thread. 289 * 290 * Returns: The passed in #GPtrArray 291 * 292 * Since: 2.22 293 */ 294 public PtrArray doref() 295 { 296 auto p = g_ptr_array_ref(gPtrArray); 297 298 if(p is null) 299 { 300 return null; 301 } 302 303 return new PtrArray(cast(GPtrArray*) p); 304 } 305 306 /** 307 * Removes the first occurrence of the given pointer from the pointer 308 * array. The following elements are moved down one place. If @array 309 * has a non-%NULL #GDestroyNotify function it is called for the 310 * removed element. 311 * 312 * It returns %TRUE if the pointer was removed, or %FALSE if the 313 * pointer was not found. 314 * 315 * Params: 316 * data = the pointer to remove 317 * 318 * Returns: %TRUE if the pointer is removed, %FALSE if the pointer 319 * is not found in the array 320 */ 321 public bool remove(void* data) 322 { 323 return g_ptr_array_remove(gPtrArray, data) != 0; 324 } 325 326 /** 327 * Removes the first occurrence of the given pointer from the pointer 328 * array. The last element in the array is used to fill in the space, 329 * so this function does not preserve the order of the array. But it 330 * is faster than g_ptr_array_remove(). If @array has a non-%NULL 331 * #GDestroyNotify function it is called for the removed element. 332 * 333 * It returns %TRUE if the pointer was removed, or %FALSE if the 334 * pointer was not found. 335 * 336 * Params: 337 * data = the pointer to remove 338 * 339 * Returns: %TRUE if the pointer was found in the array 340 */ 341 public bool removeFast(void* data) 342 { 343 return g_ptr_array_remove_fast(gPtrArray, data) != 0; 344 } 345 346 /** 347 * Removes the pointer at the given index from the pointer array. 348 * The following elements are moved down one place. If @array has 349 * a non-%NULL #GDestroyNotify function it is called for the removed 350 * element. 351 * 352 * Params: 353 * index = the index of the pointer to remove 354 * 355 * Returns: the pointer which was removed 356 */ 357 public void* removeIndex(uint index) 358 { 359 return g_ptr_array_remove_index(gPtrArray, index); 360 } 361 362 /** 363 * Removes the pointer at the given index from the pointer array. 364 * The last element in the array is used to fill in the space, so 365 * this function does not preserve the order of the array. But it 366 * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL 367 * #GDestroyNotify function it is called for the removed element. 368 * 369 * Params: 370 * index = the index of the pointer to remove 371 * 372 * Returns: the pointer which was removed 373 */ 374 public void* removeIndexFast(uint index) 375 { 376 return g_ptr_array_remove_index_fast(gPtrArray, index); 377 } 378 379 /** 380 * Removes the given number of pointers starting at the given index 381 * from a #GPtrArray. The following elements are moved to close the 382 * gap. If @array has a non-%NULL #GDestroyNotify function it is 383 * called for the removed elements. 384 * 385 * Params: 386 * index = the index of the first pointer to remove 387 * length = the number of pointers to remove 388 * 389 * Returns: the @array 390 * 391 * Since: 2.4 392 */ 393 public PtrArray removeRange(uint index, uint length) 394 { 395 auto p = g_ptr_array_remove_range(gPtrArray, index, length); 396 397 if(p is null) 398 { 399 return null; 400 } 401 402 return new PtrArray(cast(GPtrArray*) p); 403 } 404 405 /** 406 * Sets a function for freeing each element when @array is destroyed 407 * either via g_ptr_array_unref(), when g_ptr_array_free() is called 408 * with @free_segment set to %TRUE or when removing elements. 409 * 410 * Params: 411 * elementFreeFunc = A function to free elements with 412 * destroy @array or %NULL 413 * 414 * Since: 2.22 415 */ 416 public void setFreeFunc(GDestroyNotify elementFreeFunc) 417 { 418 g_ptr_array_set_free_func(gPtrArray, elementFreeFunc); 419 } 420 421 /** 422 * Sets the size of the array. When making the array larger, 423 * newly-added elements will be set to %NULL. When making it smaller, 424 * if @array has a non-%NULL #GDestroyNotify function then it will be 425 * called for the removed elements. 426 * 427 * Params: 428 * length = the new length of the pointer array 429 */ 430 public void setSize(int length) 431 { 432 g_ptr_array_set_size(gPtrArray, length); 433 } 434 435 /** 436 * Creates a new #GPtrArray with @reserved_size pointers preallocated 437 * and a reference count of 1. This avoids frequent reallocation, if 438 * you are going to add many pointers to the array. Note however that 439 * the size of the array is still 0. 440 * 441 * Params: 442 * reservedSize = number of pointers preallocated 443 * 444 * Returns: the new #GPtrArray 445 */ 446 public static PtrArray sizedNew(uint reservedSize) 447 { 448 auto p = g_ptr_array_sized_new(reservedSize); 449 450 if(p is null) 451 { 452 return null; 453 } 454 455 return new PtrArray(cast(GPtrArray*) p); 456 } 457 458 /** 459 * Sorts the array, using @compare_func which should be a qsort()-style 460 * comparison function (returns less than zero for first arg is less 461 * than second arg, zero for equal, greater than zero if irst arg is 462 * greater than second arg). 463 * 464 * Note that the comparison function for g_ptr_array_sort() doesn't 465 * take the pointers from the array as arguments, it takes pointers to 466 * the pointers in the array. 467 * 468 * This is guaranteed to be a stable sort since version 2.32. 469 * 470 * Params: 471 * compareFunc = comparison function 472 */ 473 public void sort(GCompareFunc compareFunc) 474 { 475 g_ptr_array_sort(gPtrArray, compareFunc); 476 } 477 478 /** 479 * Like g_ptr_array_sort(), but the comparison function has an extra 480 * user data argument. 481 * 482 * Note that the comparison function for g_ptr_array_sort_with_data() 483 * doesn't take the pointers from the array as arguments, it takes 484 * pointers to the pointers in the array. 485 * 486 * This is guaranteed to be a stable sort since version 2.32. 487 * 488 * Params: 489 * compareFunc = comparison function 490 * userData = data to pass to @compare_func 491 */ 492 public void sortWithData(GCompareDataFunc compareFunc, void* userData) 493 { 494 g_ptr_array_sort_with_data(gPtrArray, compareFunc, userData); 495 } 496 497 /** 498 * Atomically decrements the reference count of @array by one. If the 499 * reference count drops to 0, the effect is the same as calling 500 * g_ptr_array_free() with @free_segment set to %TRUE. This function 501 * is thread-safe and may be called from any thread. 502 * 503 * Since: 2.22 504 */ 505 public void unref() 506 { 507 g_ptr_array_unref(gPtrArray); 508 } 509 }