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 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 }