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.BBTree;
26 
27 private import glib.ConstructionException;
28 private import gtkc.glib;
29 public  import gtkc.glibtypes;
30 
31 
32 /**
33  * The GTree struct is an opaque data structure representing a
34  * [balanced binary tree][glib-Balanced-Binary-Trees]. It should be
35  * accessed only by using the following functions.
36  */
37 public class BBTree
38 {
39 	/** the main Gtk struct */
40 	protected GTree* gTree;
41 	protected bool ownedRef;
42 
43 	/** Get the main Gtk struct */
44 	public GTree* getBBTreeStruct()
45 	{
46 		return gTree;
47 	}
48 
49 	/** the main Gtk struct as a void* */
50 	protected void* getStruct()
51 	{
52 		return cast(void*)gTree;
53 	}
54 
55 	/**
56 	 * Sets our main struct and passes it to the parent class.
57 	 */
58 	public this (GTree* gTree, bool ownedRef = false)
59 	{
60 		this.gTree = gTree;
61 		this.ownedRef = ownedRef;
62 	}
63 
64 
65 	/**
66 	 * Removes all keys and values from the #GTree and decreases its
67 	 * reference count by one. If keys and/or values are dynamically
68 	 * allocated, you should either free them first or create the #GTree
69 	 * using g_tree_new_full(). In the latter case the destroy functions
70 	 * you supplied will be called on all keys and values before destroying
71 	 * the #GTree.
72 	 */
73 	public void destroy()
74 	{
75 		g_tree_destroy(gTree);
76 	}
77 
78 	/**
79 	 * Calls the given function for each of the key/value pairs in the #GTree.
80 	 * The function is passed the key and value of each pair, and the given
81 	 * @data parameter. The tree is traversed in sorted order.
82 	 *
83 	 * The tree may not be modified while iterating over it (you can't
84 	 * add/remove items). To remove all items matching a predicate, you need
85 	 * to add each item to a list in your #GTraverseFunc as you walk over
86 	 * the tree, then walk the list and remove each item.
87 	 *
88 	 * Params:
89 	 *     func = the function to call for each node visited.
90 	 *         If this function returns %TRUE, the traversal is stopped.
91 	 *     userData = user data to pass to the function
92 	 */
93 	public void foreac(GTraverseFunc func, void* userData)
94 	{
95 		g_tree_foreach(gTree, func, userData);
96 	}
97 
98 	/**
99 	 * Gets the height of a #GTree.
100 	 *
101 	 * If the #GTree contains no nodes, the height is 0.
102 	 * If the #GTree contains only one root node the height is 1.
103 	 * If the root node has children the height is 2, etc.
104 	 *
105 	 * Return: the height of @tree
106 	 */
107 	public int height()
108 	{
109 		return g_tree_height(gTree);
110 	}
111 
112 	/**
113 	 * Inserts a key/value pair into a #GTree.
114 	 *
115 	 * If the given key already exists in the #GTree its corresponding value
116 	 * is set to the new value. If you supplied a @value_destroy_func when
117 	 * creating the #GTree, the old value is freed using that function. If
118 	 * you supplied a @key_destroy_func when creating the #GTree, the passed
119 	 * key is freed using that function.
120 	 *
121 	 * The tree is automatically 'balanced' as new key/value pairs are added,
122 	 * so that the distance from the root to every leaf is as small as possible.
123 	 *
124 	 * Params:
125 	 *     key = the key to insert
126 	 *     value = the value corresponding to the key
127 	 */
128 	public void insert(void* key, void* value)
129 	{
130 		g_tree_insert(gTree, key, value);
131 	}
132 
133 	/**
134 	 * Gets the value corresponding to the given key. Since a #GTree is
135 	 * automatically balanced as key/value pairs are added, key lookup
136 	 * is O(log n) (where n is the number of key/value pairs in the tree).
137 	 *
138 	 * Params:
139 	 *     key = the key to look up
140 	 *
141 	 * Return: the value corresponding to the key, or %NULL
142 	 *     if the key was not found
143 	 */
144 	public void* lookup(void* key)
145 	{
146 		return g_tree_lookup(gTree, key);
147 	}
148 
149 	/**
150 	 * Looks up a key in the #GTree, returning the original key and the
151 	 * associated value. This is useful if you need to free the memory
152 	 * allocated for the original key, for example before calling
153 	 * g_tree_remove().
154 	 *
155 	 * Params:
156 	 *     lookupKey = the key to look up
157 	 *     origKey = returns the original key
158 	 *     value = returns the value associated with the key
159 	 *
160 	 * Return: %TRUE if the key was found in the #GTree
161 	 */
162 	public bool lookupExtended(void* lookupKey, void** origKey, void** value)
163 	{
164 		return g_tree_lookup_extended(gTree, lookupKey, origKey, value) != 0;
165 	}
166 
167 	/**
168 	 * Gets the number of nodes in a #GTree.
169 	 *
170 	 * Return: the number of nodes in @tree
171 	 */
172 	public int nnodes()
173 	{
174 		return g_tree_nnodes(gTree);
175 	}
176 
177 	/**
178 	 * Increments the reference count of @tree by one.
179 	 *
180 	 * It is safe to call this function from any thread.
181 	 *
182 	 * Return: the passed in #GTree
183 	 *
184 	 * Since: 2.22
185 	 */
186 	public BBTree doref()
187 	{
188 		auto p = g_tree_ref(gTree);
189 		
190 		if(p is null)
191 		{
192 			return null;
193 		}
194 		
195 		return new BBTree(cast(GTree*) p);
196 	}
197 
198 	/**
199 	 * Removes a key/value pair from a #GTree.
200 	 *
201 	 * If the #GTree was created using g_tree_new_full(), the key and value
202 	 * are freed using the supplied destroy functions, otherwise you have to
203 	 * make sure that any dynamically allocated values are freed yourself.
204 	 * If the key does not exist in the #GTree, the function does nothing.
205 	 *
206 	 * Params:
207 	 *     key = the key to remove
208 	 *
209 	 * Return: %TRUE if the key was found (prior to 2.8, this function
210 	 *     returned nothing)
211 	 */
212 	public bool remove(void* key)
213 	{
214 		return g_tree_remove(gTree, key) != 0;
215 	}
216 
217 	/**
218 	 * Inserts a new key and value into a #GTree similar to g_tree_insert().
219 	 * The difference is that if the key already exists in the #GTree, it gets
220 	 * replaced by the new key. If you supplied a @value_destroy_func when
221 	 * creating the #GTree, the old value is freed using that function. If you
222 	 * supplied a @key_destroy_func when creating the #GTree, the old key is
223 	 * freed using that function.
224 	 *
225 	 * The tree is automatically 'balanced' as new key/value pairs are added,
226 	 * so that the distance from the root to every leaf is as small as possible.
227 	 *
228 	 * Params:
229 	 *     key = the key to insert
230 	 *     value = the value corresponding to the key
231 	 */
232 	public void replace(void* key, void* value)
233 	{
234 		g_tree_replace(gTree, key, value);
235 	}
236 
237 	/**
238 	 * Searches a #GTree using @search_func.
239 	 *
240 	 * The @search_func is called with a pointer to the key of a key/value
241 	 * pair in the tree, and the passed in @user_data. If @search_func returns
242 	 * 0 for a key/value pair, then the corresponding value is returned as
243 	 * the result of g_tree_search(). If @search_func returns -1, searching
244 	 * will proceed among the key/value pairs that have a smaller key; if
245 	 * @search_func returns 1, searching will proceed among the key/value
246 	 * pairs that have a larger key.
247 	 *
248 	 * Params:
249 	 *     searchFunc = a function used to search the #GTree
250 	 *     userData = the data passed as the second argument to @search_func
251 	 *
252 	 * Return: the value corresponding to the found key, or %NULL
253 	 *     if the key was not found
254 	 */
255 	public void* search(GCompareFunc searchFunc, void* userData)
256 	{
257 		return g_tree_search(gTree, searchFunc, userData);
258 	}
259 
260 	/**
261 	 * Removes a key and its associated value from a #GTree without calling
262 	 * the key and value destroy functions.
263 	 *
264 	 * If the key does not exist in the #GTree, the function does nothing.
265 	 *
266 	 * Params:
267 	 *     key = the key to remove
268 	 *
269 	 * Return: %TRUE if the key was found (prior to 2.8, this function
270 	 *     returned nothing)
271 	 */
272 	public bool steal(void* key)
273 	{
274 		return g_tree_steal(gTree, key) != 0;
275 	}
276 
277 	/**
278 	 * Calls the given function for each node in the #GTree.
279 	 *
280 	 * Deprecated: The order of a balanced tree is somewhat arbitrary.
281 	 * If you just want to visit all nodes in sorted order, use
282 	 * g_tree_foreach() instead. If you really need to visit nodes in
283 	 * a different order, consider using an [n-ary tree][glib-N-ary-Trees].
284 	 *
285 	 * Params:
286 	 *     traverseFunc = the function to call for each node visited. If this
287 	 *         function returns %TRUE, the traversal is stopped.
288 	 *     traverseType = the order in which nodes are visited, one of %G_IN_ORDER,
289 	 *         %G_PRE_ORDER and %G_POST_ORDER
290 	 *     userData = user data to pass to the function
291 	 */
292 	public void traverse(GTraverseFunc traverseFunc, GTraverseType traverseType, void* userData)
293 	{
294 		g_tree_traverse(gTree, traverseFunc, traverseType, userData);
295 	}
296 
297 	/**
298 	 * Decrements the reference count of @tree by one.
299 	 * If the reference count drops to 0, all keys and values will
300 	 * be destroyed (if destroy functions were specified) and all
301 	 * memory allocated by @tree will be released.
302 	 *
303 	 * It is safe to call this function from any thread.
304 	 *
305 	 * Since: 2.22
306 	 */
307 	public void unref()
308 	{
309 		g_tree_unref(gTree);
310 	}
311 
312 	/**
313 	 * Creates a new #GTree.
314 	 *
315 	 * Params:
316 	 *     keyCompareFunc = the function used to order the nodes in the #GTree.
317 	 *         It should return values similar to the standard strcmp() function -
318 	 *         0 if the two arguments are equal, a negative value if the first argument
319 	 *         comes before the second, or a positive value if the first argument comes
320 	 *         after the second.
321 	 *
322 	 * Return: a newly allocated #GTree
323 	 *
324 	 * Throws: ConstructionException GTK+ fails to create the object.
325 	 */
326 	public this(GCompareFunc keyCompareFunc)
327 	{
328 		auto p = g_tree_new(keyCompareFunc);
329 		
330 		if(p is null)
331 		{
332 			throw new ConstructionException("null returned by new");
333 		}
334 		
335 		this(cast(GTree*) p);
336 	}
337 
338 	/**
339 	 * Creates a new #GTree like g_tree_new() and allows to specify functions
340 	 * to free the memory allocated for the key and value that get called when
341 	 * removing the entry from the #GTree.
342 	 *
343 	 * Params:
344 	 *     keyCompareFunc = qsort()-style comparison function
345 	 *     keyCompareData = data to pass to comparison function
346 	 *     keyDestroyFunc = a function to free the memory allocated for the key
347 	 *         used when removing the entry from the #GTree or %NULL if you don't
348 	 *         want to supply such a function
349 	 *     valueDestroyFunc = a function to free the memory allocated for the
350 	 *         value used when removing the entry from the #GTree or %NULL if you
351 	 *         don't want to supply such a function
352 	 *
353 	 * Return: a newly allocated #GTree
354 	 *
355 	 * Throws: ConstructionException GTK+ fails to create the object.
356 	 */
357 	public this(GCompareDataFunc keyCompareFunc, void* keyCompareData, GDestroyNotify keyDestroyFunc, GDestroyNotify valueDestroyFunc)
358 	{
359 		auto p = g_tree_new_full(keyCompareFunc, keyCompareData, keyDestroyFunc, valueDestroyFunc);
360 		
361 		if(p is null)
362 		{
363 			throw new ConstructionException("null returned by new_full");
364 		}
365 		
366 		this(cast(GTree*) p);
367 	}
368 
369 	/**
370 	 * Creates a new #GTree with a comparison function that accepts user data.
371 	 * See g_tree_new() for more details.
372 	 *
373 	 * Params:
374 	 *     keyCompareFunc = qsort()-style comparison function
375 	 *     keyCompareData = data to pass to comparison function
376 	 *
377 	 * Return: a newly allocated #GTree
378 	 *
379 	 * Throws: ConstructionException GTK+ fails to create the object.
380 	 */
381 	public this(GCompareDataFunc keyCompareFunc, void* keyCompareData)
382 	{
383 		auto p = g_tree_new_with_data(keyCompareFunc, keyCompareData);
384 		
385 		if(p is null)
386 		{
387 			throw new ConstructionException("null returned by new_with_data");
388 		}
389 		
390 		this(cast(GTree*) p);
391 	}
392 }