Top | ![]() |
![]() |
![]() |
![]() |
A map type for that maps keys from one GType to values of another GType using hashing.
See egg_dbus_hash_map_new()
for details.
By default, the map takes ownership when inserting key/value pairs meaning that the programmer gives
up his references. Values looked up from the map are owned by the array. There is also convenience
API to get a copy of the value, see egg_dbus_hash_map_lookup_copy()
.
Note that this class exposes a number of implementation details directly in the class instance structure for efficient and convenient access when used from the C programming language. Use with caution. For the same reasons, this class also provides a number of convenience functions for dealing with fixed-size integral and floating point numbers.
gboolean (*EggDBusHashMapForeachFunc) (EggDBusHashMap *hash_map
,gpointer key
,gpointer value
,gpointer user_data
);
Type of callback function passed to egg_dbus_hash_map_foreach()
.
hash_map |
The map being iterated over. |
|
key |
A key. |
|
value |
Value corresponding to |
|
user_data |
User data passed to |
EggDBusHashMap * egg_dbus_hash_map_new (GType key_type
,GDestroyNotify key_free_func
,GType value_type
,GDestroyNotify value_free_func
);
Creates a new hash map for mapping keys of type key_type
to values of type value_type
.
See egg_dbus_hash_map_new_full()
for a more complicated version of this function.
EggDBusHashMap * egg_dbus_hash_map_new_full (GType key_type
,GHashFunc key_hash_func
,GEqualFunc key_equal_func
,GDestroyNotify key_free_func
,GBoxedCopyFunc key_copy_func
,GType value_type
,GDestroyNotify value_free_func
,GBoxedCopyFunc value_copy_func
,GEqualFunc value_equal_func
);
Creates a new hash map for mapping keys of type key_type
to values of type value_type
.
The map will use key_free_func
and value_free_func
to free keys and values respectively.
If either of these functions are NULL
, it's the responsibility of the owner to make sure
any keys or values inserted into the map are freed.
If either of key_hash_func
or key_equal_func
is NULL
a default hash or equality function
will be used if one such exists (for example one exists for G_TYPE_STRING, G_TYPE_INT and
so on). If a hash or equality function wasn't given and no default hash function exists, it
is a programming error and a warning will be reported using g_error()
(causing program
termination).
If either of key_copy_func
or value_copy_func
is NULL
default copy functions will be used
if available (for example there is no default copy function for G_TYPE_POINTER or
derived types). Note that optional methods such as egg_dbus_hash_map_lookup_copy()
won't work if there is no value copy function.
Normally the hash map stores pointers to both key and values and the methods taking and
returning keys or values will also take pointers to keys or values. However, for fixed-size integral
types that fits in a pointer (such as G_TYPE_INT or G_TYPE_BOOLEAN), the key or value is stored
in the pointer to avoid allocating memory. Typically this is not something you need to care about
as such implementation details are hidden behind convenience API like egg_dbus_hash_map_insert_fixed_ptr()
or egg_dbus_hash_map_lookup_fixed()
.
Note that it is a programming error to pass a free function for fixed-size types (e.g. integral
or floating point types); a warning will be reported using g_error()
(causing program termination).
key_type |
The type of the keys in the map. |
|
key_hash_func |
Hash function for keys or |
|
key_equal_func |
Function to compare keys or |
|
key_free_func |
Function to be used to free keys or |
|
key_copy_func |
Function to copy keys or |
|
value_type |
The type of the values in the map. |
|
value_free_func |
Function to be used to free values or |
|
value_copy_func |
Function to copy values or |
|
value_equal_func |
Function to compare values or |
guint
egg_dbus_hash_map_get_size (EggDBusHashMap *hash_map
);
Gets the number of key/value pairs in hash_map
.
GType
egg_dbus_hash_map_get_key_type (EggDBusHashMap *hash_map
);
Gets the type of the keys in hash_map
.
GType
egg_dbus_hash_map_get_value_type (EggDBusHashMap *hash_map
);
Gets the type of the values in hash_map
.
void
egg_dbus_hash_map_clear (EggDBusHashMap *hash_map
);
Removes all key/value pairs from hash_map
.
void egg_dbus_hash_map_insert (EggDBusHashMap *hash_map
,gconstpointer key
,gconstpointer value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
If a value_free_func
was supplied when creating hash_map
, the old value is freed using
that function. If a key_free_func
was supplied when creating hash_map
, the passed key
is freed using that function.
gboolean egg_dbus_hash_map_contains (EggDBusHashMap *hash_map
,gconstpointer key
);
Checks if hash_map
contains a value for key
.
gpointer egg_dbus_hash_map_lookup (EggDBusHashMap *hash_map
,gconstpointer key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value NULL
. If you need this distinction, use egg_dbus_hash_map_contains()
.
Note that the returned value is owned by hash_map
and may be invalid if
later removed from the map. If you want a copy, use egg_dbus_hash_map_lookup_copy()
instead.
gpointer egg_dbus_hash_map_lookup_copy (EggDBusHashMap *hash_map
,gconstpointer key
);
Like egg_dbus_hash_map_lookup()
but returns a copy of the value.
This method is optional as some value types (for example G_TYPE_POINTER
and derived types) have no natural copy function and one might not have been set when hash_map
was constructed. It is a programming error to call this method on hash_map
if there
is no value copy function on hash_map
(a warning will be printed using g_error()
causing program
termination).
gboolean egg_dbus_hash_map_remove (EggDBusHashMap *hash_map
,gconstpointer key
);
Removes a key and it associated value from hash_map
.
If a value_free_func
was supplied when creating hash_map
, the value is freed using
that function. If a key_free_func
was supplied when creating hash_map
, the key in
the map is freed using that function.
gboolean egg_dbus_hash_map_foreach (EggDBusHashMap *hash_map
,EggDBusHashMapForeachFunc func
,gpointer user_data
);
Calls func
for each of the key/value pairs in hash_map
. The function is passed the key and
value of each pair, and the given user_data
parameter. The map may not be modified while iterating
over it (you can't add/remove items).
gboolean egg_dbus_hash_map_contains_fixed (EggDBusHashMap *hash_map
,guint64 key
);
Checks if hash_map
contains a value for key
.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gboolean egg_dbus_hash_map_contains_float (EggDBusHashMap *hash_map
,gdouble key
);
Checks if hash_map
contains a value for key
.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
gpointer egg_dbus_hash_map_lookup_fixed (EggDBusHashMap *hash_map
,guint64 key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value NULL
. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gpointer egg_dbus_hash_map_lookup_float (EggDBusHashMap *hash_map
,gdouble key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value NULL
. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
gpointer egg_dbus_hash_map_lookup_fixed_copy (EggDBusHashMap *hash_map
,guint64 key
);
Like egg_dbus_hash_map_lookup_fixed()
but returns a copy of the value.
This method is optional as some value types (for example G_TYPE_POINTER
and derived types) have no natural copy function and one might not have been set when hash_map
was constructed. It is a programming error to call this method on hash_map
if there
is no value copy function on hash_map
(a warning will be printed using g_error()
causing program
termination).
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gpointer egg_dbus_hash_map_lookup_float_copy (EggDBusHashMap *hash_map
,gdouble key
);
Like egg_dbus_hash_map_lookup_float()
but returns a copy of the value.
This method is optional as some value types (for example G_TYPE_POINTER
and derived types) have no natural copy function and one might not have been set when hash_map
was constructed. It is a programming error to call this method on hash_map
if there
is no value copy function on hash_map
(a warning will be printed using g_error()
causing program
termination).
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
guint64 egg_dbus_hash_map_lookup_ptr_fixed (EggDBusHashMap *hash_map
,gconstpointer key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the value type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gdouble egg_dbus_hash_map_lookup_ptr_float (EggDBusHashMap *hash_map
,gconstpointer key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0.0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the value type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
guint64 egg_dbus_hash_map_lookup_fixed_fixed (EggDBusHashMap *hash_map
,guint64 key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when both the key and value types are integral types (G_TYPE_INT, G_TYPE_UINT64 and so on).
gdouble egg_dbus_hash_map_lookup_fixed_float (EggDBusHashMap *hash_map
,guint64 key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0.0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on) and value type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
guint64 egg_dbus_hash_map_lookup_float_fixed (EggDBusHashMap *hash_map
,gdouble key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE) and the value type is an integral type type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gdouble egg_dbus_hash_map_lookup_float_float (EggDBusHashMap *hash_map
,gdouble key
);
Looks up the value associated with key
in hash_map
. Note that this function
cannot distinguish between a key that is not present and one which is present
but has the value 0.0. If you need this distinction, use egg_dbus_hash_map_contains()
.
This is a C convenience function for when both the key and value type are floating point types (G_TYPE_FLOAT and G_TYPE_DOUBLE).
gboolean egg_dbus_hash_map_remove_fixed (EggDBusHashMap *hash_map
,guint64 key
);
Removes a key and it associated value from hash_map
.
If a value_free_func
was supplied when creating hash_map
, the value is freed using
that function.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
gboolean egg_dbus_hash_map_remove_float (EggDBusHashMap *hash_map
,gdouble key
);
Removes a key and it associated value from hash_map
.
If a value_free_func
was supplied when creating hash_map
, the value is freed using
that function.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
void egg_dbus_hash_map_insert_ptr_fixed (EggDBusHashMap *hash_map
,gconstpointer key
,guint64 value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
If a key_free_func
was supplied when creating hash_map
, the passed key
is freed using that function.
This is a C convenience function for when the value type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
void egg_dbus_hash_map_insert_ptr_float (EggDBusHashMap *hash_map
,gconstpointer key
,gdouble value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
If a key_free_func
was supplied when creating hash_map
, the passed key
is freed using that function.
This is a C convenience function for when the value type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
void egg_dbus_hash_map_insert_fixed_ptr (EggDBusHashMap *hash_map
,guint64 key
,gconstpointer value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
If a value_free_func
was supplied when creating hash_map
, the old value is freed using
that function.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on).
void egg_dbus_hash_map_insert_fixed_fixed (EggDBusHashMap *hash_map
,guint64 key
,guint64 value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
This is a C convenience function for when both the key and value types are integral types (G_TYPE_INT, G_TYPE_UINT64 and so on).
void egg_dbus_hash_map_insert_fixed_float (EggDBusHashMap *hash_map
,guint64 key
,gdouble value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
This is a C convenience function for when the key type is an integral type (G_TYPE_INT, G_TYPE_UINT64 and so on) and value type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
void egg_dbus_hash_map_insert_float_ptr (EggDBusHashMap *hash_map
,gdouble key
,gconstpointer value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
If a value_free_func
was supplied when creating hash_map
, the old value is freed using
that function.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE).
void egg_dbus_hash_map_insert_float_fixed (EggDBusHashMap *hash_map
,gdouble key
,guint64 value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
This is a C convenience function for when the key type is a floating point type (G_TYPE_FLOAT and G_TYPE_DOUBLE) and the value type is an integral type type (G_TYPE_INT, G_TYPE_UINT64 and so on).
void egg_dbus_hash_map_insert_float_float (EggDBusHashMap *hash_map
,gdouble key
,gdouble value
);
Inserts a new key and value into hash_map
.
If the key already exists in the hash_map
its current value is replaced with the new value.
This is a C convenience function for when both the key and value type are floating point types (G_TYPE_FLOAT and G_TYPE_DOUBLE).
typedef struct { GType key_type; GType value_type; GHashTable *data; } EggDBusHashMap;
The EggDBusHashMap instance structure should normally not be accessed directly, use accessor functions instead. Certain instance members are provided only for efficient and convenient access when using the C programming language. Use with caution.