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