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