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