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