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