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