source: appstream-generator/build/girepo/glib/HashTable.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 22.3 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module glib.HashTable;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.ListG;
27
28
29/**
30 * The #GHashTable struct is an opaque data structure to represent a
31 * [Hash Table][glib-Hash-Tables]. It should only be accessed via the
32 * following functions.
33 */
34public class HashTable
35{
36        /** the main Gtk struct */
37        protected GHashTable* gHashTable;
38        protected bool ownedRef;
39
40        /** Get the main Gtk struct */
41        public GHashTable* getHashTableStruct()
42        {
43                return gHashTable;
44        }
45
46        /** the main Gtk struct as a void* */
47        protected void* getStruct()
48        {
49                return cast(void*)gHashTable;
50        }
51
52        /**
53         * Sets our main struct and passes it to the parent class.
54         */
55        public this (GHashTable* gHashTable, bool ownedRef = false)
56        {
57                this.gHashTable = gHashTable;
58                this.ownedRef = ownedRef;
59        }
60
61
62        /**
63         * This is a convenience function for using a #GHashTable as a set.  It
64         * is equivalent to calling g_hash_table_replace() with @key as both the
65         * key and the value.
66         *
67         * When a hash table only ever contains keys that have themselves as the
68         * corresponding value it is able to be stored more efficiently.  See
69         * the discussion in the section description.
70         *
71         * Params:
72         *     key = a key to insert
73         *
74         * Returns: %TRUE if the key did not exist yet
75         *
76         * Since: 2.32
77         */
78        public bool add(void* key)
79        {
80                return g_hash_table_add(gHashTable, key) != 0;
81        }
82
83        /**
84         * Checks if @key is in @hash_table.
85         *
86         * Params:
87         *     key = a key to check
88         *
89         * Returns: %TRUE if @key is in @hash_table, %FALSE otherwise.
90         *
91         * Since: 2.32
92         */
93        public bool contains(void* key)
94        {
95                return g_hash_table_contains(gHashTable, key) != 0;
96        }
97
98        /**
99         * Destroys all keys and values in the #GHashTable and decrements its
100         * reference count by 1. If keys and/or values are dynamically allocated,
101         * you should either free them first or create the #GHashTable with destroy
102         * notifiers using g_hash_table_new_full(). In the latter case the destroy
103         * functions you supplied will be called on all keys and values during the
104         * destruction phase.
105         */
106        public void destroy()
107        {
108                g_hash_table_destroy(gHashTable);
109        }
110
111        /**
112         * Calls the given function for key/value pairs in the #GHashTable
113         * until @predicate returns %TRUE. The function is passed the key
114         * and value of each pair, and the given @user_data parameter. The
115         * hash table may not be modified while iterating over it (you can't
116         * add/remove items).
117         *
118         * Note, that hash tables are really only optimized for forward
119         * lookups, i.e. g_hash_table_lookup(). So code that frequently issues
120         * g_hash_table_find() or g_hash_table_foreach() (e.g. in the order of
121         * once per every entry in a hash table) should probably be reworked
122         * to use additional or different data structures for reverse lookups
123         * (keep in mind that an O(n) find/foreach operation issued for all n
124         * values in a hash table ends up needing O(n*n) operations).
125         *
126         * Params:
127         *     predicate = function to test the key/value pairs for a certain property
128         *     userData = user data to pass to the function
129         *
130         * Returns: The value of the first key/value pair is returned,
131         *     for which @predicate evaluates to %TRUE. If no pair with the
132         *     requested property is found, %NULL is returned.
133         *
134         * Since: 2.4
135         */
136        public void* find(GHRFunc predicate, void* userData)
137        {
138                return g_hash_table_find(gHashTable, predicate, userData);
139        }
140
141        /**
142         * Calls the given function for each of the key/value pairs in the
143         * #GHashTable.  The function is passed the key and value of each
144         * pair, and the given @user_data parameter.  The hash table may not
145         * be modified while iterating over it (you can't add/remove
146         * items). To remove all items matching a predicate, use
147         * g_hash_table_foreach_remove().
148         *
149         * See g_hash_table_find() for performance caveats for linear
150         * order searches in contrast to g_hash_table_lookup().
151         *
152         * Params:
153         *     func = the function to call for each key/value pair
154         *     userData = user data to pass to the function
155         */
156        public void foreac(GHFunc func, void* userData)
157        {
158                g_hash_table_foreach(gHashTable, func, userData);
159        }
160
161        /**
162         * Calls the given function for each key/value pair in the
163         * #GHashTable. If the function returns %TRUE, then the key/value
164         * pair is removed from the #GHashTable. If you supplied key or
165         * value destroy functions when creating the #GHashTable, they are
166         * used to free the memory allocated for the removed keys and values.
167         *
168         * See #GHashTableIter for an alternative way to loop over the
169         * key/value pairs in the hash table.
170         *
171         * Params:
172         *     func = the function to call for each key/value pair
173         *     userData = user data to pass to the function
174         *
175         * Returns: the number of key/value pairs removed
176         */
177        public uint foreachRemove(GHRFunc func, void* userData)
178        {
179                return g_hash_table_foreach_remove(gHashTable, func, userData);
180        }
181
182        /**
183         * Calls the given function for each key/value pair in the
184         * #GHashTable. If the function returns %TRUE, then the key/value
185         * pair is removed from the #GHashTable, but no key or value
186         * destroy functions are called.
187         *
188         * See #GHashTableIter for an alternative way to loop over the
189         * key/value pairs in the hash table.
190         *
191         * Params:
192         *     func = the function to call for each key/value pair
193         *     userData = user data to pass to the function
194         *
195         * Returns: the number of key/value pairs removed.
196         */
197        public uint foreachSteal(GHRFunc func, void* userData)
198        {
199                return g_hash_table_foreach_steal(gHashTable, func, userData);
200        }
201
202        /**
203         * Retrieves every key inside @hash_table. The returned data is valid
204         * until changes to the hash release those keys.
205         *
206         * This iterates over every entry in the hash table to build its return value.
207         * To iterate over the entries in a #GHashTable more efficiently, use a
208         * #GHashTableIter.
209         *
210         * Returns: a #GList containing all the keys inside the hash
211         *     table. The content of the list is owned by the hash table and
212         *     should not be modified or freed. Use g_list_free() when done
213         *     using the list.
214         *
215         * Since: 2.14
216         */
217        public ListG getKeys()
218        {
219                auto p = g_hash_table_get_keys(gHashTable);
220               
221                if(p is null)
222                {
223                        return null;
224                }
225               
226                return new ListG(cast(GList*) p);
227        }
228
229        /**
230         * Retrieves every key inside @hash_table, as an array.
231         *
232         * The returned array is %NULL-terminated but may contain %NULL as a
233         * key.  Use @length to determine the true length if it's possible that
234         * %NULL was used as the value for a key.
235         *
236         * Note: in the common case of a string-keyed #GHashTable, the return
237         * value of this function can be conveniently cast to (const gchar **).
238         *
239         * This iterates over every entry in the hash table to build its return value.
240         * To iterate over the entries in a #GHashTable more efficiently, use a
241         * #GHashTableIter.
242         *
243         * You should always free the return result with g_free().  In the
244         * above-mentioned case of a string-keyed hash table, it may be
245         * appropriate to use g_strfreev() if you call g_hash_table_steal_all()
246         * first to transfer ownership of the keys.
247         *
248         * Returns: a
249         *     %NULL-terminated array containing each key from the table.
250         *
251         * Since: 2.40
252         */
253        public void*[] getKeysAsArray()
254        {
255                uint length;
256               
257                auto p = g_hash_table_get_keys_as_array(gHashTable, &length);
258               
259                return p[0 .. length];
260        }
261
262        /**
263         * Retrieves every value inside @hash_table. The returned data
264         * is valid until @hash_table is modified.
265         *
266         * This iterates over every entry in the hash table to build its return value.
267         * To iterate over the entries in a #GHashTable more efficiently, use a
268         * #GHashTableIter.
269         *
270         * Returns: a #GList containing all the values inside the hash
271         *     table. The content of the list is owned by the hash table and
272         *     should not be modified or freed. Use g_list_free() when done
273         *     using the list.
274         *
275         * Since: 2.14
276         */
277        public ListG getValues()
278        {
279                auto p = g_hash_table_get_values(gHashTable);
280               
281                if(p is null)
282                {
283                        return null;
284                }
285               
286                return new ListG(cast(GList*) p);
287        }
288
289        /**
290         * Inserts a new key and value into a #GHashTable.
291         *
292         * If the key already exists in the #GHashTable its current
293         * value is replaced with the new value. If you supplied a
294         * @value_destroy_func when creating the #GHashTable, the old
295         * value is freed using that function. If you supplied a
296         * @key_destroy_func when creating the #GHashTable, the passed
297         * key is freed using that function.
298         *
299         * Params:
300         *     key = a key to insert
301         *     value = the value to associate with the key
302         *
303         * Returns: %TRUE if the key did not exist yet
304         */
305        public bool insert(void* key, void* value)
306        {
307                return g_hash_table_insert(gHashTable, key, value) != 0;
308        }
309
310        /**
311         * Looks up a key in a #GHashTable. Note that this function cannot
312         * distinguish between a key that is not present and one which is present
313         * and has the value %NULL. If you need this distinction, use
314         * g_hash_table_lookup_extended().
315         *
316         * Params:
317         *     key = the key to look up
318         *
319         * Returns: the associated value, or %NULL if the key is not found
320         */
321        public void* lookup(void* key)
322        {
323                return g_hash_table_lookup(gHashTable, key);
324        }
325
326        /**
327         * Looks up a key in the #GHashTable, returning the original key and the
328         * associated value and a #gboolean which is %TRUE if the key was found. This
329         * is useful if you need to free the memory allocated for the original key,
330         * for example before calling g_hash_table_remove().
331         *
332         * You can actually pass %NULL for @lookup_key to test
333         * whether the %NULL key exists, provided the hash and equal functions
334         * of @hash_table are %NULL-safe.
335         *
336         * Params:
337         *     lookupKey = the key to look up
338         *     origKey = return location for the original key, or %NULL
339         *     value = return location for the value associated with the key, or %NULL
340         *
341         * Returns: %TRUE if the key was found in the #GHashTable
342         */
343        public bool lookupExtended(void* lookupKey, void** origKey, void** value)
344        {
345                return g_hash_table_lookup_extended(gHashTable, lookupKey, origKey, value) != 0;
346        }
347
348        /**
349         * Creates a new #GHashTable with a reference count of 1.
350         *
351         * Hash values returned by @hash_func are used to determine where keys
352         * are stored within the #GHashTable data structure. The g_direct_hash(),
353         * g_int_hash(), g_int64_hash(), g_double_hash() and g_str_hash()
354         * functions are provided for some common types of keys.
355         * If @hash_func is %NULL, g_direct_hash() is used.
356         *
357         * @key_equal_func is used when looking up keys in the #GHashTable.
358         * The g_direct_equal(), g_int_equal(), g_int64_equal(), g_double_equal()
359         * and g_str_equal() functions are provided for the most common types
360         * of keys. If @key_equal_func is %NULL, keys are compared directly in
361         * a similar fashion to g_direct_equal(), but without the overhead of
362         * a function call.
363         *
364         * Params:
365         *     hashFunc = a function to create a hash value from a key
366         *     keyEqualFunc = a function to check two keys for equality
367         *
368         * Returns: a new #GHashTable
369         *
370         * Throws: ConstructionException GTK+ fails to create the object.
371         */
372        public this(GHashFunc hashFunc, GEqualFunc keyEqualFunc)
373        {
374                auto p = g_hash_table_new(hashFunc, keyEqualFunc);
375               
376                if(p is null)
377                {
378                        throw new ConstructionException("null returned by new");
379                }
380               
381                this(cast(GHashTable*) p);
382        }
383
384        /**
385         * Creates a new #GHashTable like g_hash_table_new() with a reference
386         * count of 1 and allows to specify functions to free the memory
387         * allocated for the key and value that get called when removing the
388         * entry from the #GHashTable.
389         *
390         * Since version 2.42 it is permissible for destroy notify functions to
391         * recursively remove further items from the hash table. This is only
392         * permissible if the application still holds a reference to the hash table.
393         * This means that you may need to ensure that the hash table is empty by
394         * calling g_hash_table_remove_all before releasing the last reference using
395         * g_hash_table_unref().
396         *
397         * Params:
398         *     hashFunc = a function to create a hash value from a key
399         *     keyEqualFunc = a function to check two keys for equality
400         *     keyDestroyFunc = a function to free the memory allocated for the key
401         *         used when removing the entry from the #GHashTable, or %NULL
402         *         if you don't want to supply such a function.
403         *     valueDestroyFunc = a function to free the memory allocated for the
404         *         value used when removing the entry from the #GHashTable, or %NULL
405         *         if you don't want to supply such a function.
406         *
407         * Returns: a new #GHashTable
408         *
409         * Throws: ConstructionException GTK+ fails to create the object.
410         */
411        public this(GHashFunc hashFunc, GEqualFunc keyEqualFunc, GDestroyNotify keyDestroyFunc, GDestroyNotify valueDestroyFunc)
412        {
413                auto p = g_hash_table_new_full(hashFunc, keyEqualFunc, keyDestroyFunc, valueDestroyFunc);
414               
415                if(p is null)
416                {
417                        throw new ConstructionException("null returned by new_full");
418                }
419               
420                this(cast(GHashTable*) p);
421        }
422
423        /**
424         * Atomically increments the reference count of @hash_table by one.
425         * This function is MT-safe and may be called from any thread.
426         *
427         * Returns: the passed in #GHashTable
428         *
429         * Since: 2.10
430         */
431        public HashTable doref()
432        {
433                auto p = g_hash_table_ref(gHashTable);
434               
435                if(p is null)
436                {
437                        return null;
438                }
439               
440                return new HashTable(cast(GHashTable*) p);
441        }
442
443        /**
444         * Removes a key and its associated value from a #GHashTable.
445         *
446         * If the #GHashTable was created using g_hash_table_new_full(), the
447         * key and value are freed using the supplied destroy functions, otherwise
448         * you have to make sure that any dynamically allocated values are freed
449         * yourself.
450         *
451         * Params:
452         *     key = the key to remove
453         *
454         * Returns: %TRUE if the key was found and removed from the #GHashTable
455         */
456        public bool remove(void* key)
457        {
458                return g_hash_table_remove(gHashTable, key) != 0;
459        }
460
461        /**
462         * Removes all keys and their associated values from a #GHashTable.
463         *
464         * If the #GHashTable was created using g_hash_table_new_full(),
465         * the keys and values are freed using the supplied destroy functions,
466         * otherwise you have to make sure that any dynamically allocated
467         * values are freed yourself.
468         *
469         * Since: 2.12
470         */
471        public void removeAll()
472        {
473                g_hash_table_remove_all(gHashTable);
474        }
475
476        /**
477         * Inserts a new key and value into a #GHashTable similar to
478         * g_hash_table_insert(). The difference is that if the key
479         * already exists in the #GHashTable, it gets replaced by the
480         * new key. If you supplied a @value_destroy_func when creating
481         * the #GHashTable, the old value is freed using that function.
482         * If you supplied a @key_destroy_func when creating the
483         * #GHashTable, the old key is freed using that function.
484         *
485         * Params:
486         *     key = a key to insert
487         *     value = the value to associate with the key
488         *
489         * Returns: %TRUE if the key did not exist yet
490         */
491        public bool replace(void* key, void* value)
492        {
493                return g_hash_table_replace(gHashTable, key, value) != 0;
494        }
495
496        /**
497         * Returns the number of elements contained in the #GHashTable.
498         *
499         * Returns: the number of key/value pairs in the #GHashTable.
500         */
501        public uint size()
502        {
503                return g_hash_table_size(gHashTable);
504        }
505
506        /**
507         * Removes a key and its associated value from a #GHashTable without
508         * calling the key and value destroy functions.
509         *
510         * Params:
511         *     key = the key to remove
512         *
513         * Returns: %TRUE if the key was found and removed from the #GHashTable
514         */
515        public bool steal(void* key)
516        {
517                return g_hash_table_steal(gHashTable, key) != 0;
518        }
519
520        /**
521         * Removes all keys and their associated values from a #GHashTable
522         * without calling the key and value destroy functions.
523         *
524         * Since: 2.12
525         */
526        public void stealAll()
527        {
528                g_hash_table_steal_all(gHashTable);
529        }
530
531        /**
532         * Atomically decrements the reference count of @hash_table by one.
533         * If the reference count drops to 0, all keys and values will be
534         * destroyed, and all memory allocated by the hash table is released.
535         * This function is MT-safe and may be called from any thread.
536         *
537         * Since: 2.10
538         */
539        public void unref()
540        {
541                g_hash_table_unref(gHashTable);
542        }
543
544        /**
545         * Compares two #gpointer arguments and returns %TRUE if they are equal.
546         * It can be passed to g_hash_table_new() as the @key_equal_func
547         * parameter, when using opaque pointers compared by pointer value as
548         * keys in a #GHashTable.
549         *
550         * This equality function is also appropriate for keys that are integers
551         * stored in pointers, such as `GINT_TO_POINTER (n)`.
552         *
553         * Params:
554         *     v1 = a key
555         *     v2 = a key to compare with @v1
556         *
557         * Returns: %TRUE if the two keys match.
558         */
559        public static bool directEqual(void* v1, void* v2)
560        {
561                return g_direct_equal(v1, v2) != 0;
562        }
563
564        /**
565         * Converts a gpointer to a hash value.
566         * It can be passed to g_hash_table_new() as the @hash_func parameter,
567         * when using opaque pointers compared by pointer value as keys in a
568         * #GHashTable.
569         *
570         * This hash function is also appropriate for keys that are integers
571         * stored in pointers, such as `GINT_TO_POINTER (n)`.
572         *
573         * Params:
574         *     v = a #gpointer key
575         *
576         * Returns: a hash value corresponding to the key.
577         */
578        public static uint directHash(void* v)
579        {
580                return g_direct_hash(v);
581        }
582
583        /**
584         * Compares the two #gdouble values being pointed to and returns
585         * %TRUE if they are equal.
586         * It can be passed to g_hash_table_new() as the @key_equal_func
587         * parameter, when using non-%NULL pointers to doubles as keys in a
588         * #GHashTable.
589         *
590         * Params:
591         *     v1 = a pointer to a #gdouble key
592         *     v2 = a pointer to a #gdouble key to compare with @v1
593         *
594         * Returns: %TRUE if the two keys match.
595         *
596         * Since: 2.22
597         */
598        public static bool doubleEqual(void* v1, void* v2)
599        {
600                return g_double_equal(v1, v2) != 0;
601        }
602
603        /**
604         * Converts a pointer to a #gdouble to a hash value.
605         * It can be passed to g_hash_table_new() as the @hash_func parameter,
606         * It can be passed to g_hash_table_new() as the @hash_func parameter,
607         * when using non-%NULL pointers to doubles as keys in a #GHashTable.
608         *
609         * Params:
610         *     v = a pointer to a #gdouble key
611         *
612         * Returns: a hash value corresponding to the key.
613         *
614         * Since: 2.22
615         */
616        public static uint doubleHash(void* v)
617        {
618                return g_double_hash(v);
619        }
620
621        /**
622         * Compares the two #gint64 values being pointed to and returns
623         * %TRUE if they are equal.
624         * It can be passed to g_hash_table_new() as the @key_equal_func
625         * parameter, when using non-%NULL pointers to 64-bit integers as keys in a
626         * #GHashTable.
627         *
628         * Params:
629         *     v1 = a pointer to a #gint64 key
630         *     v2 = a pointer to a #gint64 key to compare with @v1
631         *
632         * Returns: %TRUE if the two keys match.
633         *
634         * Since: 2.22
635         */
636        public static bool int64Equal(void* v1, void* v2)
637        {
638                return g_int64_equal(v1, v2) != 0;
639        }
640
641        /**
642         * Converts a pointer to a #gint64 to a hash value.
643         *
644         * It can be passed to g_hash_table_new() as the @hash_func parameter,
645         * when using non-%NULL pointers to 64-bit integer values as keys in a
646         * #GHashTable.
647         *
648         * Params:
649         *     v = a pointer to a #gint64 key
650         *
651         * Returns: a hash value corresponding to the key.
652         *
653         * Since: 2.22
654         */
655        public static uint int64Hash(void* v)
656        {
657                return g_int64_hash(v);
658        }
659
660        /**
661         * Compares the two #gint values being pointed to and returns
662         * %TRUE if they are equal.
663         * It can be passed to g_hash_table_new() as the @key_equal_func
664         * parameter, when using non-%NULL pointers to integers as keys in a
665         * #GHashTable.
666         *
667         * Note that this function acts on pointers to #gint, not on #gint
668         * directly: if your hash table's keys are of the form
669         * `GINT_TO_POINTER (n)`, use g_direct_equal() instead.
670         *
671         * Params:
672         *     v1 = a pointer to a #gint key
673         *     v2 = a pointer to a #gint key to compare with @v1
674         *
675         * Returns: %TRUE if the two keys match.
676         */
677        public static bool intEqual(void* v1, void* v2)
678        {
679                return g_int_equal(v1, v2) != 0;
680        }
681
682        /**
683         * Converts a pointer to a #gint to a hash value.
684         * It can be passed to g_hash_table_new() as the @hash_func parameter,
685         * when using non-%NULL pointers to integer values as keys in a #GHashTable.
686         *
687         * Note that this function acts on pointers to #gint, not on #gint
688         * directly: if your hash table's keys are of the form
689         * `GINT_TO_POINTER (n)`, use g_direct_hash() instead.
690         *
691         * Params:
692         *     v = a pointer to a #gint key
693         *
694         * Returns: a hash value corresponding to the key.
695         */
696        public static uint intHash(void* v)
697        {
698                return g_int_hash(v);
699        }
700
701        /**
702         * Compares two strings for byte-by-byte equality and returns %TRUE
703         * if they are equal. It can be passed to g_hash_table_new() as the
704         * @key_equal_func parameter, when using non-%NULL strings as keys in a
705         * #GHashTable.
706         *
707         * Note that this function is primarily meant as a hash table comparison
708         * function. For a general-purpose, %NULL-safe string comparison function,
709         * see g_strcmp0().
710         *
711         * Params:
712         *     v1 = a key
713         *     v2 = a key to compare with @v1
714         *
715         * Returns: %TRUE if the two keys match
716         */
717        public static bool strEqual(void* v1, void* v2)
718        {
719                return g_str_equal(v1, v2) != 0;
720        }
721
722        /**
723         * Converts a string to a hash value.
724         *
725         * This function implements the widely used "djb" hash apparently
726         * posted by Daniel Bernstein to comp.lang.c some time ago.  The 32
727         * bit unsigned hash value starts at 5381 and for each byte 'c' in
728         * the string, is updated: `hash = hash * 33 + c`. This function
729         * uses the signed value of each byte.
730         *
731         * It can be passed to g_hash_table_new() as the @hash_func parameter,
732         * when using non-%NULL strings as keys in a #GHashTable.
733         *
734         * Note that this function may not be a perfect fit for all use cases.
735         * For example, it produces some hash collisions with strings as short
736         * as 2.
737         *
738         * Params:
739         *     v = a string key
740         *
741         * Returns: a hash value corresponding to the key
742         */
743        public static uint strHash(void* v)
744        {
745                return g_str_hash(v);
746        }
747}
Note: See TracBrowser for help on using the repository browser.