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.ArrayG;
26 
27 private import glib.ConstructionException;
28 private import glib.Str;
29 private import glib.c.functions;
30 public  import glib.c.types;
31 public  import gtkc.glibtypes;
32 
33 
34 /**
35  * Contains the public fields of a GArray.
36  */
37 public class ArrayG
38 {
39 	/** the main Gtk struct */
40 	protected GArray* gArray;
41 	protected bool ownedRef;
42 
43 	/** Get the main Gtk struct */
44 	public GArray* getArrayGStruct(bool transferOwnership = false)
45 	{
46 		if (transferOwnership)
47 			ownedRef = false;
48 		return gArray;
49 	}
50 
51 	/** the main Gtk struct as a void* */
52 	protected void* getStruct()
53 	{
54 		return cast(void*)gArray;
55 	}
56 
57 	/**
58 	 * Sets our main struct and passes it to the parent class.
59 	 */
60 	public this (GArray* gArray, bool ownedRef = false)
61 	{
62 		this.gArray = gArray;
63 		this.ownedRef = ownedRef;
64 	}
65 
66 
67 	/**
68 	 * Adds @len elements onto the end of the array.
69 	 *
70 	 * Params:
71 	 *     data = a pointer to the elements to append to the end of the array
72 	 *     len = the number of elements to append
73 	 *
74 	 * Returns: the #GArray
75 	 */
76 	public ArrayG appendVals(void* data, uint len)
77 	{
78 		auto p = g_array_append_vals(gArray, data, len);
79 
80 		if(p is null)
81 		{
82 			return null;
83 		}
84 
85 		return new ArrayG(cast(GArray*) p);
86 	}
87 
88 	/**
89 	 * Frees the memory allocated for the #GArray. If @free_segment is
90 	 * %TRUE it frees the memory block holding the elements as well and
91 	 * also each element if @array has a @element_free_func set. Pass
92 	 * %FALSE if you want to free the #GArray wrapper but preserve the
93 	 * underlying array for use elsewhere. If the reference count of @array
94 	 * is greater than one, the #GArray wrapper is preserved but the size
95 	 * of @array will be set to zero.
96 	 *
97 	 * If array elements contain dynamically-allocated memory, they should
98 	 * be freed separately.
99 	 *
100 	 * This function is not thread-safe. If using a #GArray from multiple
101 	 * threads, use only the atomic g_array_ref() and g_array_unref()
102 	 * functions.
103 	 *
104 	 * Params:
105 	 *     freeSegment = if %TRUE the actual element data is freed as well
106 	 *
107 	 * Returns: the element data if @free_segment is %FALSE, otherwise
108 	 *     %NULL. The element data should be freed using g_free().
109 	 */
110 	public string free(bool freeSegment)
111 	{
112 		auto retStr = g_array_free(gArray, freeSegment);
113 
114 		scope(exit) Str.freeString(retStr);
115 		return Str.toString(retStr);
116 	}
117 
118 	/**
119 	 * Gets the size of the elements in @array.
120 	 *
121 	 * Returns: Size of each element, in bytes
122 	 *
123 	 * Since: 2.22
124 	 */
125 	public uint getElementSize()
126 	{
127 		return g_array_get_element_size(gArray);
128 	}
129 
130 	/**
131 	 * Inserts @len elements into a #GArray at the given index.
132 	 *
133 	 * Params:
134 	 *     index = the index to place the elements at
135 	 *     data = a pointer to the elements to insert
136 	 *     len = the number of elements to insert
137 	 *
138 	 * Returns: the #GArray
139 	 */
140 	public ArrayG insertVals(uint index, void* data, uint len)
141 	{
142 		auto p = g_array_insert_vals(gArray, index, data, len);
143 
144 		if(p is null)
145 		{
146 			return null;
147 		}
148 
149 		return new ArrayG(cast(GArray*) p);
150 	}
151 
152 	/**
153 	 * Creates a new #GArray with a reference count of 1.
154 	 *
155 	 * Params:
156 	 *     zeroTerminated = %TRUE if the array should have an extra element at
157 	 *         the end which is set to 0
158 	 *     clear = %TRUE if #GArray elements should be automatically cleared
159 	 *         to 0 when they are allocated
160 	 *     elementSize = the size of each element in bytes
161 	 *
162 	 * Returns: the new #GArray
163 	 *
164 	 * Throws: ConstructionException GTK+ fails to create the object.
165 	 */
166 	public this(bool zeroTerminated, bool clear, uint elementSize)
167 	{
168 		auto p = g_array_new(zeroTerminated, clear, elementSize);
169 
170 		if(p is null)
171 		{
172 			throw new ConstructionException("null returned by new");
173 		}
174 
175 		this(cast(GArray*) p);
176 	}
177 
178 	/**
179 	 * Adds @len elements onto the start of the array.
180 	 *
181 	 * This operation is slower than g_array_append_vals() since the
182 	 * existing elements in the array have to be moved to make space for
183 	 * the new elements.
184 	 *
185 	 * Params:
186 	 *     data = a pointer to the elements to prepend to the start of the array
187 	 *     len = the number of elements to prepend
188 	 *
189 	 * Returns: the #GArray
190 	 */
191 	public ArrayG prependVals(void* data, uint len)
192 	{
193 		auto p = g_array_prepend_vals(gArray, data, len);
194 
195 		if(p is null)
196 		{
197 			return null;
198 		}
199 
200 		return new ArrayG(cast(GArray*) p);
201 	}
202 
203 	/**
204 	 * Atomically increments the reference count of @array by one.
205 	 * This function is thread-safe and may be called from any thread.
206 	 *
207 	 * Returns: The passed in #GArray
208 	 *
209 	 * Since: 2.22
210 	 */
211 	public ArrayG doref()
212 	{
213 		auto p = g_array_ref(gArray);
214 
215 		if(p is null)
216 		{
217 			return null;
218 		}
219 
220 		return new ArrayG(cast(GArray*) p);
221 	}
222 
223 	/**
224 	 * Removes the element at the given index from a #GArray. The following
225 	 * elements are moved down one place.
226 	 *
227 	 * Params:
228 	 *     index = the index of the element to remove
229 	 *
230 	 * Returns: the #GArray
231 	 */
232 	public ArrayG removeIndex(uint index)
233 	{
234 		auto p = g_array_remove_index(gArray, index);
235 
236 		if(p is null)
237 		{
238 			return null;
239 		}
240 
241 		return new ArrayG(cast(GArray*) p);
242 	}
243 
244 	/**
245 	 * Removes the element at the given index from a #GArray. The last
246 	 * element in the array is used to fill in the space, so this function
247 	 * does not preserve the order of the #GArray. But it is faster than
248 	 * g_array_remove_index().
249 	 *
250 	 * Params:
251 	 *     index = the index of the element to remove
252 	 *
253 	 * Returns: the #GArray
254 	 */
255 	public ArrayG removeIndexFast(uint index)
256 	{
257 		auto p = g_array_remove_index_fast(gArray, index);
258 
259 		if(p is null)
260 		{
261 			return null;
262 		}
263 
264 		return new ArrayG(cast(GArray*) p);
265 	}
266 
267 	/**
268 	 * Removes the given number of elements starting at the given index
269 	 * from a #GArray.  The following elements are moved to close the gap.
270 	 *
271 	 * Params:
272 	 *     index = the index of the first element to remove
273 	 *     length = the number of elements to remove
274 	 *
275 	 * Returns: the #GArray
276 	 *
277 	 * Since: 2.4
278 	 */
279 	public ArrayG removeRange(uint index, uint length)
280 	{
281 		auto p = g_array_remove_range(gArray, index, length);
282 
283 		if(p is null)
284 		{
285 			return null;
286 		}
287 
288 		return new ArrayG(cast(GArray*) p);
289 	}
290 
291 	/**
292 	 * Sets a function to clear an element of @array.
293 	 *
294 	 * The @clear_func will be called when an element in the array
295 	 * data segment is removed and when the array is freed and data
296 	 * segment is deallocated as well. @clear_func will be passed a
297 	 * pointer to the element to clear, rather than the element itself.
298 	 *
299 	 * Note that in contrast with other uses of #GDestroyNotify
300 	 * functions, @clear_func is expected to clear the contents of
301 	 * the array element it is given, but not free the element itself.
302 	 *
303 	 * Params:
304 	 *     clearFunc = a function to clear an element of @array
305 	 *
306 	 * Since: 2.32
307 	 */
308 	public void setClearFunc(GDestroyNotify clearFunc)
309 	{
310 		g_array_set_clear_func(gArray, clearFunc);
311 	}
312 
313 	/**
314 	 * Sets the size of the array, expanding it if necessary. If the array
315 	 * was created with @clear_ set to %TRUE, the new elements are set to 0.
316 	 *
317 	 * Params:
318 	 *     length = the new size of the #GArray
319 	 *
320 	 * Returns: the #GArray
321 	 */
322 	public ArrayG setSize(uint length)
323 	{
324 		auto p = g_array_set_size(gArray, length);
325 
326 		if(p is null)
327 		{
328 			return null;
329 		}
330 
331 		return new ArrayG(cast(GArray*) p);
332 	}
333 
334 	/**
335 	 * Creates a new #GArray with @reserved_size elements preallocated and
336 	 * a reference count of 1. This avoids frequent reallocation, if you
337 	 * are going to add many elements to the array. Note however that the
338 	 * size of the array is still 0.
339 	 *
340 	 * Params:
341 	 *     zeroTerminated = %TRUE if the array should have an extra element at
342 	 *         the end with all bits cleared
343 	 *     clear = %TRUE if all bits in the array should be cleared to 0 on
344 	 *         allocation
345 	 *     elementSize = size of each element in the array
346 	 *     reservedSize = number of elements preallocated
347 	 *
348 	 * Returns: the new #GArray
349 	 */
350 	public static ArrayG sizedNew(bool zeroTerminated, bool clear, uint elementSize, uint reservedSize)
351 	{
352 		auto p = g_array_sized_new(zeroTerminated, clear, elementSize, reservedSize);
353 
354 		if(p is null)
355 		{
356 			return null;
357 		}
358 
359 		return new ArrayG(cast(GArray*) p);
360 	}
361 
362 	/**
363 	 * Sorts a #GArray using @compare_func which should be a qsort()-style
364 	 * comparison function (returns less than zero for first arg is less
365 	 * than second arg, zero for equal, greater zero if first arg is
366 	 * greater than second arg).
367 	 *
368 	 * This is guaranteed to be a stable sort since version 2.32.
369 	 *
370 	 * Params:
371 	 *     compareFunc = comparison function
372 	 */
373 	public void sort(GCompareFunc compareFunc)
374 	{
375 		g_array_sort(gArray, compareFunc);
376 	}
377 
378 	/**
379 	 * Like g_array_sort(), but the comparison function receives an extra
380 	 * user data argument.
381 	 *
382 	 * This is guaranteed to be a stable sort since version 2.32.
383 	 *
384 	 * There used to be a comment here about making the sort stable by
385 	 * using the addresses of the elements in the comparison function.
386 	 * This did not actually work, so any such code should be removed.
387 	 *
388 	 * Params:
389 	 *     compareFunc = comparison function
390 	 *     userData = data to pass to @compare_func
391 	 */
392 	public void sortWithData(GCompareDataFunc compareFunc, void* userData)
393 	{
394 		g_array_sort_with_data(gArray, compareFunc, userData);
395 	}
396 
397 	/**
398 	 * Atomically decrements the reference count of @array by one. If the
399 	 * reference count drops to 0, all memory allocated by the array is
400 	 * released. This function is thread-safe and may be called from any
401 	 * thread.
402 	 *
403 	 * Since: 2.22
404 	 */
405 	public void unref()
406 	{
407 		g_array_unref(gArray);
408 	}
409 }