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 gtkc.glib; 29 public import gtkc.glibtypes; 30 31 32 /** 33 * Contains the public fields of a pointer array. 34 */ 35 public class PtrArray 36 { 37 /** the main Gtk struct */ 38 protected GPtrArray* gPtrArray; 39 protected bool ownedRef; 40 41 /** Get the main Gtk struct */ 42 public GPtrArray* getPtrArrayStruct(bool transferOwnership = false) 43 { 44 if (transferOwnership) 45 ownedRef = false; 46 return gPtrArray; 47 } 48 49 /** the main Gtk struct as a void* */ 50 protected void* getStruct() 51 { 52 return cast(void*)gPtrArray; 53 } 54 55 /** 56 * Sets our main struct and passes it to the parent class. 57 */ 58 public this (GPtrArray* gPtrArray, bool ownedRef = false) 59 { 60 this.gPtrArray = gPtrArray; 61 this.ownedRef = ownedRef; 62 } 63 64 65 /** 66 * Adds a pointer to the end of the pointer array. The array will grow 67 * in size automatically if necessary. 68 * 69 * Params: 70 * data = the pointer to add 71 */ 72 public void add(void* data) 73 { 74 g_ptr_array_add(gPtrArray, data); 75 } 76 77 /** 78 * Calls a function for each element of a #GPtrArray. 79 * 80 * Params: 81 * func = the function to call for each array element 82 * userData = user data to pass to the function 83 * 84 * Since: 2.4 85 */ 86 public void foreac(GFunc func, void* userData) 87 { 88 g_ptr_array_foreach(gPtrArray, func, userData); 89 } 90 91 /** 92 * Frees the memory allocated for the #GPtrArray. If @free_seg is %TRUE 93 * it frees the memory block holding the elements as well. Pass %FALSE 94 * if you want to free the #GPtrArray wrapper but preserve the 95 * underlying array for use elsewhere. If the reference count of @array 96 * is greater than one, the #GPtrArray wrapper is preserved but the 97 * size of @array will be set to zero. 98 * 99 * If array contents point to dynamically-allocated memory, they should 100 * be freed separately if @free_seg is %TRUE and no #GDestroyNotify 101 * function has been set for @array. 102 * 103 * Params: 104 * freeSeg = if %TRUE the actual pointer array is freed as well 105 * 106 * Returns: the pointer array if @free_seg is %FALSE, otherwise %NULL. 107 * The pointer array should be freed using g_free(). 108 */ 109 public void** free(bool freeSeg) 110 { 111 return g_ptr_array_free(gPtrArray, freeSeg); 112 } 113 114 /** 115 * Inserts an element into the pointer array at the given index. The 116 * array will grow in size automatically if necessary. 117 * 118 * Params: 119 * index = the index to place the new element at, or -1 to append 120 * data = the pointer to add. 121 * 122 * Since: 2.40 123 */ 124 public void insert(int index, void* data) 125 { 126 g_ptr_array_insert(gPtrArray, index, data); 127 } 128 129 /** 130 * Creates a new #GPtrArray with a reference count of 1. 131 * 132 * Returns: the new #GPtrArray 133 * 134 * Throws: ConstructionException GTK+ fails to create the object. 135 */ 136 public this() 137 { 138 auto p = g_ptr_array_new(); 139 140 if(p is null) 141 { 142 throw new ConstructionException("null returned by new"); 143 } 144 145 this(cast(GPtrArray*) p); 146 } 147 148 /** 149 * Creates a new #GPtrArray with @reserved_size pointers preallocated 150 * and a reference count of 1. This avoids frequent reallocation, if 151 * you are going to add many pointers to the array. Note however that 152 * the size of the array is still 0. It also set @element_free_func 153 * for freeing each element when the array is destroyed either via 154 * g_ptr_array_unref(), when g_ptr_array_free() is called with 155 * @free_segment set to %TRUE or when removing elements. 156 * 157 * Params: 158 * reservedSize = number of pointers preallocated 159 * elementFreeFunc = A function to free elements with 160 * destroy @array or %NULL 161 * 162 * Returns: A new #GPtrArray 163 * 164 * Since: 2.30 165 * 166 * Throws: ConstructionException GTK+ fails to create the object. 167 */ 168 public this(uint reservedSize, GDestroyNotify elementFreeFunc) 169 { 170 auto p = g_ptr_array_new_full(reservedSize, elementFreeFunc); 171 172 if(p is null) 173 { 174 throw new ConstructionException("null returned by new_full"); 175 } 176 177 this(cast(GPtrArray*) p); 178 } 179 180 /** 181 * Creates a new #GPtrArray with a reference count of 1 and use 182 * @element_free_func for freeing each element when the array is destroyed 183 * either via g_ptr_array_unref(), when g_ptr_array_free() is called with 184 * @free_segment set to %TRUE or when removing elements. 185 * 186 * Params: 187 * elementFreeFunc = A function to free elements with 188 * destroy @array or %NULL 189 * 190 * Returns: A new #GPtrArray 191 * 192 * Since: 2.22 193 * 194 * Throws: ConstructionException GTK+ fails to create the object. 195 */ 196 public this(GDestroyNotify elementFreeFunc) 197 { 198 auto p = g_ptr_array_new_with_free_func(elementFreeFunc); 199 200 if(p is null) 201 { 202 throw new ConstructionException("null returned by new_with_free_func"); 203 } 204 205 this(cast(GPtrArray*) p); 206 } 207 208 /** 209 * Atomically increments the reference count of @array by one. 210 * This function is thread-safe and may be called from any thread. 211 * 212 * Returns: The passed in #GPtrArray 213 * 214 * Since: 2.22 215 */ 216 public PtrArray doref() 217 { 218 auto p = g_ptr_array_ref(gPtrArray); 219 220 if(p is null) 221 { 222 return null; 223 } 224 225 return new PtrArray(cast(GPtrArray*) p); 226 } 227 228 /** 229 * Removes the first occurrence of the given pointer from the pointer 230 * array. The following elements are moved down one place. If @array 231 * has a non-%NULL #GDestroyNotify function it is called for the 232 * removed element. 233 * 234 * It returns %TRUE if the pointer was removed, or %FALSE if the 235 * pointer was not found. 236 * 237 * Params: 238 * data = the pointer to remove 239 * 240 * Returns: %TRUE if the pointer is removed, %FALSE if the pointer 241 * is not found in the array 242 */ 243 public bool remove(void* data) 244 { 245 return g_ptr_array_remove(gPtrArray, data) != 0; 246 } 247 248 /** 249 * Removes the first occurrence of the given pointer from the pointer 250 * array. The last element in the array is used to fill in the space, 251 * so this function does not preserve the order of the array. But it 252 * is faster than g_ptr_array_remove(). If @array has a non-%NULL 253 * #GDestroyNotify function it is called for the removed element. 254 * 255 * It returns %TRUE if the pointer was removed, or %FALSE if the 256 * pointer was not found. 257 * 258 * Params: 259 * data = the pointer to remove 260 * 261 * Returns: %TRUE if the pointer was found in the array 262 */ 263 public bool removeFast(void* data) 264 { 265 return g_ptr_array_remove_fast(gPtrArray, data) != 0; 266 } 267 268 /** 269 * Removes the pointer at the given index from the pointer array. 270 * The following elements are moved down one place. If @array has 271 * a non-%NULL #GDestroyNotify function it is called for the removed 272 * element. 273 * 274 * Params: 275 * index = the index of the pointer to remove 276 * 277 * Returns: the pointer which was removed 278 */ 279 public void* removeIndex(uint index) 280 { 281 return g_ptr_array_remove_index(gPtrArray, index); 282 } 283 284 /** 285 * Removes the pointer at the given index from the pointer array. 286 * The last element in the array is used to fill in the space, so 287 * this function does not preserve the order of the array. But it 288 * is faster than g_ptr_array_remove_index(). If @array has a non-%NULL 289 * #GDestroyNotify function it is called for the removed element. 290 * 291 * Params: 292 * index = the index of the pointer to remove 293 * 294 * Returns: the pointer which was removed 295 */ 296 public void* removeIndexFast(uint index) 297 { 298 return g_ptr_array_remove_index_fast(gPtrArray, index); 299 } 300 301 /** 302 * Removes the given number of pointers starting at the given index 303 * from a #GPtrArray. The following elements are moved to close the 304 * gap. If @array has a non-%NULL #GDestroyNotify function it is 305 * called for the removed elements. 306 * 307 * Params: 308 * index = the index of the first pointer to remove 309 * length = the number of pointers to remove 310 * 311 * Returns: the @array 312 * 313 * Since: 2.4 314 */ 315 public PtrArray removeRange(uint index, uint length) 316 { 317 auto p = g_ptr_array_remove_range(gPtrArray, index, length); 318 319 if(p is null) 320 { 321 return null; 322 } 323 324 return new PtrArray(cast(GPtrArray*) p); 325 } 326 327 /** 328 * Sets a function for freeing each element when @array is destroyed 329 * either via g_ptr_array_unref(), when g_ptr_array_free() is called 330 * with @free_segment set to %TRUE or when removing elements. 331 * 332 * Params: 333 * elementFreeFunc = A function to free elements with 334 * destroy @array or %NULL 335 * 336 * Since: 2.22 337 */ 338 public void setFreeFunc(GDestroyNotify elementFreeFunc) 339 { 340 g_ptr_array_set_free_func(gPtrArray, elementFreeFunc); 341 } 342 343 /** 344 * Sets the size of the array. When making the array larger, 345 * newly-added elements will be set to %NULL. When making it smaller, 346 * if @array has a non-%NULL #GDestroyNotify function then it will be 347 * called for the removed elements. 348 * 349 * Params: 350 * length = the new length of the pointer array 351 */ 352 public void setSize(int length) 353 { 354 g_ptr_array_set_size(gPtrArray, length); 355 } 356 357 /** 358 * Creates a new #GPtrArray with @reserved_size pointers preallocated 359 * and a reference count of 1. This avoids frequent reallocation, if 360 * you are going to add many pointers to the array. Note however that 361 * the size of the array is still 0. 362 * 363 * Params: 364 * reservedSize = number of pointers preallocated 365 * 366 * Returns: the new #GPtrArray 367 */ 368 public static PtrArray sizedNew(uint reservedSize) 369 { 370 auto p = g_ptr_array_sized_new(reservedSize); 371 372 if(p is null) 373 { 374 return null; 375 } 376 377 return new PtrArray(cast(GPtrArray*) p); 378 } 379 380 /** 381 * Sorts the array, using @compare_func which should be a qsort()-style 382 * comparison function (returns less than zero for first arg is less 383 * than second arg, zero for equal, greater than zero if irst arg is 384 * greater than second arg). 385 * 386 * Note that the comparison function for g_ptr_array_sort() doesn't 387 * take the pointers from the array as arguments, it takes pointers to 388 * the pointers in the array. 389 * 390 * This is guaranteed to be a stable sort since version 2.32. 391 * 392 * Params: 393 * compareFunc = comparison function 394 */ 395 public void sort(GCompareFunc compareFunc) 396 { 397 g_ptr_array_sort(gPtrArray, compareFunc); 398 } 399 400 /** 401 * Like g_ptr_array_sort(), but the comparison function has an extra 402 * user data argument. 403 * 404 * Note that the comparison function for g_ptr_array_sort_with_data() 405 * doesn't take the pointers from the array as arguments, it takes 406 * pointers to the pointers in the array. 407 * 408 * This is guaranteed to be a stable sort since version 2.32. 409 * 410 * Params: 411 * compareFunc = comparison function 412 * userData = data to pass to @compare_func 413 */ 414 public void sortWithData(GCompareDataFunc compareFunc, void* userData) 415 { 416 g_ptr_array_sort_with_data(gPtrArray, compareFunc, userData); 417 } 418 419 /** 420 * Atomically decrements the reference count of @array by one. If the 421 * reference count drops to 0, the effect is the same as calling 422 * g_ptr_array_free() with @free_segment set to %TRUE. This function 423 * is MT-safe and may be called from any thread. 424 * 425 * Since: 2.22 426 */ 427 public void unref() 428 { 429 g_ptr_array_unref(gPtrArray); 430 } 431 }